Tutorial: Embed Kimono data on your site with HTML, CSS, and jQuery

Kimono has a lot of great integrations to help you easily embed your data on your site but sometimes, you want a little more control over how your data is displayed.

Here we will walk through an example to generate a formatted list of your data that you can use on any personal site. We will use HTML, CSS, and some basic jQuery (a Javascript framework). Once you're done, you'll be able to customize the list to your heart's content!

This tutorial is designed for people who are pretty new to coding on the web, but have a little bit of experience. We think it’s a great way to improve your front-end development chops while doing something interesting with your data. You won’t need to be totally familiar with everything we do here so just read along.

Your page will use jQuery to make an API call to Kimono to retrieve data from your API. Then it will append the data into the page as HTML elements. Finally, we’ll use Bootstrap, a CSS framework to style the page.

Requirements:

  • A Kimono API
  • Basic knowledge of HTML, CSS, and jQuery/javascript
  • A website with jQuery and Bootstrap included (easily done on JSFiddle!)

You can follow along with this guide using this sample Kimono API (or go straight to the raw JSON data), and take a look at the code on this JSFiddle

 

Embedding Data as a List

Using jQuery and the CSS framework, Bootstrap, you can create a customized list in just a few steps. Here’s the plan:

  1. Create an HTML list to hold your data
  2. Make a call to your Kimono API with jQuery
  3. Fill in your list from earlier with the data returned from Kimono

 

1) Create an HTML list to hold your data

You’re going to create a list panel using Bootstrap. This accomplishes two things: first, it gives you a place to store the data, and second, it gives you access to Bootstrap's awesomeness! Bootstrap is a CSS framework that will help you easily style your list.

To do this, first create a div with class "container padding." In html, this looks like this: 

<div class = “container padding”></div>

This puts the panel into an invisible padded container so it fits well on a site without taking up the whole page.

To make the panel itself, create a div (nested inside of your last div) with class = "panel panel-info." "panel-info" is a class that utilizes bootstrap to create the light blue color scheme.  (You can also try out panel-success, panel-warning, or panel-danger for different colors!)

Next is the "panel-heading," this is an empty div that your jQuery call will fill with the title of your API. Finally, create the list using the <ul> tag and class "list-group" to give it the rounded edges format of Bootstrap lists.

When you put it all together, you should have something like this:

 
<div class="container padding">
   <div class="panel panel-info">
      <div class="panel-heading"> </div>
         <ul class="list-group">
         </ul>
   </div>
</div> 

Note that right now, our list is empty - don't worry! We'll fill it in with data from our Kimono API in step 3. 

2) Make a call to your Kimono API with jQuery

Now that you’ve setup the HTML structure for your list, we are going to use jQuery to make a request to your Kimono API and retrieve the data for your list!

Kimono provides a jQuery sample code template in the API Docs of your API for this purpose. This snippet of code will provide a call to your specific API URL to get the data formatted in JSON (JSON is a data format that is very common on the web and easy to work with). Here is the JSON file for this example data:

{
  "name": "Hackernews-kimono-example",
  "count": 30,
  "frequency": "Manual Crawl",
  "version": 22,
  "newdata": true,
  "lastrunstatus": "success",
  "lastsuccess": "Fri Jan 16 2015 19:01:00 GMT+0000 (UTC)",
  "thisversionstatus": "success",
  "thisversionrun": "Fri Jan 16 2015 19:00:58 GMT+0000 (UTC)",
  "results": {
    "collection1": [
      {
        "property1": {
          "href": "https://research.facebook.com/blog/879898285375829/fair-open-sources-deep-l20earning-modules-for-torch/",
          "text": "Facebook open-sources deep-learning modules"
        }
      },
      {
        "property1": {
          "href": "https://vine.co/v/OjqeYWWpVWK",
          "text": "SpaceX: “Close, but no cigar. This time”"
        }
      },
      {
        "property1": {
          "href": "https://medium.com/message/back-to-the-future-time-travel-and-the-secret-history-of-the-1980s-80bf3c6347cf",
          "text": "Back to the Future, Time Travel, and the Secret History of the 1980s"
        }
      },
      {
        "property1": {
          "href": "http://www.nytimes.com/2015/01/17/science/earth/2014-was-hottest-year-on-record-surpassing-2010.html",
          "text": "2014 Was Hottest Year on Record, Surpassing 2010"
        }
      },
...

Now that we know what the Kimono data will look like, let's take a look at the jQuery call that will retrieve this data. The "$" at the beginning signifies that we are invoking jQuery on an object. Note that you can substitute the "$" with "jQuery" for clarity. The "ajax" method allows you to make this call asynchronously (this means that it will happen in the background without affecting the existing loaded page before you're ready for it). This is great if you’re embedding this block on a site that has other things on it already because you don't need to worry about this call affecting anything else.

After the data request, you want a function that reacts to whether or not the retrieval was successful (sometimes, calls will fail for a variety of reasons - it could be internet connectivity,  server issues, or a variety of other things). This is important because sometimes you might run into an error, in which case you can either handle the error or just do nothing. To create a function that will run only if your data was retrieved, begin with a 'success' function that takes in a "response" argument (the data response from the ajax request).

$.ajax({
   "url":"https://www.kimonolabs.com/api/5qtdkod0? 
apikey=z6vewKq5SXBcF6Q6L17sQEJ8gaYMou0C", "crossDomain":true, "dataType":"jsonp", success: function(response) { console.log(response); }, });

Included in this example code is a success function that will simply print the dataset using the method “console.log”. However, you will want a function that doesn’t just return the whole dataset, but rather, specific elements and properties you are interested in! The next step will teach you how to write a selective function to do this.

 

3) Fill in your list from earlier with the data returned from Kimono

Now that you've created an empty list and made a request for your data, you can populate the list using your newly returned data. This part is a little bit tricky so take your time to get the syntax just right. There are two pieces of data this function will append to your list: 1) the title of your API and 2) the actual elements of data themselves.

Now, rewrite your success function from before to actually append the data to your page. The body of the success function should first select the name of the API from the dataset and then apply it to the "panel-heading" div you created earlier.

To select the name of the api, you can reference the 'name' property of the api. This is done using 'response.name.'

Next, using the ".html" method, you'll replace the content of anything within the "panel-heading" class with "response.name", so that this panel displays our api name. Here's what the beginning of your function should look like.

'success': function(response){
   $(".panel-heading").html(response.name);

You’re doing two things here. First, you’re saying go find class “panel heading” and put something into the html that’s there. Then, you’re saying, put the value of response.name ( the title of your api) into that html.

The next part of the function will iterate through every element of the data you want to display. You'll do this with a for loop and then append each element from your list to the empty list you created in step 1.

Create a "collection" variable that will represents the data from collection1. This helps keep your code clean and readable.

Then implement a for loop which works as a counter to keep track of going through each element in your data.  "Var i = 0" sets the variable i to 0, "i < collection.length" tells the for loop to only run while "i", the counter, is less than the length of the collection, and "i++" is shorthand for i = i +1 which will increase your counter by 1 until the loop is told to stop.    

var collection = response.results.collection1;
for (var i = 0; i < collection.length; i++){

Inside the for loop, you can append the list with each element using the method ".append" to add items into anything with the class "list-group." This is similar to “.html()” except that now you are adding a new element entirely, rather than changing the content of an element as we did with the title. Also, this means that the new element is inserted after the element we target with our selector.

Each item you are adding should be formatted with HTML tags so that it will work properly with your empty HTML list. Use the <li> tag for list items and the class "list-group-item" that will get CSS applied by bootstrap to adjust the look of each item.

Sandwiched in these tags should be the element which you can select using "collection[i].property1.text". "collection[i]" will use the "i" counter to index each entry of the collection one at a time during every iteration of the for loop and "property1.text" will select for the "text" element nested inside "property1". (You may need to tweak this based on how your API is set up)

$(".list-group").append('<li class="list-group-item">' + collection[i].property1.text + '</li>'); 

 

Putting it All Together 

<!-- HTML -->
<div class="container padding">    <div class="panel panel-info">       <div class="panel-heading"> </div>       <ul class="list-group">       </ul>    </div> </div> 
//jQuery
$.ajax({ "url":"https://www.kimonolabs.com/api/5qtdkod0apikey=z6vewKq5SXBcF6Q6L17sQEJ8gaYMou0C", "crossDomain":true, "dataType":"jsonp", //Make a call to the Kimono API following the "url"
'success': function(response){ // If the call request was successful and the data was retrieved, this
function will create a list displaying the data
$(".panel-heading").html(response.name); //Puts the API name into the panel heading
var collection = response.results.collection1; for (var i = 0; i < collection.length; i++){ // Traverses through every element in the entire collection
$(".list-group").append('<li class="list-group-item">' +
collection[i].property1.text + '</li>'); // adds the text and the links from the first property into the
list } } });

You should now have a functional script to embed data into your site. Hooray! To get here, you've created an empty list in a panel with HTML, then created a script that makes a call to your Kimono API and inputs the name and elements from the retrieved data into this list.

 

If you are seeking a more complex data display with multiple properties, take a look at our example for building a table using the same methods as this list script.

 

Powered by Zendesk