KB User's Guide - API - Using JavaScript to Embed KB Content

This document provides an example of JavaScript that can be used to embed some or all of a KB document in another webpage, such as a page in a WordPress website.

What Can I Display Using the API?

To embed KB document content, we will be using the Articles API. The technical details for this API service can be found here: KB User's Guide - API - Articles

The following key content areas are all passed through the Articles API can be included as desired:

  • Doc ID
  • Title
  • Keywords
  • PageHeader
  • Summary
  • Body
  • PageFooter

Other pieces of data that can be displayed via the API as needed are:

  • Alert **
  • Owner
  • Last Updater
  • Date/time of creation
  • Date/time of last update
  • Date/time of last review
  • Date/time of activation
  • Date/time of expiration
  • OwnerGroup

** This field will only be applicable if you are using the KB's dynamic content replacement feature on a document owned by another group.

How Do I Display It On My Website?

  1. First, you will want to decide exactly what content from your KB document you would like to display on your website. You will also need to know how these fields are represented within the API, as those are the names you will reference later on. The below table shows how the fields listed above are named in the API:

    Name in KB Admin Tools Name in API
    Doc ID id
    Title title
    Keywords keywords
    PageHeader header
    Summary summary
    Body body
    PageFooter footer
    Name in KB Admin Tools Name in API
    Alert banner alert
    Owner owner
    LastUpdater updater
    Created created
    Updated updated
    Reviewed reviewed
    Activation activation
    Expiration expiration
    Group ownerGroup

  2. If your website does not currently load a jQuery file, insert the following within the <head> tag of your website (or wherever you have been instructed to enter JavaScript):

    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

  3. Just below this (still inside the <head> tag), you will add some custom JavaScript that will:

    1. call the desired article
    2. pull the content from the fields you specify
    3. insert that content into an HTML element with a specified ID or class
    4. display an error message if the API call fails for any reason

    In the example below, we are:

    1. calling the KB document 79005, which is available under https://kb.wisc.edu/test/
    2. returning the content (referred to as "data" in JavaScript) from the title, body, and created fields
    3. placing the data into HTML elements with the IDs kb-title, kb-body, and kb-created, repectively
    4. inserting an error message into the kb-body element if the KB document fails to load

    Only the highlighted text will vary with your specific use (though you may have more or fewer than three lines referencing the fields and elements, depending on how much or how little of the document data you plan to display).

    $(document).ready(function() {

    $.ajax({

        url: "https://kb.wisc.edu/test/api/v1/articles/79005"

    }).then(function(data) {

       $('#kb-title').append(data.title);

       $('#kb-body').append(data.body);

       $('#kb-created').append(data.created);

    });

    $( document ).ajaxError(function() {

       $('#kb-body').append("<h3>Something seems to have gone wrong...</h3><p>Please report the issue by clicking the <strong>Contact Us</strong> link at the bottom of page, and we'll make it right. Thank you!</p>")

    }); 

});

  4. In the <body> of your webpage, locate the exact place where you would like to embed your content. Then, insert the desired elements with the classes or IDs you referenced in your JavaScript. These elements should essentially be empty HTML tags; when the page loads, the data from the API will load inside of them.

    Using the above example, we will place the title in a Heading 2 (<h2>) tag, the body in a divider (<div>) tag, and the created date into a paragraph (<p>) tag.

        <body>

      <h2 id="kb-title"></h2>

      <div id="kb-body"></div>

      <p id="kb-created"></p>

    </body>

  5. When put together, the code for the entire webpage would look something like this:

    
<!DOCTYPE html>

<html>

  <head>

    <title>Webpage Title</title>

    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

    <script>

      $(document).ready(function() {

        $.ajax({

          url: "https://kb.wisc.edu/test/api/v1/articles/79005"

        }).then(function(data) {

          $('#kb-title').append(data.title);

          $('#kb-body').append(data.body);

          $('#kb-created').append(data.created);

        });

        $( document ).ajaxError(function() {
        
          $('#description').append("<h3>Something seems to have gone wrong...</h3><p>Please report the issue by clicking the <strong>Comment</strong> button below, and we'll make it right. Thank you!</p>")
     
        });

      });

    </script>

  </head>

  <body>

    <h2 id="kb-title"></h2>

    <div id="kb-body"></div>

    <p id="kb-created"></p>

  </body>

</html>

    And the resulting content on the page would be displayed as follows:

    6. What Would This Look Like On Another Website?

    In practice, you can embed one or more KB documents throughout a much more robust webpage.

    To see an example of how KB document content (in this case, content from three different documents) can be embedded within the broader context of an external webpage, open the following page in your browser: My Official Service Website

    See Also:



Keywords:json ajax dynamically restful calls embedding displaying knowledgebase articles documents wordpress press website site webpages pages sections fields   Doc ID:81506
Owner:Leah S.Group:KB User's Guide
Created:2018-04-09 15:22 CDTUpdated:2018-12-20 18:15 CDT
Sites:KB User's Guide
Feedback:  1   0