EscapedMarkup

Summary: Allow a selection of markup rules to be performed for otherwise escaped text
Version: 2012-09-25
Prerequisites: Must have Toolbox installed
Status: Functional
Maintainer: Peter Bowers?
Categories: Markup
Users: (view? / edit)
Discussion: EscapedMarkup-Talk

Questions answered by this recipe

  • Have you ever wanted to put some wikitext inside to escape the text, but you still wanted to emphasize a certain portion of that text or to provide variable substitution or in some other way perform certain markup rules over that wikitext?

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

Allow escaped text to contain active markup.

Installation

  1. Download and install Toolbox.
    1. Put toolbox.phpΔ in your cookbook directory
    2. Place this code in your config.php (or farmconfig.php or etc.)
include_once("$FarmD/cookbook/toolbox.php");
  1. Download EscapedMarkup.phpΔ and place it in your cookbook directory
  2. Place this code in your config.php (or farmconfig.php or etc.):
$EnableEscapedMarkup = true;
include_once("$FarmD/cookbook/EscapedMarkup.php");

Configuration

By default this recipe only runs the {$var} rule (for variable substitution) and the '''...''' (for strong text) over text escaped using the [$...$] type of escape. (This [$...$] is new markup provided by this recipe.) That default is accomplished using a line such as this:

$EscapedMarkupRules['$'] = array('{$var}', "'''");

Note that the index to the array is '$' which corresponds to the dollar signs in the [$...$] markup. Note that the names of the rules which are run are the values in the array being assigned ({$var} and '''). These are the keys to further configuration.

If you wish to execute those same markup rules over the [@...@] markup and the [=...=] markup then the line in config.php would look like this:

$EscapedMarkupRules['@'] = array('{$var}', "'''");
$EscapedMarkupRules['='] = array('{$var}', "'''");

Note that the $ has been replaced with a @ and =, corresponding to the character used in the escape markup. Each can be set independently. By default [@...@] and [=...=] are unchanged and so no markup rules are run over text within those blocks.

Changing the rules on the right side of this assignment results in a different set of rules being executed over your text. If you wanted [[WikiLinks]] and [++large text++] rules to be executed in addition to the {$var} and ''' rules used above then the line in your config.php file might look like this:

$EscapedMarkupRules['$'] = array('{$var}', "'''", '[[' '[+');

You can find a list of the names of markup rules on your site by appending ?action=ruleset to your URL. (Note that you must have $EnableDiag set to 1 for this to work.)

Usage

Simply make use of markup within your escaped text and the text will be marked up as you wish. Be sure that the markup you choose to escape the text (using [@...@] or [=...=] or [$...$]) corresponds to the @ or = or $ used as the index to $EscapedMarkupRules in your configuration. If you haven't changed the defaults then only [$...$] will show any change.

Assuming the default configuration, when you put this source on a page:

[$This is some '''escaped''' text on the page {$FullName} and [[Links]] are not active.$]

you will see something that looks like this:

This is some escaped text on the page Cookbook.EscapedMarkup and [[Links]] are not active.

You will note that the ''' rule and the {$var} rule were executed while the [[ rule (for links) was not executed.

Notes

Change log / Release notes

  • 2012-09-25 Original Release

See also

Contributors

Comments

See discussion at EscapedMarkup-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.