jQuery.Syntax Advanced Setup

jQuery.Syntax was designed to be simple to use, but it also has many advanced features.

Installer

The installer provides a simple way to deploy customised versions of jQuery.Syntax. It is the primary way to access advanced features of jQuery.Syntax:

$ rake install
(in /...snip.../jquery-syntax)
Working in /...snip.../jquery-syntax/public...
Building CSS: clean/master.sass
Loading theme from /...snip.../jquery-syntax/themes/clean...
Loading theme from /...snip.../jquery-syntax/themes/base...
...snip...
Copying jquery.syntax.brush.java.js...
Copying jquery.syntax.brush.kai.js...
...snip...
Minifying jquery.syntax.brush.io.js...
Minifying jquery.syntax.brush.lisp.js...
...snip...
Install into /...snip.../jquery-syntax/public finished.

The installer processes the source files and theme, to produce a set of files that can be deployed to a website.

By default rake install reads the install.yaml file for information about which theme to generate and where to put the minified javascript and stylesheets. Here is an example install.yaml:

# The path to install the code
prefix: "public"
# The options for the stylesheet generation
generate_stylesheets:
    theme: "clean"
    # override: blue
# Enable minification
minify: true

Specifying the configuration file

It is possible to specify a different file to read the install configuration from by supplying it as an argument:

$ rake install[site.yaml]

Specifying a different prefix

You can also specify the installation directory by setting the PREFIX environment variable. This will override the prefix setting in install.yaml:

$ PREFIX=public2 rake install

Dependencies

You will need to install Ruby to use the installer, along with the following gems:

$ sudo gem install rake haml

Syntax Highlighting Options

These options are for use when highlighting a specific element:

$('div.java').syntax({
	brush: 'java',
	layout: 'fixed',
	tabWidth: 8,
	replace: true
});
brush
The name of the brush to use for syntax highlighting. This is not the same as the class name brush-{language} but is infact the exact name of the language {language}. Defaults to plain.
tabWidth
Used for the tab to space conversion. Defaults to 4.
layout
Used for producing HTML from a set of lines. Defaults to plain. Don't use this for the simple function (use blockLayout and inlineLayout).
linkify
Turn elements that matched href into actual links.
replace
If true, replace the given container with the resulting highlighted element. This is generally what you want to do, unless you are highlighting something and then using the result elsewhere, e.g. say you wanted to highlight <script type="text/javascript"> tags and then insert them into the body of the page.

Creating Your Own Theme

Simply create a new subdirectory in the themes directory. Then, create files named using the convention jquery.syntax.{resource-type}.{name}.sass. For example, a new theme named coffee:

Once you've done this, update install.yaml and run the installer to update the current deployment.

You can also create a theme configuration file themes/config.yaml which specifies how the theme builds on other themes:

# "base" is the basic theme. It adds minor scaffolding
# to support a website which doesn't have the right
# css for .syntax and .syntax-container layout.
depends:
    - base
# This adds code to existing css generation files - when 
# the specified file is processed, this file is also 
# included at the end.
extends:
    "jquery.syntax.core.sass": "_jquery.syntax.core.sass"
# Specifies files to prefix on every other file processed.
# Normally you wouldn't declare rules in this as they would
# end up duplicated in every CSS file generated.
includes:
    - _modern.scss

Creating Your Own Layout

Layouts are specified using the naming format jquery.syntax.layout.{name}.js in the main jQuery.Syntax directory.

A layout is basically a function which translates the code from a set of highlighted lines into actual structured output. The "table" layout does this by creating a <table> and adding a row for each line. The "inline" layout creates an inline <code> element.

It is also possible to bundle a stylesheet with a layout, which means you will need to generate a file jquery.syntax.layout.{name}.sass in an appropriate theme subdirectory.

Once you have done all this, use your theme by specifying it as an option:

<script type="text/javascript" charset="utf-8"><!--
$(function() {
	// Assuming you've made the files:
	//     jquery.syntax.layout.my_block.js 
	//     jquery.syntax.layout.my_inline.js
	
	// Simple function...
	$.syntax({blockLayout: "my_block", inlineLayout: "my_inline"});
		
	// Or...
	$('pre.js').syntax({brush: "javascript", layout: "my_block"})
});
--></script>

You can see several of the sample layouts that come with jQuery.Syntax.

Creating Your Own Brush

Brushes are specified using the naming format jquery.syntax.brush.{name}.js. As with layouts, they also have an associated optional stylesheet named jquery.syntax.brush.{name}.sass. Here is a simple example:

// brush: "new_brush" aliases: ["nb"]

//	This file is part of the "jQuery.Syntax" project, and is licensed under the GNU AGPLv3.
//	Copyright 2010 Samuel Williams. All rights reserved.
//	See <jquery.syntax.js> for licensing details.

Syntax.register('my_brush', function(brush) {
	brush.push(['(', ')'], {klass: 'operator'});
	
	brush.push({
		// All regular expressions must be global.
		pattern: /0x[0-9a-fA-F]+/g,
		// klass is used as a tag for the particular element being highlighted.
		klass: 'constant'
	});
	
	brush.push({
		pattern: /; .*$/gm,
		klass: 'comment',
		// This states that within the string matched, only elements of klass href can exist within.
		allow: ['href']
		
		// ... You can also specify several other things
		// allow: '*' -> allow all klasses to be children of this match
		// disallow: ['...'] -> allow all klasses except the listed ones to be children of this match
		// only: ['...'] -> this child match can only exist within the given parent klass
	});
	
	// Syntax.lib.doubleQuotedString = {pattern: /"([^\\"\n]|\\.)*"/g, klass: 'string'};
	brush.push(Syntax.lib.doubleQuotedString);
	
	// Syntax.lib.stringEscape = {pattern: /\\./g, klass: 'escape', only: ['string']};
	brush.push(Syntax.lib.stringEscape);
	
	// Syntax.lib.webLink = {pattern: /\w+:\/\/[\w\-.\/?%&=@:;#]*/g, klass: 'href'};
	brush.push(Syntax.lib.webLink);
});

Once you've created or updated a brush, you will need to run the installer again to update the current deployment.

Highlighting Individual Elements

jQuery.Syntax provides the basic jQuery.syntax(...) function as outlined above, but this is actually a wrapper for another more flexible function jQuery.fn.syntax(...). This function is a standard jQuery element function, and can be used to highlight specific elements.

// Callback functions receives three arguments
// 'options' are the options given for the processing of this element
// 'html' is the resulting syntax highlighted html
// 'container' is the original element where the code was extracted

$('pre.js').syntax(
	{brush: 'javascript', layout: 'table'},
	function (options, html, container) {
		// A callback that reimplements the default behaviour (as an example).
		container.replaceWith(html.clone(true));
	}
);

$('code.js').syntax(
	{brush: 'javascript', layout: 'inline', replace: true}, 
	function (options, html, container) {
		// The result of this callback is replaced into container (like above), because
		// 'replace: true' is suppled as an option and the result is non-null.
		// You could perform further manipulation on this result, if required.
		return html;
	}
);

When integrating with dynamically generated code (such as via AJAX), there are two options: either use the simple syntax function with a specific context element (where the context element contains the dynamically generated content) or use the specific syntax function with any source code that has been dynamically generated.

As an example, Syntax-Highlighting.com uses the specific function since it is processing a specific block of source code. Another example is the Orion Transfer Weblog which allows source code in the comment preview. Because this is sanitised by the server, when the page is updated via AJAX, the simple function is used to render any source code in the comment preview.

Simple Function Example

// This function is called when the preview is updated.
function updatePreview () {
	// Update preview with result of AJAX...
	// ...snip...
	
	// Update any source code in the preview
	$.syntax({context: $("#comment-preview")});
}

$.post('update-preview', {
	success: updatePreview,
	...etc...
})

Specific Function Example

// Because resources need to be loaded, this method is asynchronous,
// and you need to provide a callback function
var code = $('<pre>int main (int argc, char ** argv);</pre>');

code.syntax({brush: 'c'}, function(options, html, container) {
	// The variable 'html' contains the highlighted source code elements.
	console.log(html);
})

Zero-Load Script

It is possible to have many pages without syntax highlighting, so why have the overhead of loading an extra JavaScript every time? You can use the following jQuery snippet to avoid loading jQuery.Syntax at all when it is not needed.

// jQuery.Syntax Dynamic Loader v1.0
jQuery(function ($) {
	var SyntaxRoot = "/_static/jquery-syntax/";

	if ($('.syntax').length) {
		$.getScript(SyntaxRoot + "jquery.syntax.min.js", function () {
			$.syntax({root: SyntaxRoot});
		});
	}
});