How to add code in a MODX Articles blog post

Keeping a MODX blog

I've been wanting to keep a blog of my work with MODX for a while for a few reasons:

1. To chart my progress with the CMS
2. So that I can remember how to do things!
3. As a way to give something back to the MODX community and help them too, if possible

The problem

So, after setting up Articles as my blogging package of choice, the first challenge is: How do I display legible code?

Suppose I want to post a useful PHP snippet? If I just post it in some <pre></pre> tags then I get something like this:

<strong><!--?php 
$text = "The quick brown fox jumped over the lazy dog.";
$newtext = wordwrap($text, 20, "<br ?-->\n");
echo $newtext;
?></strong>

Hmmm, not very useful, but believe me there is some serviceable code in there! (edit: that did initially not read well, but it looks perfect now, like the "improved" version below. This is probably due to an update of the editor I use called Redactor from modmore which is probably sorting the code out to display well)

One of the problems is that we need to change any characters in the code that are special characters in HTML to HTML entities so that they can be displayed in an HTML document rather than being interpreted.

The solution

So I wrote a little utility to convert my code to HTML entities

Here's my code again after having any special characters converted to HTML entities:

<strong>
<?php
$text = "The quick brown fox jumped over the lazy dog.";
$newtext = wordwrap($text, 20, "<br />\n");
echo $newtext;
?>
</strong>

Ah ha, now that's looking better, and it's perfectly readable. But suppose it was a longer piece of code, wouldn't some syntax highlighting and indentation help it's readability?

Syntax highlighting

The answer is yes, and that's why I use Alex Gorbatchev's SyntaxHighlighter

So, this is pretty straight forward to use you have to include a core javascript file on your blog page shCore.js and the javascript 'brush' files for the types of code you are going to be displaying eg: shBrushPhp.js and shBrushCss.js etc.

You then need to give your <pre></pre> tags the appropriate class for the code you are displaying eg: <pre class="brush:php"> ...code... </pre>

So lets see what our code looks like now:

<?php
$text = "The quick brown fox jumped over the lazy dog.";
$newtext = wordwrap($text, 20, "<br />\n");
echo $newtext;
?>
	

Now that's looking more like it!

What about MODX tags?

But there's one last issue: what if I want to include some MODX tags [ [ ] ] in an example? MODX will see them as a tag and try and substitute a chunk or snippet or something for them, and if it can't find the mentioned tag item it will simply remove it from the post.

I tried using my html entity utility to convert [ and ] to html entities also but tinyMCE didn't want to play, it would convert them back! (I think it did work if I pasted the entities in HTML Source Editor and saved it, and never opened it again but I think it's at the point of reopening the HTML Source Editor that they get converted back to regular square brackets) So the only solution I could come up with was to leave spaces between them like so [ [...] ] , MODX ignores them if there is a space. So you can then write your snippet like this:

<div class="slide">
	<img src="[ [++site_url ] ][ [ +image ] ]" alt="[ [+description] ]"  [ [+imageAttribs ] ] >
	[ [ +content:notempty=`
	<div class="slide_content">
		[ [ +content ] ]
	</div>
	`] ]
</div>
	

Not Brilliant but it will have to do for now.

Hope that helps.

Mike