Github repositories in jQuery

Note: This post was originally published in August 2015

Update 7/12: Today I released version 0.0.3 to Bower. The code has some breaking changes and this blog post has been updated to reflect them.

Today I sat down and wrote a relatively simple but effective jQuery plugin. Its purpose? To simply list all available (public) repositories for a specified user. I know of at least one other plugin that does the same, and reinventing the wheel is not usually a good idea. Yet something seemed to be missing. For one, the plugin I found had hard-coded HTML.
That was a no-go for me, as I didn't really want to change the source for simple markup-related changes. Also my experience writing jQuery plugins was (and probably still is) near-zero, so I could use the exercise.

The plugin makes it easy to add your Github repository information to your web site. You can use Bower to install the plugin and call it as you're used to.

bower install jquery-github-showcase  

You can view a demo here and find the plugin here.

Using the plugin

You'll have to download it manually and add it to your HTML/template file. Obviously it depends on jQuery, so make sure that's loaded first.

<script src="js/jquery-github-showcase.js"></script>

Once you've included the plugin, you can call it like any other. In the example below we are adding the plugin to the #my-showcase selector:

$(document).ready(function() {
    $('#my-showcase').gh_showcase({
        'username': 'MichielvdVelde',
        'templateUrl': 'templates/github.tpl',
        'renderer': Mustache.render, // Required, and should take (template, scope)
        'store': localStorage, // Required, should have getItem(key) and setItem(key, value)
        'transform': function(repo) {
            // Use this method to transform repo properties when necessary
            // In this case, convert the date to dd-mm-YYYY
            var updated_at = new Date(repo.updated_at);
            repo.updated_at = updated_at.getDate() + '-' + (updated_at.getMonth() +1) + '-' + updated_at.getFullYear();
            return repo;
        }
    });
});

Now the repositories for username will be appended to the element, using the template URL (templates/github.tpl) provided. Alternatively you can also substitute it for template, which takes the template directly. How it works from there depends on the renderer.

There are no built-in fallbacks for renderer and store; if one or both of these are undefined or do not have the correct requirements, the plugin will print an error message to the console and fail.
To circumvent this, you can define your own renderer method in the options. This method should accept the same arguments as Mustache (meaning (template, repo)). The complete repo object from the Github API will be available in the render method and template, so you can do what you want with it.

You may have noticed the tranform method added to the plugin's options. This method allows you to alter (transform) the repo's properties before they are passed to the render method. In the example above I am using this feature to transform the updated_at date to a date string in my local format (which is dd-mm-YYYY). You can do anything you want here with any of the properties. Just make sure to return the repo object.

Options

  • username: The user name to load the repositories for (required)
  • sort: The field to sort on (see Github API, default 'pushed')
  • direction: The direction of the sort, either desc (default) or asc
  • template: The template to use for rendering (this or templateUrl is required)
  • templateUrl: The URL of the template to use for rendering (this or template is required)
  • cacheTime: The cache time in hours. Defaults to 24h. Disable caching by setting cacheTime to 0
  • renderer (replaces render): The render method. Should take (template, scope). If no renderer is set, an error will be generated
  • store: The cache store to use. Should have setItem(key, value) and getItem(key). If no store is set, an error will be generated
  • transform: An optional method to transform properties.

If both template and templateUrl are set, templateUrl takes precedence.

If you want to replace localStorage as the cache store, this object needs to have two methods: getItem(key) and setItem(key, value).

To do's

I still have several things to improve about this plugin. It's usable, but could use some optimization and clean-up.

  • Build in some error handling instead of just crashing and failing
  • Maybe use data-* attributes to store some of the configuration values

The plugin is now available on Bower, and the latest version (at the time of writing) is 0.0.3. I hope it's useful to you, feel free to fork and improve upon it, like most of my work, the plugin is MIT-licensed.

See you soon!

comments powered by Disqus