SyntaxHighlighter Plugin Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


PayPal

SyntaxHighlighter provides front-end syntax highlighting for MODX Revolution. SyntaxHighlighter is a Revolution version of Alex Gorbatchev's JavaScript Syntax Highligher. The plugin and snippet code itself and the installer are mine, but the rest of the code is Alex's. If you use Syntax Highlighter, you're encouraged to donate to Alex's project here. Theme property and updates thanks to AlexZem

The SyntaxHighlighter package installs both a plugin and a snippet. Either one will highlight just about any kind of code and will provide line numbers in the "gutter" at the left side of the code. The line numbers can be turned off if you don't want them. You can use either the plugin or the snippet, but not both. For maximum speed, use neither one (see the section below on Speed Considerations).

The Plugin

The SyntaxHighlighter plugin is disabled by default. To enable it, edit the plugin, uncheck the "disabled" checkbox, and save the plugin.

The plugin will fire on every page at your site. It is relatively fast, but it will slow the site down slightly as it parses every page looking for code to highlight. If you have a code-intensive site, this is fine, but if you only have code on a few pages, the snippet may be a better option. The plugin will only affect code in <pre> tags with a particular class (see the Usage section below).

The various kinds of highlighting — one for each type of code (HTML, PHP, CSS, etc.) — are called "brushes". The &brushes property of the snippet will determine which brushes are loaded. For the plugin, you must specify every brush used on the site in the &brushes property.

The System Setting

The syntaxhighlighter.theme System Setting sets the default theme to be used by SyntaxHighlighter. The theme will be used throughout the site. The available themes are: Default, Django, Eclipse, Emacs, FadeToGrey, MDUltra, Midnight, and RDark. If you use the snippet, you can override the default theme on a particular page by using the &theme property in the snippet tag.


As of version 1.0.1, the theme files under the assets/components/syntaxhighlighter directory have been moved to the css/theme directory. The theme files in the css/ directory are no longer used. They haven't been removed in case you have a custom theme there. If you do, move it to the theme/ directory. The old files can be deleted.


The Snippet

The snippet is particularly useful if you only have code on a few pages, or if different pages have different kinds of code. You can specify the brushes to load in the snippet tag so that only the brushes used on the page are loaded. If no brushes are specified in the tag, the default brushes (JScript,Xml,Php,Css,Plain) are loaded. To highlight code on a page, place a SyntaxHighlighter snippet tag at the top of the page content (or in the template):

[[SyntaxHighlighter? &brushes=`css,php`]]

Usage

SyntaxHighlighter (SH) will only affect code wrapped in <pre> tags. In order to let SH know what type of code it is, you need to specify a "brush" in the opening <pre> tag like this:

<pre class="brush: php">

The line above tells SH that you want the php brush. By default, brushes are loaded for php, css, xml, js, and plain. The plain brush styles the selection as preformatted, but does no highlighting. It's useful for MODX tags (though there really should be a brush for that too).

It's important that any angle-brackets in the code be converted to HTML entities (&lt; and &gt;) before SH sees the code, otherwise, SH may get confused. You can convert them manually, or you can use the FixedPre plugin to do it for you. FixedPre fires during OnParseDocument, so it will convert the code and remove the <fixedpre> tags before SyntaxHighlighter sees it. If you use FixedPre, do not convert the tags to HTML entities.

If you already have FixedPre installed, be sure to update it to at least version 1.0.2-pl. Earlier versions are not compatible with SyntaxHighlighter. Note that the later versions of FixedPre no longer insert <span> tags. If you use those for styling, see the FixedPre tutorial here.

Important: If you use SyntaxHighlighter with FixedPre, make sure the FixedPre tags are inside the SyntaxHighlighter tags. Otherwise, FixedPre will "entify" the <pre> tags and SyntaxHighlighter won't see them.

Other Brushes

SH has many brushes including ones for SQL, AppleScript, ColdFusion, Delphi, Ruby, Python, Perl, VB, Java, and many more. To see the available brushes, look in the assets/components/syntaxhighlighter/scripts directory. In order to use other brushes, you need to specify them, separated by commas, in the &brushes property of SH.

The brush names are mixed case and must be specified correctly in the &brush property. They are the filenames from the scripts directory minus and leading "sh" and the extension. For example, the file shBrushJScript.js is specified in the &brushes property as 'JScript'.

When you specify the brush in the <pre> tag, however, you must use the lower-case alias for the brush. In the case of the JScript brush, the alias is js. The default brush aliases are php, css, xml, js, and plain. Note that xml is used to highlight both XML and HTML. For other brushes, you can look at the end of the brush.js file that's being included to find out what the alias is, though it's usually a lowercase version of the code type (e.g., python, ruby, sql, perl, java, vb, bash, csharp, etc.).

If you specify a brush in the <pre> tag that is not loaded in the &brush property, a JavaScript alert will pop up and tell you the name of the missing brush.

Important: The brushes to be loaded by the &brushes property are case-sensitive and must match the brush-name part of the file name. When you specify a brush in a <pre> tag, however, the brush name must be all lowercase.

Options

Various options can be specified in the <pre> tag by adding them after the class specification. The full list of options can be found here. Here's what they look like in a tag:

    <pre class="brush: php; toolbar: false; gutter: false; highlight: [2,3];">
    <?php
    function modify($x, $y) {
       $x = $x * 3;
       $y = $y + 2;
       return $x + $y;
    }
    </pre>

The option settings above will turn the toolbar (the icon at the right side of preformatted section) and the line numbers off and will highlight lines two and three of the code. Notice the semicolon at the end of each option specification.

Speed Considerations

There are a number of ways to speed up the operation of SyntaxHighlighter. The easiest is to just eliminate any brushes you don't use on the site from the &brushes property of the plugin or specify just the brushes you need in the snippet tag.

Another trick is to enable SH using either the snippet or plugin and view the source code of a page. Copy the relevant SH lines directly into your template(s) at the appropriate places, then disable the SyntaxHighlighter plugin or remove the snippet tag. Don't forget the script at the bottom of the page. It can be moved below the final <html> tag so that the browser will finish rendering the HTML before executing the function, but visitors on slow connections may see the unformatted code before the formatted code appears.

Further speed increases can be gained by moving the content of the two CSS files into your site's CSS file and removing the SyntaxHighlighter CSS file references in the template.

Finally, for even more speed, you can copy the contents of the brush files you actually use into a single .js file and just refer to that file with a single line in the template. If you're really a speed freak, you could place all the js code in the template itself.

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray