Documentation

Installation

Installing Syntax Anywhere provides a Syntax Anywhere block, a template for the core HTML block and two dashboard pages: one page for the global settings and one providing built-in documentation for the syntax processors provided. The Syntax Anywhere block can be found in the Developer section of the block add slide-out.

  • Block: Syntax Anywhere, in the Developer section of the block add pull out
  • Block template: Syntax Anywhere template for the core HTML block
  • Dashboard Page: Syntax Anywhere > Global Settings
  • Dashboard Page: Syntax Anywhere > Syntax Processor Plugins (with built in documentation)

Getting started

Following installation, you probably want to add a Syntax Anywhere block to a test page and experiment with the available settings to explore the possibilities available.

Add the Syntax Anywhere block with the default settings. The only thing you may need to initially change is the Overall container selector on the Selection tab. The default of "main .container" is OK for Elemental and many Elemental and Bootstrap derived themes. For Fundamental and Foundation based themes, the selector would be "main .row".For other themes, you will need to look at a page in your browser developer console and pick a css selector #id or .class appropriate to the theme, or ask your theme developer to advise you.

With the Syntax Anywhere block saved, add some [code][/code] markers within a content block and then paste some code between those markers. The content block will not show code cleanly, but that doesn’t matter because when you save and publish the test page Syntax Anywhere will seek out the [code]...[/code] markers and highlight the code between them.

If you want a cleaner layout within your content block, create a html <pre>….</pre> section or <code>….</code>  section in a core Content block or core HTML block and post your code within that. You will also need to either configure Syntax Anywhere to use <pre> or <code> as selectors or add a class such as <pre class="syntax_anywhere"> to the marker tags.

With basic highlighting now running, you may want to have a look at the Tab Correction panel and if necessary adjust the way Syntax Anywhere tranlates source to clean up what a content block does to it.

You can also look at the Syntax Processors tab and have fun experimenting with different themes or Syntax Processors to see the many variations available for how your code snippets to be shown.

Having experimented and now knowing what your typical settings will be, you can go to the dashboard page at Syntax Anywhere > Global Settings and configure the default settings for the Syntax Anywhere block. These are the settings that will be used by default each time you add a Syntax Anywhere block to a page, so setting things up in the dashboard now can save you a lot of time editing blocks later.

Global implementation

When you next add a Syntax Anywhere block to a page, the global settings you saved in the dashboard will be used as default settings for the new block.

If you want to add Syntax Anywhere to all pages on your site, you can do any of:

  • Simply enable the global application of Syntax Anywhere in the dashboard. That will apply Syntax Anywhere globally with no need to add Syntax Anywhere blocks to pages.
  • Add a Syntax Anywhere block to a global area.
  • Add Syntax Anywhere blocks to specific page types using page type defaults.
  • Add Syntax Anywhere blocks to each page individually. 

Adding blocks individually can still be controlled globally because, when you add a Syntax Anywhere block, one of the options is to simply use the global settings, so allowing many blocks to be configured centrally from the dashboard, or to adapt settings specific to an individual Syntax Anywhere block.

You can even enable Syntax Anywhere globally, but then add a Syntax Anywhere block to a page and override the global settings. 

Enabling Syntax anywhere globally will load Syntax Anywhere for all pages of your site. If you only plan to show highlighted syntax on one or two pages, that could be an unwanted overhead, in which case you should add the block page by page.

Multiple blocks on a page

Be careful about using multiple syntax hignlighting themes within a page. If you need to do that for different formats, such as different hignlighting themes between the Main and Sidebar areas or because you want to show different programming languages with diffgerent themes, then its safest to use different syntax processors for each theme. Within any third party syntax processor, the syntax hignlighting themes generally cannot coexist. Using different syntax processors can get round that.

Edit Dialog

The edit dialog is similar between blocks and the global settings. The main difference is that blocks include a checkbox to simply follow the global settings.

Selection

The Selection tab governs how Syntax Anywehere decides what parts of a page to apply Syntax Anywhere to. The checkboxes provide some general selection options and you can check as many as you like as long as it there isn’t anything else on your pages that could match by accident that you don’t want to be highlighted. In general, the only thing to be really careful about using are <pre> tags without any additional qualification - check the <pre> tag is not used elsewhere in your pages before you do so.

Below the checkboxes are text inputs for selecting what parts of the html are checked and what are excluded. As explained above, the default of  "main .container"  is good for Elemental, but you could need to use different selectors for other themes.  "main .row" would be a good stariung point for  Fundamental and Foundation based themes. Have a look at any page using your browser developer console and pick a css selector #id or .class appropriate to your theme.

These selectors are passed straight to jQuery and follow the normal rules of CSS selectors.

Display

The display tab governs the starting point for how syntax highlighted sections are shown. The Syntax Processors (next tab) in many cases do their own thing when it comes to highlighting, but what you set here for text and background colour may override aspects of a syntax highlighting theme.

Font size, tabs, wrapping and line numbers are generally independent of syntax processor. A nice little extra is Show palette of numeric colours from code. When checked, Syntax Anywhere will check for hex and rgb colour codes and provide a pop up palette to the top right of each highlighted section.

Syntax Processor

Syntax anywhere uses a plugin architecture to integrate a range of proprietary and third party syntax processors. Many of these provide a massive choice highlighting themes and additional options for how they interact with the overall Syntax Anywhere options. In most cases you can leave the checkboxes at their default values and simply pick a theme you like.

Prcessor selection pops up a list of the available syntax processors. More details on each can be viewed by clicking the (i) symbol for more information. Similar documentation can be viewed on the Syntax Processors dashboard page.

Tag Correction

Depending on the way code fragments are pasted into a page: the rich text editor used, html blocks, markdown blocks and whatever text inclusion blocks are available, the blocks may themselves mutate the code snippets you paste into their edit dialogs. Tag Correction can be used to correct for whatever blocks do. For example, pasting code straight into a regular content block will result in each line being wrapped in <p> tags. Syntax Anywhere can remove those tags to restore the code fragment to what you want to show.

Be particularly careful about posting code containing <script> tags inro html. Syntax Anywhere provides a way round this by allowing you to post tags starting <sa_script (and ending </sa_script), or [script]….[/script]. So a minor edit of your source can be used to allow it to be processed by Syntax Anywhere without any risk of <script> in the source being sanitized or accidentally executed in the browser!

Advanced

You are unlikely to need to change any settings on the Advanced tab. These settings are mostly of use to developers integrating further syntax processors. Most of these settings are self explanatory.

If you find that Syntax Anywhere is processing syntax out of sequence with other JavaScript or jQuery based addons, or perhaps some content is loaded late, the option to Delay syntax processing can provide a quick solution. Sometimes just a 1ms delay is all you need to push Syntax Anywhere to the end of a sequence of jQuery ready handlers. 

If your pages have ajax loaded sections containing code fragments to be highlighted, you can trigger do_syntax_anywhere at any time to a check for further code fragments that need to be highlighted, such as a <pre class="syntax_anywhere"> tag. This is a developer option because you will need to add JavaScript to an ajax loader to trigger this event when ajax loading completes. Sliding Delay syntax processing all the way to the right means that Syntax Anywhere will not begin any processing until the JavaScript event do_syntax_anywhere, leaving when to check for code fragments entirely in your own code.

Support

If you need support, links are helpfully provided in the Support tab. When opening a support request, it can help me a lot if you use the Export Settings button to copy the block settings in JSON format and paste these settings into the support request.

The adjacent Import Settings button allows you to paste previously exported settings into Syntax Anywhere. You can use this to copy block settings between blocks or even between sites.

If you don’t want all your site editors to have access to this part of the edit dialog, an option at the bottom of the page allows you to hide it from all but the Super Admin user and only show to the Super Admin in the dashboard page.

Global Application

On the dashboard settings page, enabling Global Application will attach Syntax Anywhere to all pages on your site using the Global Settings. With Global Application you don’t need to add Syntax Anywhere blocks to individual pages. This can be a really big convenience and timesaver for developers writing code or css design blogs and for documentation sites.

When Global Application is enabled, you may also want the flexibility of different Syntax Anywhere settings on some pages. If you now enable Check for blocks on page to override global setting, you can add an individual Syntax Anywhere block to a page and this will take over from the global settings. However, that does involve additional processing when every page is shown, so if you only ever want global application, with no exceptions, this setting can be be left skipped.

Highlighting typical web code

For many users, the primary use of Syntax Anywhere will be to insert some PHP or HTML including php or JavaScript.

For security, various types of content block will sometimes sanitize or even completely strip <?php ... ?> or <script> tags. Even worse, you could end up with a <script> tag getting onto a page and actually being executed! Syntax Anywhere offers multiple ways of working through these obstacles.

If you paste a code fragment straight into a regular content block without using the <> html mode, the content block will escape all tags and make every line of code into a paragraph. It won’t look nice or correct in edit mode, but when you publish the page Syntax Anywhere will detect the section of code and undo all the mashing up the content block has inflicted to present nicely formatted code.

If you want to edit code directly within a content block rather than paste it into place, its can be easier to swap the content block to the <> html view or use an html block or markdown block. Here we have some options:

  • Syntax Anywhere can detect sanitized <?php...?> php tags and restore them.
  • Syntax Anywhere can detect escaped tags. So you could use &lt;php ... ?&gt; or &lt;script &gt;, so that the browser does not process them and Syntax Anywhere will then unescape the tags.
  • Syntax Anywhere can convert tags with a prefix <sa_tagname> to <tagname>. So you can write script sections as <sa_script></sa_script>  and if necessary write php sections as <sa_?php ... ?_sa>. Block edit dialogs and browsers will not do anything with such sa_ coded tags, leaving them for Syntax Anywhere to find and format back into the code you originally wanted to show.
  • Syntax Anywhere can also be set to convert [tag] to <tag>. Sometimes that is easier, but it also presents difficulties as it can be confused with array[index]. 
  • You can use the Syntax Anywhere template for the core HTML block (see below)

Which of the above paths you follow depends entirely on what you want to do and the way you like to write. 

Syntax Anywhere template for the HTML block

Syntax Anywhere provides a special Syntax Anywhere template for the core HTML block. You don’t need to use this template because Syntax Anywhere can pick up sections of code to highlight anywhere in the output of this and other blocks. However, sometimes it can be useful to have a simple block that you can just paste anything into and it will be highlighted.

The Syntax Anywehere template for the HTML block will highlight the entire content of the block, whatever is pasted into the block and you don’t need to think about escaping any script tags first. The Syntax Anywhere template escapes the content and wraps it with a <pre class="jl_syntax_anywhere syntax_anywhere"> tag. So all you need to do is to assign the HTML block the Syntax Anywhere template and enable Syntax Anywhere with jl_syntax_anywhere or syntax_anywhere as the selector.

In practice, its usually best to add an empty HTML block, assign the template, then edit again to add your code. That way, the block is never rendered with unescaped code in it!