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 … Gist solves this.
Last Updated
This page was last updated on December 18th 2011 and was first published on December 18th 2011
Table of Contents
- 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.
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.
Usage
Usage is very easy, here’s how to use it (its actually being used now):
A Gistex object can be instantiated the following ways:
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 |
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. |
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.
Demos
Download
The Gistex.js files can be found on github.
Contact
Any issues or questions can be posted on the issue tracking page found on github.