zenorocha/jquery-github

A jQuery plugin to display your Github Repositories

jQuery Github

A jQuery plugin to display your Github Repositories.

Browser Support

We do care about it.

IE 8+ ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔

Getting started

Three quick start options are available:

• Download latest release
• Clone the repo: [email protected]:zenorocha/jquery-github.git
• Install with Bower: bower install jquery-github

Setup

Use Bower to fetch all dependencies:

$ bower install

Now you're ready to go!

Usage

Create an attribute called data-repo:

<div data-repo="jquery-boilerplate/jquery-boilerplate"></div>

Include jQuery:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>

Include plugin's CSS and JS:

<link rel="stylesheet" href="assets/base.css">
<script src="jquery.github.min.js"></script>

Call the plugin:

$("[data-repo]").github();

And that's it \o/

Check full example's source code.

Options

Here's a list of available settings.

$("[data-repo]").github({
	iconStars:  true,
	iconForks:  true,
	iconIssues: false
});

Attribute	Type	Default	Description
iconStars	Boolean	true	Displays the number of stars in a repository.
iconForks	Boolean	true	Displays the number of forks in a repository.
iconIssues	Boolean	false	Displays the number of issues in a repository.

Structure

The basic structure of the project is given in the following way:

.
|-- assets/
|-- demo/
|   |-- index.html
|   |-- index-zepto.html
|-- dist/
|   |-- jquery.boilerplate.js
|   |-- jquery.boilerplate.min.js
|-- src/
|   |-- jquery.boilerplate.coffee
|   |-- jquery.boilerplate.js
|-- .editorconfig
|-- .gitignore
|-- .jshintrc
|-- .travis.yml
|-- github.jquery.json
|-- Gruntfile.js
`-- package.json

assets/

Contains CSS and Font files to create that lovely Github box.

bower_components/

Contains all dependencies like jQuery and Zepto.

demo/

Contains a simple HTML file to demonstrate the plugin.

dist/

This is where the generated files are stored once Grunt runs JSHint and other stuff.

src/

Contains the files responsible for the plugin.

.editorconfig

This file is for unifying the coding style for different editors and IDEs.

Check editorconfig.org if you haven't heard about this project yet.

.gitignore

List of files that we don't want Git to track.

Check this Git Ignoring Files Guide for more details.

.jshintrc

List of rules used by JSHint to detect errors and potential problems in JavaScript.

Check jshint.com if you haven't heard about this project yet.

.travis.yml

Definitions for continous integration using Travis.

Check travis-ci.org if you haven't heard about this project yet.

github.jquery.json

Package manifest file used to publish plugins in jQuery Plugin Registry.

Check this Package Manifest Guide for more details.

Gruntfile.js

Contains all automated tasks using Grunt.

Check gruntjs.com if you haven't heard about this project yet.

package.json

Specify all dependencies loaded via Node.JS.

Check NPM for more details.

Showcase

• zenorocha.com/projects
• anasnakawa.com/projects

Have you used this plugin in your project?

Let me know! Send a tweet or pull request and I'll add it here :)

Alternatives

Prefer a non-jquery version with pure JavaScript?

No problem, @ricardobeat already did one. Check his fork!

Prefer Zepto instead of jQuery?

No problem, @igorlima already did that. Check demo/index-zepto.html.

Prefer AngularJS instead of jQuery?

No problem, @lucasconstantino already did that. Check his fork!

Contributing

Check CONTRIBUTING.md.

History

Check Releases for detailed changelog.

Credits

Built on top of jQuery Boilerplate.

License

MIT License © Zeno Rocha

jquery-github's Issues

Create an online page to demonstrate the plugin

a little suggestion for styles

The box looks strange on pages with CSS resets like this:

* { box-sizing: border-box; }

This is used quite often as far as I know.
So I suggest this to be added to base.css:

.github-box .github-box-download {
  // ...
  box-sizing: content-box;
}

Home page link broken.

http://zenorocha.github.io/jquery-github/ link is broken

Add support for emoji

Add Continous Integration with Travis

This will also help #11

Change "watch" to "star" icon

Use mock instead of static definitions

Is there an easy way to hide the download button?

I'd rather not show a download button for my repo, because most users will want to download the packaged version of our project, not the source, so the download button is just a point of confusion.

Can it be hidden?

Fix Date

"Latest commit to master on 0/10/2013"

Issue count

It is very usefull to build a custom page with your plugin.
But the benefit is more usefull, if the count if issues is on the repository, very usefull for authors and users, there read the page.
Maybe a nice idea for your plugin.

A exampel can you see here for the count, but custom source and not with your plugin, much older. http://bueltge.github.io/

Add the ability to list all repositories from a certain username

Something like this:

$("#my-container").github({
    username: "zenorocha"
});

Idea by @Yonaba.

Display error message if API exceds its limits

Improve Minify method

https://github.com/EvandroLG/setup-lib-js/blob/master/files/Makefile

Add qUnit tests

Update Forks URL at 'gh-pages'

It shows: https://github.com/zenorocha/jquery-github/forks
Instead of: https://github.com/zenorocha/jquery-github/network

Fetch dependencies via Bower

Nothing shows up

I have no idea why, but my Github repos disappeared off my website even though I didn't change any code related to displaying them. I troubleshooted for a little while and after nearly giving up I then decided for some reason to come here and see if it was a global issue, and it somehow turns out, it is.

Visiting your page shows this in my browser(s):

Interestingly enough, no 404's were given in the Developer Tools.

This made me realize: this service heavily relies on something else (github), and when that's not working it doesn't display anything. For a fallback, would it be possible to display dumb links to repositories instead?

Auto instantiate the plugin based on "data-repo"

We don't need this:

$('.github-widget').github();

We just have to catch all HTML elements that contains the "data-repo" attribute and loads inside of it.

TwitterBootstrapStyle

Multiple Repos on 1 page but options are global?

I have a page where I have 2 repo's displayed on a page. I want to display some with issues and some not.

<div id="jquery" data-repo="jquery/jquery">
$("#jquery").github({
    iconStars:  true,
    iconForks:  true,
    iconIssues: false
});

<div id="zeno" data-repo="zenorocha/jquery-github">
$("#zeno").github({
    iconStars:  false,
    iconForks:  false,
    iconIssues: true
});

I am seeing that the last .github() I call seems to set the options for all of them on the page. Are these options global?

Plugin methods exposed to the global scope

Just the jQuery plugin definition is wrapped with an IIFE. The classes and its methods are exposed to the global scope. I understand that, this way, is easier to test all the plugin methods, but these methods can be overwritten.

I suggest to put the IIFE wrapper in the build without losing the way tests are done, using a grunt task. What do you guys think?

I can make a PR, if it's a good idea.

Trim repo description

CSS Namespace

Update dependencies

And include David's badge.

Change name to "jquery-github-repos"

Create a minified version

Will exceed GitHub API rate limits

The rate limit for unauthenticated requests is only 60/hour. That's pretty easily reached - a page with 12 repo boxes will blow it in just five page reloads :(

It could use localStorage for caching, but it's still likely to hit the limits if you visit just a few sites using it.

Update to jQuery 1.9