EasyGitHub Include 1.1.0

Share

GitHub Include IconEasyGitHub Include 1.1.0 is a simple Joomla! 2.5 content plugin that imports a raw source code file from GitHub (or any raw file URL) and inserts it inline in your articles or anywhere else a content plugin will work.

Version 1.1.0 updates Prettify to the March 2013 release and adds support for displaying sections of a file (i.e. a range of lines) which makes it much easier to write a walk-through of a large peice of code. (Oh, 1.1.0 also brings a new theme called "Doxy", 10 new languages and the ability to use Google's servers to deliver the Prettify Javascript and CSS.)

 

EasyGitHub Include loads the code URL from GitHub (or any other URL that links to a raw code file) and applies Google Prettify syntax highlighting.

Installation

EasyGitHub Include is a standard Joomla! 2.5 plugin and is installed using the Extension Manager.

You can either download the file to your computer or you can use the "DirectLink" URL available on the download page directly in the Extension Manager.

Configuration

You can configure the EasyGitHub Include plugins default values from the Plugin Manager as you would with any other Joomla! plugin. Don't worry we've put all the syntax tips in the plugin's Details view and we've added useful tooltips to all of the settings.

 

EasyGitHub Include Plugin Screen

Use Google?

The Use Google option is a new feature in version 1.1.0 and allows you to use the Prettify files on Googles servers, which most time will be faster than using your own servers.

Include Prettify Javascript

If you're not using Googles servers, this option allows you to prevent the inclusion of the Prettify.js files (if for example you're already including them through another means).

Include Prettify CSS

If you're not using Googles servers, this option allows you to prevent the inclusion of the Prettify.css files (if for example you're already including them in your template CSS).

Code File Wrapper

The raw code file is wrapped in a set of tags with the options being:

  1. <code> tags for HTML5 templates
  2. <code> tags inside <pre> tags for non-HTML5 templates
  3. <pre> only tags for old templates and browsers

If you're using a pure HTML5 template you will want to change this setting from the default to "Wrap in <code> tags".

Prettify Theme

Allows you to set a default theme to be used when one isn't specified in the tags you embed in your article.

Force Cache?

The one setting you may be tempted to play with is the "Force Cache" setting. Simply put as the plugin runs on your webserver it has to first retreive the contents of the URL from another server, sometimes on less expensive hosting services this can take several seconds, which your end user will see as being a slow page load from your website.

To avoid this issue the Joomla! cache is, by default, used even if you have Joomla!'s Global Cache setting turned off. To make the plugin obey your Joomla! settings simply set "Force Cahce?" to "No". Of, course this means if you have the cache turned off globally then your end users will see a pause on evey page that uses the plugin.

The cache is relatively smart, in that we cache the retrieved code file against a hash of it source URL, so even if the source file is used in multiple articles in your website it will only be retreived once during each cache cycle.

 

Using EasyGitHub Include

Results:

The image below shows the formatted output of a section of a PHP file included from a GitHub Repository. You can see this example and others on our demo site or you can click on the image to see a larger version.

EasyGitHub Include Results 

It's not a Git Only World

In this example we're actually using a code file hosted on Google's Code repository - really it doesn't matter where the file is hosted as long as the URL you give the plugin returns just the code file. If the URL returns a HTML page with the code inside it the HTML will be formatted and presented in the page as well.

In this case the URL is: http://core-plot.googlecode.com/hg/framework/Source/CPTColorTests.m

Syntax:

Please note in the examples shown below the extra space between the { the plugins identifier i.e. githubinc  is there to prevent the plugin from activating — you shouldn't have it actual include tags.

{ githubinc URL, THEMEX, LANG, LINENUMS:Y}

The most common error message you will receive is that the URL is incorrect, more specifically it will look like this:

Sorry cURL failed to retreive the page, is the URL correct?.

Examples:

 

{ githubinc https://raw.github.com/user/project/branch/filename.suffix, 2, php}

 

{ githubinc https://raw.github.com/user/project/branch/filename.suffix, 2, php, linenums:20}

 

{ githubinc https://raw.github.com/user/project/branch/filename.suffix, , , linenums:12}

 

{ githubinc https://raw.github.com/user/project/branch/filename.suffix, , , , 20-30}

 

URL- The URL should point to the raw code file and be of the form

https://raw.github.com/user/project/branch/filename.suffix

 

THEME X - This is an optional parameter, if its not provided the setting in the plugin will be used. If it is provided it must be from 0 to 4 where X is one of the following:

0 - i.e. 0 = Default Theme
1 - i.e. 1 = Desert
2 - i.e. 2 = Sunburst
3 - i.e. 3 = Sons Of Obsidian
4 - i.e. 4 = Doxy

If you use multiple code blocks on a single page only the theme of the first code block will be used.

LANG - This is an optional parameter, if its not provided the file suffix from the URL will be used. If it is provided it overrides the URL's file suffix.

LINENUMS:Y - This is an optional parameter, if its provided Prettify will add line numbers to every 5th line. You can specify a starting line by using linenums:y where y is the first line number.

RANGE X-Y - This is an optional parameter, if its provided EasyGitHubInclude will only display lines X through Y of the file. You must specify both a starting line and an end line number e.g. 20-30 where 20 is the first line number and 30 the last.

Credits

Easy GitHub Include is made possible by Google Code Prettify

Share

You need to login to access the forums.

Member Login

You need to Login to access your Subscription details or the Forums.