Code Highlight Example

Code Higlight Example

When you're like me, amoung other also a software developer(isch) kind of guy, you probably like to share some code sometimes. Presenting code clean and pretty readable is then mostly desired in these cases. There can be a lot of packages be found on the web, that can accomplish this task, by taking out of your hands the styling of a block of code.

In general, it involves enclosing the block of code – which can be any coding language you like – in between a set of HTML mark-up tags. Usually, this will be the <pre></pre> tags, that indicates the start and end of the code block.

The actual code will then be be placed between these tags. But since it is code, it must be marked as such, which why it is also enclosed within the <code></code> tags as well. So the whole sequence will therefore be written as <pre><code> .. code .. </code></pre>.

After testing some of the available packages in the past, I've now settled on the Prism package, which is both light-weight and has the options to install plug-ins, like a copy button. More information can be found at prismjs.com

Example of a paragraph with highlighted code

How Prism is installed and used we will explain further down this document. Let's start with an example first, to give an idea what the output looks like.

The following fragment was taken from a document about this sites engine, an earlier version explaining the operation of one of the classes.

Excerpt starts here >>>

The function ProcessURL()

// Page reference key
private static $PAGE_INFO_KEY;

public static function ProcessURL() {
  // Check the host the request was made to, and redirect if necessary
  self::checkHost(); 
  // Check the HTTPS status, redirect if necessary
  self::checkHTTPS();

  self::$PAGE_INFO_KEY = self::getPageArrayKey();
  if (self::$PAGE_INFO_KEY === false) {
    self::send404Headers();
    self::$to_show = self::$FILE_NOT_FOUND;
    return "404";
  }
  else {
    $page_array = self::getXmlPageInfo(self::$PAGE_INFO_KEY, '*');
    self::checkRedirectRequest($page_array);
    self::ensureHTMOrSlashExtension(self::$PAGE_INFO_KEY);
    self::$to_show = $page_array;
  }
}

>>> Excerpt ends here

Using Prism in your documents

Downloading the code

The download of Prism consists of two files only: prism.js, which holds the JavScript code and prism.css, which holds the CSS code. The download procedure itself, is not as one might expect though: click on a file link to start the download.

Instead the developers have chosen a different approach, by that you first make a selection from one of the themes, then select a programming language to support (besides the default set) – this can be a single one, multiple or even all, and last by selecting the desired plug-ins (more on that later).

All your choices will collected at the end of the lists, where then you will find the download buttons. These now first combine al choices into a single for JavaScript and CSS, after which the download for each file starts. This way the code and styling is very light-weight.

Installing Prism

Installing Prism is rather easy, by placing a link for the CSS file in the header of your page, just like you would do with any other CSS style sheet. But this is only the styling, not the code.

Using Prism on your HTML document

What's left is using the code, to highlight your code block, as we described above. First, load the JavaScript code somewhere within de body of your HTML page, so after the <body> tag. The exact location does not really matter, just be sure to place it before any code block you want to insert.

...
<body>
    <!-- Prism script -->
    <script src="public/highlight/prism.js"></script>
    ...

Then you will insert your code block. Start with the <pre> tag, followed with the <code> tag, which we will assign the class for the language to display. Then comes the actual code, followed by the two closing tags.

<pre><code class="language-php">
    // Some php code
    if ($a > $b) {
        $c = 10;
    }
</code></pre>

Displaying HTML code tags - a bit tricky

There is one thing with HTML code tags, that you will have to sort out before you can successfully display it. Every tag needs to be escaped, otherwise it won't work. If you would take a look at the page source of the top code block above, where we inserted the JavaScript code, you would see some rather weird writing.

&lt;body&gt;
    &lt;!-- Prism script --&gt;
    &lt;script src=&quot;public/highlight/prism.js&quot;&gt;&lt;/script&gt;
    ...

To correctly display HTML tags, we need to use special characters instead of the real character, for the opening and closing of a tag. For example the character ‘ < ’ needs to be written as ‘ < ’. This is of course a real PITA if this needs to be done by hand.

For the Prism script, there is a plug-in avail;able, that can do this for you. But I find it not that useful and it comes with precautions. It is called the Unescaped Markup plug-in.

There is another solution for this problem, that can be solved with a built-in PHP function. And since the site is powered with PHP anyway, it is easy to implement. The PHP function is called htmlspecialchars() and it escapes the &, ", < and > characters.

Implement PHP function

...
<body>
    <!-- Prism script -->
    <script src="public/highlight/prism.js"></script>
    ...

The code above is escaped using the PHP function. Implementation is so simple, there's no need for a wrapper function and we can use the function as is. Placing this is however critical, otherwise you might end up with a extra empty line at the start.

To prevent this from happening, the PHP in-line statement must follow directly after the opening <code> tag. The example below will show this in detail. The HTML code to display is then placed inside single quotes.

<pre><code class="language-html"><?php echo htmlspecialchars(
'...
HTML Code
...
'); ?>
</code></pre>

Please observe the location op the opening and closing single PHP quotes. Everything between them is traded as literal characters, including the spaces and returns. This is however not the case with the return / linefeed before the opening quote, it is ignored.

Single quotes in PHP string

IMHO this is easier than relying on other methods. There is still one quirk though, that will require some handy work. Usually, PHP strings are enclosed in single quotes.

If anywhere in the HTML code single quotes are used, this will break the PHP string. These single quotes also need to be escaped in PHP fashion, with a single backslash. This is often the case, when JavaScript commands with arguments, are embedded in the HTML.

NOTE: carridge returns

If you you enter a carrige return inside the <code></code> tags, and start typing on the next line, a blank line space will be included. To avoid this, start typing on the same line as the <code> opening tag.

Code Highlight - customisation

The standard Prism code just highlights the selected code. But Prism supports plug-ins that add functionality, that can be useful.

Copy text plug-in

A button that lets you easily copy the block of code, I would deem a option that should be standard. So make sure that you select this plug-in before downloading the Prism code. Please note that the Toolbar plug-in is also required. There is no further action required to use this plug-in.

Download code file plug-in

If you also want to share you're code as a source file, then this plug-in comes handy. It also requires the Toolbar plug-in to be installed. Follow the instruction on the plug-in page, how to use it.

Personal touch

I've made a small adjustment to the css : the font-size is set to 0.9em and the line-height is set to 1.2em, instead of the default 1 and 1.5 respectively. I find it more readable that way, a bit more compact then the standard settings.

Welcome at the Ebkoz-Lab