Monday, January 28th, 2008

Less maintenance code tutorials with Ajax Code Display

Category: Examples, HTML, JavaScript, jQuery, Unobtrusive JS

One of my main annoyances with writing code tutorials is that you need to maintain code in several locations: the code itself and the examples in the tutorial document. This is not really a problem when you can use a scripting language or print out the tutorials from a CMS, but when you just want people to get an HTML document you’re in trouble. As I am right now writing a lot of articles I didn’t want to waste my time and thought about using Ajax to load the code I am documenting into the HTML on the fly. The result looks something like this:

Screenshot of the Ajax Code Display in action

All you need to do is to add jQuery, the script and a class of “codeexample” to a link in the document you want to display. The script creates a PRE element with the code inside, replaces all the special characters, tabs with spaces and adds line numbers. For example:

  1. <p><a href="ordered.html" class="codeexample">ordered.html</a></p>

If you only want to show certain lines (which you’ll have to do if you want to explain some code step-by-step) you can define the lines as a list including ranges. Say you want to display line 5, 10 and 12 to 21, then you’d add:

  1. <p><a href="ordered.html" class="codeexample lines[5,10,12-21]">ordered.html</a></p>

You can highlight lines of code in the same manner, say you want like 18 to 20 in bold:

  1. <p><a href="ordered.html" class="codeexample lines[5,10,12-21] highlight[18-20]">ordered.html</a></p>

Last but not least you can make the link clickable to show an IFRAME with the rendered output. Clicking the link again will remove the iframe. For this, just add a class called “dodisplay”:

  1. <p><a href="ordered.html" class="codeexample dodisplay highlight[10,12,14-15]">ordered.html (click to show output)</a></p>

The script is creative commons, and hopefully you’ll find some extras to add. Enjoy.

Posted by Chris Heilmann at 11:18 am

4.2 rating from 25 votes


Comments feed TrackBack URI

You forgot to link to the script Chris. ;-)

Comment by deanedwards — January 28, 2008

yay 404s!

Comment by Trevor — January 28, 2008

The problem with this approach is that the contents of the code is not going to be indexed by search engines and that browsers with JavaScript off won’t see it. As what you’re showing is pure static contents, it seems like a problem. The right thing to do here if you can afford it is to include the code dynamically from server code, not from client code.

Comment by Bertrand Le Roy — January 28, 2008

@Bertrand, the whole idea was born out of the need to have it included locally without using a backend script. I totally agree that with an online course you should do that on the backend and probably also do code highlighting/colour coding. However, your argument about not indexing is not true. Without JS you just have a normal link which will be followed by robots and users without JS alike.

Comment by Chris Heilmann — January 28, 2008

Fair enough, Chris.

Comment by Bertrand Le Roy — January 28, 2008

“Fewer” tutorials, not less. For what it’s worth.

Comment by pinchworm — January 28, 2008

Leave a comment

You must be logged in to post a comment.