2016-04-07

JavaScript Libraries and APIs

If you have written JavaScript for the DOM before, then you probably know how unwieldy it can get. I mean getElementById is seven syllables and 14 characters long for goodness sake. Isn’t there an easier way?

Enter jQuery goodness. jQuery is a JavaScript library.

Library? Like the ones where I can check out books and rent 90s movies for free? No. A library in the programming sense is a codebase that simplifies coding logic and is freely available for anyone to use. No late fees!

That may not have made sense to you but I have examples.

Hypothetically speaking, let’s say that I want to change the background of a div to red. I gave that div an id of ‘red’ for simplicity sake. In JavaScript I would write something like this:

document.body.getElementById("red").style.backgroundColor = "red";

It works and gets the job done, which is all we really need. But now let’s take a look at that same functionality in jQuery.

$("#red").css("background-color", "red");

Wow, that’s pretty! It’s everything programmers strive for: a terse and concise solution.

Now you clearly see the benefits of jQuery. It’s intended to make programming in JavaScript easier.

But there are some drawbacks. You might think that jQuery can do everything, and that programming in jQuery is the same as in JavaScript. Both of those notions are wrong.

From my perspective, working with jQuery is like using Rails, the web development framework half of Ruby on Rails. You can get pretty far with using Rails without having to dive deep into learning Ruby.

However, my contention is, you can’t truly understand or appreciate JavaScript unless you predominantly use it to run your programs. That being said, there are some really great benefits to using jQuery for you to explore. The benefit we will discuss today is using jQuery to make API calls.

API huh? API stands for Application Programming Interface. That’s a big fancy acronym for ‘rules of engagement’.

Many software applications have a set of rules that govern how they interact with other programs. I am sure that made total sense to you, but I will give you some examples for good measure.

For example, if you want to add a paragraph to the body of an HTML page, you might write something like this:

var paragraph = document.body.createElement("P");
paragraph.textContent = "I am using an API, woohoo!";
document.body.appendChild(paragraph);

In the example above I used the following rules:

1. document.body to access the body object
2. createElement method to create an element
3. textContent method to insert text into that element
4. appendChild method to append that paragraph to the body

Here we would be using the DOM API. DOM stands for Document Object Model, and it’s the organization of HTML elements on a page.

In laymen’s terms, the DOM API “provides a structured representation” of a website. This becomes the entry point that allows programming languages to interact with the HTML of a page.

The DOM API is what provides the methods such as createElement and textContent so that you can use your fancy pants JavaScript to manipulate the DOM.

Did you notice I said programming languages? You can actually interact using any language, but you probably want to go with the de facto language of the web — JavaScript. I’m just saying.

Now that you have some context, let’s get into making a Giphy search app.

This will be fun! And I really mean it this time.

We’ll start out by looking at a response object. A response object is the data returned after a request has been made to an API.

Okay, let me break that down. When you type a URL into your search bar — such as eyeluvkats.com — and hit enter, a request is sent across the internet to a server that hosts the domain eyeluvkats.com.

Afterward, a response is sent back to the user with the contents of the website: HTML, CSS, JavaScript, images, videos, etc.

Now, instead of requesting eyeluvkats.com, we will put in a request to the Giphy API that will return a data object. That request will be:

http://api.giphy.com/v1/gifs/random?api_key=dc6zaTOxFJmzC&tag=cat

Your first API call! Woohoo!

The call here was made to the Giphy API and in the parameters of the URL, we requested a particular type of gif:

gifs/**random**?api_key=dc6zaTOxFJmzC&**tag=cat**

We requested a random cat gif using the random parameter, and the tag parameter of cat. I am such a millennial, sorry! What you should now see in your browser is a JSON object with data related to a random cat gif.

JSON stands for JavaScript Object Notation. It’s how JavaScript sends data across the web and is routinely used as the go-to response object for large sets of API data. Have you ever created a JSON object before? No? Let’s do that now so you know how objects work in JavaScript.

To create a JavaScript object, also known as an object literal, you can declare a variable to equal a pair of curly braces. For instance:

var object = {};

These objects are typically used to store data, so let’s go ahead and put your bio in there. Data in objects are stored as key/value pairs, i.e. firstName: ‘Adam’, separated with commas.

Go through now and add your other details like your birthday, social security number, and credit card number. When you’re done, send that object to adam@youjustgotscammed.com.

For me, my information would look like this:

var me = {
  firstName: "Adam",
  middleName: "Elliott",
  lastName: "Recvlohe",
  favoriteFood: "Chipotle",
  favoriteDrink: "Kombucha: Gingerade",
  race: "Human",
  favoriteVideo:
    "[https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ)",
};

That’s all well and good, but how do we access that information? Well, there are a couple ways of doing it. One way is with “dot notation” and the other is using “bracket notation”.

var me = {
  firstName: "Adam",
  middleName: "Elliott",
  lastName: "Recvlohe",
  favoriteFood: "Mexican",
  favoriteDrink: "Kombucha",
  race: "Human",
};

// Dot Notation
var myFirstName = me.firstName;

// Bracket Notation
var myLastName = me["lastName"];

Remember, as the object becomes more nested the more dots or brackets you will need.

var data = {
  address: {
    city: "Tampa",
    state: "Florida",
  },
};

var myCity = data.address.city;
var myState = data["address"]["state"];

Sidenote: The JSON standard requires object properties and values to be in double quotes. I showed you JavaScript object literals because the way that you access data from each is the same with the syntax of JSON being only slightly different.

Now that we have that out of the way, we can start handling the data in the JSON object, which we got back from hitting the Giphy API. The object is quite large, but all I really want is the URL to the random cat gif. How would I assign that URL to a variable? Since you’re still here I will show you how I would do it:

var gifURL = object.data.url;

This doesn’t do anything right now, but what I wanted to show you first is how we would handle the data to then manipulate it later.

We now have the basics down of handling a response object. Let’s move on to the real stuff of creating a function to call this data for us, and then manipulate that data on the screen.

Up to this point, we haven’t really needed CodePen, but we need it now. If you want to continue to follow along I suggest opening a codepen.io account and creating a new pen.

With your pen open, we need to do a couple things first to set the scene. We need to add the jQuery library to our pen. In the JavaScript tab, on the left of JavaScript, you should see a gear icon. That is the settings button. Click there and what should open next are your JavaScript settings. Underneath Add External JavaScript there is a drop-down bar called Quick-add. Select jQuery. Okay, now we are good to go.

When do we want to execute this call to the Giphy API? Well, by convention this is usually done when the document is ready. You probably would never have guessed that we will use the ready method in jQuery. It looks a little something like this:

$(document).ready(function () {});

In JavaScript, there are a few different stages in regards to content loading. There are interactive, complete, and a few others. All this is saying is that when the DOM is ready this function will be executed.

Try it! Refresh the browser with something unique, in the ready callback function like console.log(‘Hello, World!’).

$(document).ready(function () {
  console.log("Hello, World!");
});

If you look in your console, you should see printed Hello, World!.

At the bottom of your codepen window you should see the word console. Click on that button and you should see the console open.

jQuery comes with a lot of other handy functions. The next one we will need is the getJSON method. What this will do is return a response to us in JSON and give us a callback function to then do something with that data. That probably sounds a little arbitrary. Let me give you a concrete example.

$(document).ready(function () {
  var url = "http://api.giphy.com/v1/gifs/random?api_key=dc6zaTOxFJmzC&tag=cat";

  $.getJSON(url, function (object) {
    console.log(object);
  });
});

I bet you can’t guess what this does? Okay, you proved me wrong. Of course, you know the method getJSON is sending a request to url and being returned data that is then logged in the console. You sly devil you!

That’s nice and all but we can do one better. We can take that object and use the url property to place a gif in the DOM. Mind…Blown…Boom!

We are going to stick with using jQuery and create an image dynamically. To create an image in jQuery we can pass the image tag as a string with all necessary information like so:

var imageSource = object.data.image_original_url;
var image = $("<img src=" + imageSource + " />");

Now all we have to do is append that to the body of the DOM and we are good. Houston, all systems go!

$(document).ready(function () {
  var url = "http://api.giphy.com/v1/gifs/random?api_key=dc6zaTOxFJmzC&tag=cat";

  $.getJSON(url, function (object) {
    var imageSource = object.data.image_original_url;
    var image = $("<img src=" + imageSource + " />");
    image.appendTo($("body"));
  });
});

Here it is on codepen:

My Momma always said, “Life was like a Giphy app. You never know what you’re gonna get.” — JS Gump

Now every time you refresh the page you should get a new cat gif. You’re welcome!

We can add a bit more functionality to this. Instead of getting only a random cat every time, we can instead search for the gifs we want and display some on the page. That sounds way cooler.

Before we can do this we will need an input field. The input field will take your search term and add it as a parameter to the request that is sent to the Giphy API. In your HTML add an input field.

<input type="'text'" />

Up to this point, we have been making calls to the “random” API. This time, we want to search. I wonder what API that is? Oh I see, it’s called ‘search’. On Giphy’s home page we have a nice example URL:

http://api.giphy.com/v1/gifs/search?q=funny+cat&api_key=dc6zaTOxFJmzC

That’s a litter box worth of data! By default Giphy will return 25 results. As you can see in the URL the way these items are searched is using the q parameter, which in this case equals funny+cats. If we want to search for some other set of terms then all we would have to do is capture the input from the user and when they hit enter a new request is sent to the API. Let’s do that now.

To capture the input from the user we need to use the jQuery val method on the input.

$(document).ready(function () {
  var value = $("input").val();
});

But how do we actually get that value? We need to add an event listener so that when the user hits enter we can capture that value and send it off to the getJSON method. In jQuery, event listeners are also shorter. We will listen for the keypress event but only for the enter key, which is designated as 13. Remember that event listeners provide a callback function that passes in the event from the DOM. There is one little hiccup, though. The value that we get returned will be a string, meaning it won’t have the ’+’ operator between each word. Because jQuery is written in JavaScript this allows us to use vanilla JavaScript methods in our script. I will use the replace method to change out spaces with the ’+’ operator.

$(document).ready(function () {
  $("input").keypress(function (event) {
    if (event.which == 13) {
      var value = $("input").val();
      value = value.trim().replace(/s+/g, "+");
      console.log(value);
      event.preventDefault();
    }
  });
});

The replace method that is built into JavaScript takes two parameters: a regular expression and what you want a match to be replaced with. In my regular expression, I am using a special character, s. This represents white space. I added a ’+’ operator on the end to signify that I want to capture any number of white spaces in a string, s+. My thinking is a user may put more than one space between words and I want to correct that mistake if it happens.

This is a very primitive solution but for our purposes it works. If you look in your console, you should see your string text combined with ’+’ operators. Good, we got that down. Now we can compose a URL of the search API and the value we are searching for.

$(document).ready(function () {
  $("input").keypress(function (event) {
    if (event.which == 13) {
      var value = $("input").val();
      value = value.trim().replace(/s+/g, "+");
      var url =
        "http://api.giphy.com/v1/gifs/search?api_key=dc6zaTOxFJmzC&q=" + value;
      console.log(url);
      event.preventDefault();
    }
  });
});

In your console, you should see the new URL we are sending out to the Giphy API. Next, we can actually send out our call using getJSON.

$(document).ready(function () {
  $("input").keypress(function (event) {
    if (event.which == 13) {
      var value = $("input").val();
      value = value.trim().replace(/s+/g, "+");
      var url =
        "http://api.giphy.com/v1/gifs/search?api_key=dc6zaTOxFJmzC&q=" + value;
      $.getJSON(url, function (object) {
        console.log(object);
      });
      event.preventDefault();
    }
  });
});

The JSON response object will be quite large and you won’t be able to see it using the CodePen console. Instead, in the top right where it says Change View, click and scroll down to Debug Mode. A new window will open. Right-click on the new window and scroll down to Inspect. A panel on the right or bottom of the screen should show. Now, click on the tab that says console. If you refresh the browser, put some words into the input field and click enter, you should see the response object show in the log.

Now if you type in some words in the input you should get back a hairball size of an object with an array of 25 objects. Okay, we have our data but it still is not displaying on the screen. What we need to do is iterate over the array, get every image URL and then create an img tag for each of them and append each one to the DOM. Pretty easy huh? Okay, let’s walk through it.

object.data.forEach(function (gif) {
  var url = gif.images.original.url;
  var image = $("<img src=" + url + " />");
  image.appendTo($("body"));
});

The forEach method, a vanilla JavaScript method, will iterate through all the arrays and we are assigning each array object to the gif variable. Within each of the gif objects is the images.original.url property that is the URL we need to set the src attribute of each image tag.

After we have that data we can now create the img tag, assigning the URL to the src attribute. We then append that image to the DOM.

Bada bing, bada boom, you now have an endless supply of gif bliss at your fingertips.

The completed projected now looks something likes this:

And here it is on CodePen:

You probably didn’t think that accessing and using APIs was so easy. But as you can see, from just a kitty size line of code, you were able to dynamically change your site from just a nice random cat image app to a much more powerful Giphy search app.

As you can also tell, the styles look sad. Make use of what you have learned in web development so far to make this into an awesome app with your additional styles. Be creative with it but more importantly have fun!

Sidenote: The API key we used was intended for development purposes only, not for production. That means you can’t go wild and make a million calls to the Giphy API. They will shut you down.

I hope you had another great time learning about the wonderful world of JavaScript. Until next time, may you and APIs go together like peas and carrots!