4elements, web design and consultancy

Aside from ability to extend HTML easily AngularJS also offers a simple way to interact with external APIs. In this tutorial, I will show you how to use Services to access GitHub's API and create a simple repository browser.

It's nothing fancy as you can see, only a basic layout that puts the search box on the right, repository information in the middle, and user's repositories on the right. We also have to wrap the lines in the <pre> tag that we will use to display the README file contents, since they are usually in GitHub Flavored Markdown and some lines would overlap with the user's repository list.

Of course, you can add more style to make it more pleasing to the eye, just keep in mind that the screenshots in this tutorial will show the basic look.

You can put the JavaScript code that we will write later either inline in the <head> of the document, or in a separate file, but it has to be under the AngularJS script.

Step 2: The Module

Now we can create a module for our app:

var app = angular.module('githubsearch', []);

Let's add it to the <body> tag using the ngApp directive:

<body ng-app="githubsearch">

Step 3: The Controller

We will also need a controller for our app. To keep it simple, it will be only one for the entire app, so we don't need to deal with passing information between controllers:

The $http.get() method is a shorthand for doing GET requests. The first parameter is the URL that we want to access. The second one is a object with options. We only need the params object here - it's a hash of query parameters that will be added to the request (the q parameter is a search string, as described here).

$http.get() returns a promise. We can attach success() and error() listeners to it and call the callback function accordingly.

Step 6: The Search Box

To make use of the function that we defined in the previous step we will have to add a search box to our HTML. The code is pretty simple:

We use ngModel directive to bind the value of this input field to the query variable in the scope and ngKeyup to call the executeSearch() function when user presses the enter key (hence the $event.keyCode == 13 comparison). We can't use conditional statements in AngularJS expressions, but a simple logic operation (AND) will do fine.

Under the input field, we use ngRepeat to display the search results. We will display the repository's full name and description (you can see all of the fields available in this example in the GitHub's API documentation if you want to display something different).

We also use ngClick to call the openRepo() function with the repository's full name so we can display information about it. We will define this function later.

Step 7: Using the Search Function

Now we can finally make use of the service we created. First, add the GitHub parameter to the controller function (so the service can be injected by AngularJS):

This one is pretty much the same as the two previous ones, only the url changes. We are also using the atob() function to decode contents of the README file, since it's base64 encoded. Getting contents of the README file is described here in the GitHub's API documentation.

The reason that we did not chain the two requests in one function is that some repositories don't have any README file. If we were to continue like that, the application would fail.

Step 10: Displaying the Repository Information

We will display repository's full name, number of people watching it and the README file in another <div> element:

We will store that information in the activeRepo variable in the scope of the controller. There is also the ngShow which will show the element only if there is any data to be displayed (otherwise you would see a "Watched by people" text there with no repository selected).

Step 11: Updating the Controller

We also have to update our controller so it gets the repository data and puts it in the scope. Create the openRepo() function that we attached to the ngClick directive earlier:

As you can see we first use the GitHub.getRepo() method, check for errors and then place the data in the activeRepo variable. After that we get the README file and in case it does not exist we inform the user about that fact.

Now you can run your app again and see how it

Step 12: Getting User's Repositories

To add some functionality to our app we will display all repositories of the selected repository's owner on the right side of the screen. This will require another method in our service:

At this point, you should have a working AngularJS application that retrieves GitHub repositories based on a search string. You can continue to iterate on this by adding more features, or giving it a different presentation through styles.