How to display code fragments in web pages

080219

Since in this blog I'll be writing about JavaScript, XHTML, CSS and other languages, I was wondering which would be the best way to display code fragments in a web page. Obviously each fragment will go inside a CODE element, but there's other things I'd like to implement:

1. When the page is displayed without CSS, I'd like the code fragment to have a decent formatting.
2. I'd like to add a sort of caption to each code block, to add things like "add this to your .css file" (see the code fragments below as an example).

And of course, I'd like to do it with the cleanest possible XHTML. Let's go!

Point 1 is easy to solve: all we need to do is wrap the CODE element inside a PRE element. An alternative would be to use BR elements inside CODE to format the code, but that looks ugly and inconvenient to me. Styling the CODE element to behave as a PRE element is not good, because it will ruin the code layout when viewed without CSS.

Just a note on PRE: in theory we shouldn't use PRE since it doesn't have semantic meaning, but I choose to use it anyway because it will force the browser to keep the code formatting even without CSS. To me this is an acceptable compromise, but I'd be interested to know other people's views on the matter.

Point 2 is debatable: should we use a P element inside PRE, just before CODE? Or outside PRE, adding a class to it? Then I had a curious idea: what about using the title attribute in CODE, and use JavaScript to turn it into a visible caption? That sounds reasonable! The XHTML will stay nice and clean, and even without JavaScript the information will be there, as a tooltip. The result is a simple JS function that adds a DIV with class="JScodeCaption" just before the PRE element. Also, for easy styling, the class JS is added to the PRE element.

function addCaptionsToCode() {
    var codes = document.getElementsByTagName("code");
    var elTitle, elPre;
    for (var i=0, l=codes.length ; i<l ; i++) {
        title = codes[i].title;
        if (title) {
            // Remove title from CODE
            codes[i].title = "";
            // Prepare caption DIV
            elTitle = document.createElement("div");
            elTitle.innerHTML = title;
            elTitle.className = "JScodeCaption";
            // Add class to PRE
            elPre = codes[i].parentNode;
            elPre.className += " JS";
            // Insert before the PRE
            elPre.parentNode.insertBefore(elTitle, elPre);
        }
    }
}

Btw, if using innerHTML annoys you, feel free to use the appropriate DOM methods, I'm just too lazy... :)

<pre>
<code title="The caption for this block">
... some code here ...
</code>
</pre>

If you'd like to use it in your projects, simply run the addCaptionsToCode function with your method of choice (onload, DOMContentLoaded, at the end of the XHTML), and style the JScodeCaption class in your CSS file. Easy! I'll leave you with a sample CSS to style your code fragments (explaining it would be outside the scope of this post).

pre {
   display: block;
   margin: 2em 0;
   white-space: pre;
   overflow: auto;
   width: 470px;
   line-height: 1.4;
   border: 1px solid #ccc;
   background: #ece9d8;
   padding: 8px;
}

/* JS: adding CODE captions */
pre.JS {
   margin-top: 0;
}
.JScodeCaption {
   margin-top: 2em;
   color: #999;
   font: .9em "Verdana", sans-serif;
   padding-bottom: .2em;
}

Posted in: English, Web, JavaScript
Tags: programming