Gistex

A vanilla JavaScript tool for loading Github Gist snippets on the fly with AJAX

Github offers a special service of embedding code snippets complete with syntax highlighting onto websites using a simple <script> tag. This service is awesome, but if you’re using a pure AJAX application then it becomes almost impossible to load a gist embed into a website and retain its syntax highlighting. Not anymore … Gistex solves this.

Last Updated

This page was last updated on December 18th 2011 and was first published on May 9th 2011

How is this different from a regular Gist Embeds?
Supported Browsers & Frameworks
Usage
Methods
Options & Events
Issues
Demos
Download
Contact

How is this different from a regular Gist Embeds?

Gistex uses a pure, framework-less JavaScript class which loads a gist script into the page and fires a handful of callback methods while doing so. Regular embeds will load it exactly at the point of which the page contains the script tag, but Gistex can load the Gist data anywhere in the DOM. This is very useful for pure Ajax applications and websites (like this one) and can be useful for lazy loading of gist snippets. Gistex also helps since it does not block page loading since the script tags are not embedded within the content of the page.

To Top Goto Demos Goto Download

Browser Supports & Frameworks

Gistex is 100% supported and compatible with all JavaScript frameworks. Therefore, frameworks such as MooTools, JQuery, Prototype, YUI and Dojo are all supported.

All modern browsers (and a few legacy browsers) such as Internet Explorer (IE9-IE10), Chrome, Firefox, Safari and Opera are all supported. iOS Mobile browsers such as the Apple IPhone, IPad and IPod Touch are also supported. Other mobile devices are yet to be tested.

To Top Goto Demos Goto Download

Usage

Usage is very easy, here’s how to use it (its actually being used now):

<div id="container">This is where the gist code will be loaded.</div>

<script type="text/javascript" src="./gistex.js">
<script type="text/javascript">
var container = document.getElementById('container');
var gs = new Gistex(container,'https://gist.github.com/....js?file=...',{
  onLoading : function() { ... },
  onReady : function() { ... },
  onFailure : function() { ... }
});
gs.load();
</script>

A Gistex object can be instantiated the following ways:

new Gistex(container,'https://gist.github.com/1494292.js?file=gistfile1.js',{...});

new Gistex(container,{ id : 1494292, file : 'gistfile1.js'},{ ... });

new Gistex(container,'<script src="https://gist.github.com/1494292.js?file=gistfile1.js"></script>',{ ... });

To Top Goto Demos Goto Download

Methods

The following methods are the only public ones that Gistex provides:

Method	Description
new Gistex(container,src,options)	Instantiates a Gistex Object. The container must either be the the element itself (dom object) or the id of the element (string). The src can either be the javascript file path, the script code or the a hash of id=id, file=file properties. The options parameter is a hash of key value options.
object.load()	Starts the request to load the gist code from github.
object.cancel()	Cancels the request to load the gist code from github.
object.show()	Shows the container
object.hide()	Hides the container
object.getSrc()	Returns the source of the gist file
object.getID()	Returns the ID of the gist iframe request

To Top Goto Demos Goto Download

Options & Events

Gistex contains a handful of Events and a few extra options that can be applied in the constructor options:

Option	Values	Description
showOnReady	Boolean (default = true)	If true then the container which will contain the gist content will be hidden and then revealed (display=”block”) once it has been loaded.
className	String (default = ‘gist-stage’)	The class string that will be set for the container of the gist code.
timeout	Integer (default = 10000)	The timeout delay that is checked for when the gist file is downloaded. This will call onTimeout when the total time has gone beyond the timeout delay.
onReady	Event	This will be fired when the gist file is ready and has been displayed.
onLoading	Event	This will be called as soon as the request has been made.
onFailure	Event	This will be fired when the gist file was not found or cannot be fetched from github.
onComplete	Event	This will be called (just before) either when the onReady or the onFailure event has been called.
onTimeout	Event	This will be called when a timeout has occured (when the total time is takes longer than the timeout delay specified in options.timeout.
onCancel	Event	This will be called if the request has been cancelled.

To Top Goto Demos Goto Download

Issues

There are no issues with this plugin. However, since the plugin works by rewriting the document.write text then it may be an issue with legacy browsers or older mobile operating systems (I’m looking at you IE mobile). But since all browsers support this fine then it doesn’t look like there are any other problems.
The JavaScript will fetch out the stylesheet code from the html created from the embed. The stylesheet will load in the background. This may or may not download in time before the code is displayed so for a brief delay the user may see the code displayed without any syntax highlighting. This is only an issue the very first time it is loaded since the stylesheet will be cached properly afterwards.

To Top Goto Demos Goto Download