Syntax Highlight module for Sitecore

20 May 2015
Alan Plocieniak
Frink_Cognifide_2016_HeaderImages_0117

Introduction

While doing some research on a module for syntax highlighting in Sitecore, I found this blog post.

Alexander provides a very fast and low-effort solution using a command for code formatting and FormatCodeBlock.aspx file, built into Sitecore. I was really impressed until I realised that the solution provided is a little outdated because it works only for Sitecore 6.3.0 and older versions.
The Rich Text Editor used in Sitecore has been upgraded to the newest version of the Telerik's RadEditor for ASP.NET AJAX. The new version provides some improvements like the in-line AJAX spell-checker and some architectural changes so the folder 'Website\sitecore\shell\RadControls\' with easy to modify aspx files is no longer available.

Since I still wanted to have the tool for code insertion and a highlighting feature, I decided to write it, from the beginning, by myself. Like Alexander, I integrated an external java script library called SyntaxHighlighter by Alex Gorbatchev (really well made lightweight library, used in many other solutions). During the development, I focused on the version compatibility, so it should be easy to use with the new versions of Sitecore.

In the next sections, I will point out key features and describe how to integrate and use the SyntaxHighlight module.

The module was developed and tested on Sitecore.NET 7.2 (rev. 140526), all packages are dedicated for this version. If you want use it with other version, please perform the manual installation described later in this article.

Features

  • An easy way of adding and editing new or existing code with SyntaxHighlight button:
    Click to add a new code snippet or select the existing piece of code before, to load the code content into the editor.
    new syntaxhighlight button in RichText editor
  • Code editing window totally separated from Sitecore:
    A new window is decoupled from Sitecore (pure HTML and JS, no XML nor server-side logic), thus it is easy to port it onto other Sitecore versions, with a few style fixes.
  • Advanced options:
    You are able to highlight some lines, hide gutter (numbers) or start indexing from a different number (for example if yours shows a piece of code that is part of a bigger one). 
  • Different styling:
    Fit the code snippets to your needs. Choose a different theme if your page design do not match the default one.

SyntaxHighlight module installation and configuration

You've got two options: install the modules using the package or do it manually, by yourself, step by step. The second option is recommended especially for people who already have some custom code in RichText Commands.js. 
That is the only core file that was overridden.

Manual installation

  1. Unzip this archive into your Website folder. It contains all the module scripts which will be located in the sitecore modules folder.
  2. Next navigate to Website\sitecore\shell\Controls\Rich Text Editor folder and open RichText Commands.js file.
    Append SyntaxHighlight command definition into RadEditorCommandList
    var scEditor = null;
    var scTool = null;
    var scDatabase;
    
    RadEditorCommandList["SyntaxHighlight"] = function (commandName, editor, args) {
        scEditor = editor;
        editor.showExternalDialog(
            "/sitecore%20modules/shell/syntaxhighlight/syntaxhighlight.html",
        null, //argument
        600,
        390,
        scInsertCode, //callback
        null, // callback args
        "SyntaxHighlight",
        true, //modal
        46, // behaviors
        false, //showStatusBar
        true //showTitleBar
        );
    };
    
    RadEditorCommandList["InsertSitecoreLink"] = function (commandName, editor, args) {
    After that, go down and paste the callback function 
    function scInsertCode(sender, returnValue) {
        if (scEditor.getSelectedElement().tagName == "PRE") {
            scEditor.getSelectedElement().remove();
        }
        scEditor.pasteHtml(returnValue.text);
    }
  3. Then open Sitecore core database, find the HTML Editor profiles (/sitecore/system/Settings/Html Editor Profiles) and create new item under Toolbar with the following click command: 'SyntaxHighlight' (use Html Editor Button template).
    Create Code Button
  4. Now you should move it to the Post installation configuration section and configure the module to your needs.

Automatic installation

  1. Install the SyntaxHighlight module using this package (compatible with Sitecore.NET 7.2, rev. 140526).
    Please bear in mind that the module overrides default Sitecore file (RichText Commands.js), so be careful if you already have some custom stuff in there, you will loose it when you install the package automatically.

Post installation configuration

  1. Configure which languages would you like to support.
    By default, all possible languages were added. If you want to get rid of the unnecessary languages, edit options object in SyntaxHighlight.js file
        var options = [
            ['Plain (Text)', 'plain'],
            ['Bash (Shell)', 'bash'],
            ['AppleScript', 'applescript'],
            ['ActionScript3', 'as3'],
            ['ColdFusion', 'cf'],
            ['C#', 'csharp'],
  2. and remove redundant script tags in SyntaxHighlight.html file
       <!--Remove unnecessary languages-->
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushPlain.js"></script>
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushBash.js"></script>
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushAppleScript.js"></script>
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushAS3.js"></script>
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushColdFusion.js"></script>

  3. The next step is to include scripts and the style file (scripts should be the same as defined in SyntaxHighlight.html) into your layout. For example Sample layout.aspx
        <link href="/default.css" rel="stylesheet" />
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shcore.js"></script>
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushPlain.js"></script>
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shbrushcsharp.js"></script>    
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushJScript.js"></script>    
        <script type="text/javascript" src="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/scripts/shBrushPowerShell.js"></script>    
        <link href="/sitecore modules/shell/SyntaxHighlight/syntaxhighlighter/styles/shcoredefault.css" rel="stylesheet" type="text/css" />
        <sc:VisitorIdentification runat="server" />

That was the last step. SyntaxHighlight is ready to use.

Advanced configuration and improvements

Mysterious scrollbar

I noticed that SytnaxHighlighter sometimes shows a scroll bar for no reason, like here. 

The fix for that is to append somewhere this piece of css

 .syntaxhighlighter {
     overflow - y: hidden!important;
     overflow - x: auto!important;
 }

Different theme

To achieve different themes, all you have to do is load different CSS file (default file is shcoredefault.css). Follow this page to check how other themes look like http://alexgorbatchev.com/SyntaxHighlighter/manual/themes

Summary

I hope that you will find this module useful. Happy highlighting!