libgithub

libgithub is a JavaScript library for displaying GitHub data on websites. It uses the GitHub API v2.

Currently libgithub only generates ‘badges’, which look something like this:

_images/libgithub-badges.png

libgithub is available from GitHub as a single JavaScript file. A ‘minified’ version of the library is available as well. CSS styles are also included with the distribution and can be customized.

Requirements and Installation

libgithub relies on several other JavaScript libraries to function properly, all of which are conveniently included in the libgithub distribution:

  • jQuery
  • humane.js
  • date.js
  • md5.js

These libraries must be loaded along with libgithub.min.js in the HTML files which use libgithub.

Thus, to load libgithub for use, simply include in your HTML file:

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="humane.js"></script>
<script type="text/javascript" src="date.js"></script>
<script type="text/javascript" src="md5.js"></script>
<script type="text/javascript" src="libgithub.min.js"></script>

You may need to modify the file paths as appropriate, depending on your installation. To get a style similar to the screenshot above, you will also need to include the CSS stylesheet, using something like:

<link type="text/css" rel="stylesheet" href="css/libgithub.css" />

Again, modify the path as appropriate. This stylesheet references images also included with the libgithub distribution that are expected to be in a directory called ‘img’ by default.

Usage

Here is a simple example for creating a badge:

<script type="text/javascript">
$(window).load(function () {
  var b = new libgithub.Badge('msparks', 'alphasign');
  b.targetIs('#commit');
});
</script>

<div id="commit"></div>

This example uses jQuery to create a badge when the window loads. The output is displayed in the element selected by ‘#commit’, which is the <div id="commit">.

To display multiple commits or change other various settings, see the libgithub.Badge API.

API

libgithub.Badge

This class is used to create and display GitHub commit badges.

Reference

class libgithub.Badge(username, repo[, commitId])

Construct a new badge object.

Parameters:
  • username – GitHub username
  • repo – Repository name
  • commitId – ref name or commit ID (default: ‘master’)
gravatarSize()

Get the Gravatar size. Defaults to 60 pixels.

gravatarSizeIs(size)

Set the Gravatar size.

Parameters:size – width of Gravatar in pixels
startHidden()

Current startHidden setting. If true, the file list is hidden when the badge is created. Defaults to true.

startHiddenIs(setting)

Set the startHidden setting.

Parameters:setting – new setting. True = hide file list, False = show file list
target()

Get the current target.

targetIs(selector)

Set the target HTML element via a jQuery selector.

This issues a request to GitHub for commit data and creates a callback to display the badge.

The badge is appended to the inside of the element selected by the selector.

Parameters:selector – string selector to find the target HTML element. See the jQuery documentation for more information about valid selectors.

Examples

Here is a simple example for creating a badge:

<script type="text/javascript">
$(window).load(function () {
  var b = new libgithub.Badge('msparks', 'alphasign');
  b.targetIs('#commit');
});
</script>

<div id="commit"></div>

To show the file list by default, simply toggle the startHidden setting like so:

var b = new libgithub.Badge('msparks', 'alphasign');
b.startHiddenIs(false);
b.targetIs('#commit');

The commitId parameter in the badge constructor can be a ref of any kind: a specific commit ID, partial or complete; a branch name; or a tag name. Creating a badge for a specific commit is easy:

var b = new libgithub.Badge('msparks', 'alphasign', 'c5f6c7a2');
b.targetIs('#commit');