Syntax Anywhere

This page describes the use of Syntax Anywhere for concrete5.6. Syntax Anywhere for concrete5.7+ is very similar, so much of this page also applies. However, the 5.7 version of Syntax Anywhere does not have th language selection tab. The syntax processors provided by that version all provide automatic language detection.

User Guide

The trouble with syntax highlighting blocks is just that. They are blocks. Great for big listings or the odd scrap of code, but when writing documentation it can be a hassle to have to mix and match paragraphs between other block types and your favoured syntax highlighting block. Hence Syntax Anywhere. Syntax Anywhere can be configured to detect sections of code within pretty much any block you can write fragments of code into, whatever the programming or markup language.

Syntax within a content block

This introduction and the next few examples are within a single content block with code sections in <pre> formatted text. 

Syntax Anywhere locates section of code to highlight and applies highlighting from a syntax processor. For example, using a section of <pre> formatted text:

class JlSyntaxAnywherePackage extends Package {

    protected $pkgHandle = 'jl_syntax_anywhere';
    protected $appVersionRequired = '5.6.1';
    protected $pkgVersion = '0.9';

    public function getPackageDescription() {
        return t('Apply the syntax formatting to sections within the content of other blocks.');
    }

    public function getPackageName() {
        return t('Syntax Anywhere');
    }

The block above was inserted using Syntax Anywhere. It was detected as a <pre> section by Syntax Anywhere and processed into nicely highlighted code. The code shown below uses Syntax Anywhere with a double wrapper so the <pre> element containing the code is now shown and syntax highlighted as html. You could put this code into a content block and it would be highlighted to look like the code above.

[code data-syntax_anywhere_settings='{"language":"html"}']

class JlSyntaxAnywherePackage extends Package {

    protected $pkgHandle = 'jl_syntax_anywhere';
    protected $appVersionRequired = '5.6.1';
    protected $pkgVersion = '0.9';

    public function getPackageDescription() {
        return t('Apply the syntax formatting to sections within the content of other blocks.');
    }

    public function getPackageName() {
        return t('Syntax Anywhere');
    }

[/code]

Language Selection

20_edit_language.pngThe pull down menu in a Syntax Anywhere block sets the default language syntax that will be applied. But what if you want to mix languages? The setting in the edit dialogue is only a default and can be overridden by a syntax processor auto-detecting a language.

Where the language cannot be auto-detected, the language setting can be overridden by local settings specified using a snippet of JSON in a data-syntax_anywhere_settings element attribute. Here is an example using data-syntax_anywhere_settings to specify css:

div.some-pretty-box{
  color:#8080FF;
  background:#E0E0FF;
  border:1px solid rgba(60, 15, 93, 0.05);
}

Again using a double wrapper so you can see what is under the hood, the code that Syntax Anywhere processed to give the above was:

[code data-syntax_anywhere_settings='{"language":"html"}']

<pre data-syntax_anywhere_settings='{"language":"css"}'>div.some-pretty-box{
    color:#8080FF;
    background:#E0E0FF;
    border:1px solid rgba(60, 15, 93, 0.05);
}</pre>

[/code]

While here, have a look at the little colour icon at the top right of the highlighted code. It pops up colour palette of the colours used!

The pulldown menu for languages contains the most common languages of interest to web developers. The actual syntax processors support a considerably wider range of languages. If you need to highlight such languages and they are not auto-detected by the syntax processor, the data-syntax_anywhere_settings attribute should be used to specify the language.

In fact, you can use data-syntax_anywhere_settings to override many of the Syntax Anywhere settings for any section of highlighted code. For example, you can have some sections with line numbers and some without, different background colours and different escaping.

Selecting and marking code to highlight

30_edit_selection.pngEach Syntax Anywhere block can also have its application targeted using jQuery selectors. So another way to handle different languages is to set up one Syntax Anywhere block for each language and use selectors, such as a language class in the detected <pre> wrapper, to discriminate between them.

Sometimes a simple <pre> element is not specific enough.  Syntax Anywhere can be configured to find and highlight code within  <pre> elements, <code> elements, sections marked [code][/code] and/or these elements or any element with a  "syntax_anywhere" or "jl_syntax_anywhere" class. 

For some of the 'how syntax anywhere did that' versions of the examples above, the [code][/code] markers have been used with a data-syntax_anywhere_settings attribute within the code marker. I am afraid that is where the level of tortuous self-defining recursive documentation gets a little bit too complex to show, so if you want to do that you will need to work out the details for yourself.

Highlighting PHP and JavaScript

70_edit_tag_correction.pngThere can still be some tricky moments. Suppose you want to insert some PHP or HTML including
<?php ... ?> tags and sections within HTML, or JavaScript and show its <script> tag without it being stripped for security or actually being executed. Again, Syntax Anywhere offers multiple ways of doing this.

A common convention that Syntax Anywhere can work through is to escape the tags using &lt;php ... ?&gt; or &lt;script &gt;, so that the browser does not process them. Syntax Anywhere can then unescape the tags.

First, a section of JavaScript:

<script>
$(document).ready(function(){
    $('#my_element').css('background-color','#80ffc0');
});
</script>

Again to see the power of syntax anywhere, the same section of JavaScript 'under the hood':

[code data-syntax_anywhere_settings='{"language":"js"}']

&amp;lt;script&amp;gt;
$(document).ready(function(){
    $('#my_element').css('background-color','#80ffc0');
});
&amp;lt;/script&amp;gt;

[/code]

Another optional setting under the Tag Correction tab in Syntax Anywhere is to convert tags with a prefix <sa_tagname> to <tagname>. Which you use depends on the how the block you are working with processes arbitrary tags.

Finally, some blocks (such as the HTML block), will comment out <?php ... ?> sections as <!--<?php ... ?>-->. Syntax Anywhere includes an option to remove such comments and hence highlight the <?php ... ?> tags and their content.

Syntax in other block types

Syntax Anywhere is not just limited to content blocks. It will work with any block that supports the tags and markers it can key on. With Syntax Anywhere you can highlight syntax in html blocks, many derivatives of content blocks, markdown blocks and files, and even blocks you have created using Designer Content.

Some blocks such as markdown will wrap code sections in nested sets of <pre> and <code> tags. If you don't want the inner tags appearing in your highlighted code, Syntax Anywhere provides options under the Tag Correction tab to remove wrapping <pre> and <code> tags.

Syntax Processors

50_edit_processor.pngWhere a page is using a combination of Syntax Anywhere and actual syntax highlighting blocks, such as the Highlighted Code Block, Syntax Anywhere can be configured to output compatible highlighting.

Syntax Anywhere comes with syntax processors that use:

  • The Google Syntax Highlighter - as used in the examples above, together with a selection of themes
  • The Highlighted Code Block, with added colour mapping should you decide you want to adjust the colour scheme.

By adding multiple Syntax Anywhere blocks to a page with suitably constrained selectors, you can even use different syntax highlighters for different snippets of code.

The syntax processors that Syntax Anywhere uses are actually plugin models. Should a developer have a favoured syntax highlighter, it can easily be incorporated into Syntax Anywhere by creating a plugin model to interface to that highlighter. The Syntax Highlighters provided with Syntax anywhere have been chosen so as to provide examples for:

  • a JavaScript highlighter (Google Syntax Highlighter), which is called directly from the Syntax Anywhere JavaScript.
  • a PHP highlighter (Highlighted Code Block), which is called by an AJAX callback to process the syntax on the server and return it to the display.

Syntax processor plugins are automatically detected by the edit dialog and are also summarised by a dashboard page at dashboard > script > syntax_anywhere.

Enable and Disable

Syntax processing can be enabled and disabled in the Advanced tab of the edit dialog. Should anything really bad go wrong, you can also globally disable Syntax Anywhere by defining the config/site constant

[code data-syntax_anywhere_settings='{"line_numbers":0}']

define ('SYNTAX_ANYWHERE_ENABLE', false);

[/code]

Syntax Anywhere is, by default, disabled in Edit Mode and a marker shown with the settings as JSON. 

[code data-syntax_anywhere_settings='{"line_numbers":0}']

{"language":"php",​"tab_width":"3",​"line_numbers":"0",​"wrap":"1",​"select_pre":"1",​"container_selector":"#main-content-container",​"exclude_selector":"",​"tag_decode":"1",​"unescape":"1",​"sa_prefix":"1",​"php_tag_fix":"1",​"show_edit_marker":"1",​"processor_handle":"google_code_prettify",​"sa_google_code_prettify_theme":"svn/loader/prettify.css",​"sa_google_code_prettify_escape_tags":"1"}

[/code]

This can be useful if you want to create some local settings. Just set them in a Syntax Anywhere block and pick the setting you want from the JSON shown by the edit mode marker.

If you don't want to see the edit mode marker, or if you want to risk applying the syntax processing when in edit mode, these settings can be changed in the  Advanced tab.

For Developers

Syntax Anywhere is an addon designed to help developers write documentation. As such, the edit dialog assumes that users have some developer level knowledge of things like html tags and attributes, jQuery selectors and JSON formatted data.

If you want to create a further syntax processor plugin, the existing plugins contain plenty of comments explaining how to do so. Plugins should be models located in the usual override folders:

  • site_root/models/syntax_anywhere/syntax_processors/
  • packages/package_handle/models/syntax_anywhere/syntax_processors/

Syntax processor plugins should extend the class SyntaxAnywehereSyntaxPluginBase, as per:

Loader::library('syntax_anywhere/syntax_plugin_base', 'jl_syntax_anywhere');
class SyntaxAnywhereSyntaxProcessorsSyntaxHighlighter extends SyntaxAnywehereSyntaxPluginBase {

    public function getName(){
        return t('Syntax Highlighter');
    }

 

 

Last updated: 12 months ago