(Tested with MODx revision 0.9.5.)
Goal: To be able to write about MODx snippets on a web page without that same snippet trying to interpret any mention of itself in unpredictable ways.
Suppose, for example, you are discussing the well-known Wayfinder plug-in on a web page. What happens if you include the string “[!Wayfinder!]” while discussing Wayfinder? The user will never see it. Wayfinder sees it first, and replaces it with something else.
To prevent this, you will need to replace some of the special characters with their corresponding html entities. For example, instead of the left square bracket “[” you can use the code “[”. Wayfinder will leave this alone.
This gets very tedious if you are writing a long web page with numerous examples of MODx snippets, chunks, and modules.
How about just using the <pre>…</pre> tags? These tags preserve line formatting but they do not cause any characters to be escaped. Even if they did, that would not help, because the MODx snippets, chunks, and plugins operate on your text
before it is sent to the user’s web browser. By the time the browser gets the web page and begins to interpret tags on it, the damage has already been done.
What I needed was a special tag that a component within MODx would process before it sent a web page to the browser. This tag would cause all enclosed text to be quoted before any other component within MODx saw it.
Here, then, is the “<fixedpre>” tag. You can add it to your MODx CMS as follows.
Create a Plugin
On the Site->Home->Resources->Plugins tab, create a new plugin called “plugin.fixedpre.tpl”.
On the General tab, into the Plugin code (php) box enter the code given below.
// plugin.fixedpre.tpl -- implements <fixedpre> tag -- Rahul Dhesi
// http://rahul.rahul.net/modx-hints/fixedpre-tag.html
function quote_meta($a) {
$lhs = array("<", ">", "[", "]", "!", "{", "}", "`");
$rhs = array("<", ">", "[", "]", "!", "{", "}", "`");
$b = str_replace("&", "\255", $a[2]); //save "&"
$lhs_preg = array('|<!(!*)fixedpre>|', '|<!(!*)/fixedpre>|');
$rhs_preg = array('<$1fixedpre>', '<$1/fixedpre>');
$b = preg_replace($lhs_preg, $rhs_preg, $b);
$b = str_replace($lhs, $rhs, $b);
return str_replace("\255", "&", $b); // restore "&"
}
$e = &$modx->Event;
if ($e->name == "OnLoadWebDocument") {
$modx->documentObject['content']=
preg_replace_callback("#(<fixedpre>)(.*?)(</fixedpre>)#s",
"quote_meta", $modx->documentObject['content']);
}
On the System Events tab, check the box for OnLoadWebDocument. All the other boxes on that tab should be unchecked.
Do a Save.
Now go to Site->Home->Plugins->Edit Plugin Execution Order by Event, and look for the plugin.fixedpre.tpl plugin. Are there any other plugins that also monitor for the OnLoadWebDocument event? If not, you are done.
If there are any others, then use your mouse pointer to slide the plugin.fixedpre.tpl plugin so it is the highest in the list, and do a Save. This will ensure that this plugin gets to parse your document, and do any needed quoting of characters, before any other plugin runs. This will ensure that no other plugin traps any special characters until after all needed quoting has been done by plugin.fixedpre.tpl.
Use the New “<fixedpre>” Tag
Now you can use the new “<fixedpre>” tag just like any html tag.
Here is an example of how to use it. In your html document, you can say something like this:
<p>Let's now discuss the <fixedpre>[!Wayfinder!]</fixedpre> string that we used earlier.
This causes a dynamically-generated menu to appear.</p>
The output will look something like this:
Let’s now discuss the [!Wayfinder!] string that we used earlier.
This causes a dynamically-generated menu to appear.
You can also combine <fixedpre> with <pre> as needed. For example, you can write this in your html document:
<pre><fixedpre>
[!Wayfinder?startId=`0`
&level=`2`
&hereTpl=`hereTpl`!]</fixedpre></pre>
The output will look like this:
[!Wayfinder?startId=`0`
&level=`2`
&hereTpl=`hereTpl`!]
If your text happens to discuss the <fixedpre> tag itself, just insert an exclamation mark after the opening angle bracket, like this:
These are <!fixedpre> ... <!/fixedpre> tags.
The exclamation mark will automatically get stripped before the web page goes to the user, so the above sentence will appear as:
These are <fixedpre> ... </fixedpre> tags.
If you use multiple exclamation marks in a <fixedpre> tag, only one will be stripped. So, to discuss a <!fixedpre> tag in text that is already enclosed within <fixedpre> tags, just write it as <!!fixedpre>, and so on, This lets you discuss the use of exclamation marks in <fixedpre> tags, just like on this web page.
Rahul
P.S. I began by entering a more brief posting, but after some editing decide to just reproduce my entire web page here, for completeness. You can see this also at <
http://rahul.rahul.net/modx-hints/fixedpre-tag.html>.
