One of the great things about RavenNuke™ is that it's easy to customize without an extensive knowledge of PHP or proprietary code. So as we build our site, we thought we would share how we achieved some of the customizations we needed. Being able to highlight code was one of our first needs, so we tried out several options.

GeSHi, Chili, prettify, Syntax Highlighter, and a few others where solid candidates; but in the end we decided on Highlight by software maniacs. Relatively easy to use with dynamic language detection, a nice selection of included themes, and it highlighted code within our forums more reliably than Chili or prettify.

UPDATE: June 2012 - This was originally written for RavenNuke version 2.4. Highlight JS is now included as a forum addon with Advanced BBCode Box and the approach for highlighting other modules (as below) has changed. Please consult the readme included with the Advanced BBCode Box download for tips on enabling highlighting in Content Plus.

We'll start by grabbing a copy of Highlight at http://softwaremaniacs.org/soft/highlight/en/download/. Use the Custom Package option and select the languages you would like to highlight on your site. The download script will build a custom highlight.pack.js according to your selection(s), for our purposes we selected CSS, HTML-XML, Javascript, PHP, and SQL

Upload the highlight.pack.js, as well as the folder styles included in the download to includes/jquery/. Note: You do not need to upload the languages folder if you use the custom highlight.pack.js file.

For our purposes we will be adding syntax highlighting to the Content Plus module, so first off lets create a file that will load the proper scripts only when we need them. Create a file modules/Content/highlighter.php, this example will first look for your preferred style in your active theme, and if it doesn't exhist it uses the default style. Set $DefaultStyle and $PreferredStyle to your liking, you can see the available styles that are included and showcased in the Highlight demo. You will need to make some edits to the CSS files included with highlight, but for now let's upload and come back to that in a moment.

modules/Content/highlighter.php

<?php
if (!defined('MODULE_FILE')) die ('You cannot access this file directly...');
// change to your default style (if no theme specific style)
$DefaultStyle = 'includes/jquery/styles/default.css';
// change to your preferred style, located at themes/ANY_ACTIVE_THEME/style/
$PreferredStyle = 'school_book.css';
$ThemeSel = get_theme();
$CoderCssFile = INCLUDE_PATH . 'themes/' . $ThemeSel . '/style/' . $PreferredStyle;
if (file_exists($CoderCssFile)) {
	addCSSToHead($CoderCssFile, 'file');
	}else{
	addCSSToHead($DefaultStyle, 'file');
}
// including jQuery as we use jQuery to initialize the script 
addJSToHead('includes/jquery/jquery.js', 'file');
addJSToBody('includes/jquery/highlight.pack.js', 'file');
addJSToBody('includes/jquery/start-highlight.js', 'file');
?>

Before we upload highlighter.php, we need to create includes/jquery/start-highlight.js to initialize highlighting. Also included is an IE hack to add <code> tags inside of <pre> tags, so the script can apply a multitude of preprietary IE fixes.

$(document).ready(function() {
	if ($.browser.msie) {
	$("pre").wrapInner("<code></code>"); //ie hack
	$("pre code").each(function(i, e) {hljs.highlightBlock(e, "    ")});
	}else{
	$("pre").each(function(i, e) {hljs.highlightBlock(e, "    ")});
	}
});

Upload start-highlight.js to includes/jquery/ and highlighter.php to modules/Content/, now we need to decide when and where to call highlighter.php. We only really need it on the content pages, so lets take a look at the beginning of the showpage function in modules/Content/index.php.

function showpage($pid, $page) {
global $prefix, $user_prefix, $db, $sitename, $admin, $module_name, $locale, $datetime, $bgcolor4, $nukeurl, $admin_file;
	include('header.php');
	cpheader();
	OpenTable();

We have to include the file before header.php is included (and not before mainfile.php) as that is where our scripts will be loaded. We will define RN_MODULE_HEAD, which is used to load scripts for only a particular module (not the entire site), like so:

function showpage($pid, $page) {
global $prefix, $user_prefix, $db, $sitename, $admin, $module_name, $locale, $datetime, $bgcolor4, $nukeurl, $admin_file;
define('RN_MODULE_HEAD', 'highlighter.php');
	include('header.php');
	cpheader();
	OpenTable();

With that, we are almost ready to start pasting some code examples... You must escape & with &amp;, and < and > with &lt; and &gt; before posting your code. There are many ways accomplish this, we simply used the find replace function of our text editor. Do not escape single or double quotes. Once you have escaped your code simply wrap it in a <pre> tag.

<pre>CODE_HERE</pre>

CSS: The original script and CSS was intended to reside inside of both <pre> and <code>, i.e.

<pre><code>ESCAPED_CODE_HERE</code></pre>

However, the nukeWYSIWYG editor does not handle <code> tags well, but it does do surprisingly well with <pre> tags; (with one notable exception) preserving line breaks so your code does not collapse onto a single line. This will require some edits to the stock CSS files as some of the styling is targeted toward pre code. You can download our modified CSS files or make some edits on your own.. The styles vary, but for example:

pre code {
  display: block; padding: 0.5em;
  background: #444;
}

pre .keyword,
pre .literal,
pre .change,
pre .winutils,
pre .flow,
pre .lisp .title,
pre .tex .special {
  color: white;
}

pre code,
pre .ruby .subst {
  color: #DDD;
}

Notice the values assigned to pre code, we need to assign them to pre, as well as fix a text wrapping issue by using white-space:pre-wrap;

pre{
  background-image:none;
  background-color:#444;
  display: block !important; 
  padding: 15px 0.5em 15px 30px;
  font-family:"Courier New", Courier, monospace;
  font-size: 14px;
  color:#DDD;
  line-height:14px;
  border-top: none;
  border-bottom: none;
  white-space:pre-wrap;
}

pre .keyword,
pre .literal,
pre .change,
pre .winutils,
pre .flow,
pre .lisp .title,
pre .tex .special {
  color: white;
}

pre .ruby .subst {
  color: #DDD;
}

Notice we imported the background and text colors from the pre code definitions, as well as removing pre code as it's no longer needed. Also added several other definitions for padding, font-family, font-size, line-height, and border which you can customize to your liking. Make sure you have white-space:pre-wrap; and display: block; as they are both required for proper display. Upload your edited stylesheet to includes/jquery/styles/ (or to your theme style directory for theme specific styling) and remove any unused styles from the styles directory. Also a good idea to upload a blank index file (an empty text file saved as index.html) to the includes/jquery/styles/ directory as a security measure.

Limitations: Automatic language detection seems to work differently in Internet Explorer, nothing critical but you may want to declare the language class when you can for consistent styling across all browsers. However, what self respecting web developer is using IE these days, unless they are goofing off at work? Also, the filtering on the nukeWYSIWYG editor will strip backslashes off of escaped quotes, which will not only break the highlighting, but your code sample itself. Keep this in mind when posting code! Notice in this example (sample only) code snippet we used double quotes instead of escaped single quotes for the jQuery function

	$inlineJS = '<script type="text/javascript">$(document).ready(function() {
      $("pre").each(function(i, e) {hljs.highlightBlock(e, "    ")});
    });</script>'."n";

Manual Language Detection: The automatic language detction of this script works as well or better than any of the other big name syntax highlighters, but may have trouble identifying the language of some code snippets, especially small ones. But don't worry, you can manually assign the language by adding a class to the <pre> tag:

<pre class="php">PHP Code</pre>
<pre class="sql">SQL Code</pre>
<pre class="javascript">JavaScript Code</pre>
<pre class="html">HTML/XML Code</pre>
<pre class="css">CSS Code</pre>

With that, you should be good to go.. Consult our forums with any issues [link]. Although most of their support threads are in Russian, More detailed info on usage of Highlight can be found at http://softwaremaniacs.org/forum/highlightjs/, or the readme file included in the highlight download.