Christian Heilmann

You are currently browsing the archives for the tutorials category.

Archive for the ‘tutorials’ Category

The Opera Web Standards Curriculum is live!

Tuesday, July 8th, 2008

The last few months Chris Mills from Opera was busy gathering a lot of great web development experts around him (with a lot of pimping by yours truly) to assemble probably the most thorough and up-to-date web standards curriculum on the web: The Opera Web Standard Curriculum

Several dozen articles, all licensed with Creative Commons will be available to cover the tasks of web development: from understanding the principles of the web up to Ajax interaction. During the whole course the main focus is on usability, accessibility and writing maintainable code. We deliberately left out browser hacks and backward facing solutions and build on the ideas of progressive enhancement and unobtrusive JavaScript.

I wished this would’ve been out when I started, it’d have saved me a lot of time learning bad practices and un-learning them (which is always a painful process).

So, read it, use it and teach younglings the way of the standards Jedi: The Opera Web Standard Curriculum

Generating tutorials from source comments with Tutorialbuilder

Tuesday, May 13th, 2008

I am spending far too much time keeping explanation tutorials of scripts in sync with changes in the code. This is why I wrote myself a PHP solution to do the work for me. I’ve found over the years that the best way to explain a script is to :

  • Show an example
  • Show the full source code
  • Show the source code bit by bit followed by explanations what each part does

If you go and check Tutorialbuilder you’ll see that I managed to automate most of this with a PHP script. It does the following for you:

  • It generates the tutorial parts from comments in the script source code.
  • It converts the source code to displayable code (encoding it, adding line numbers, allowing for lines to be highlighted)
  • It creates a downloadable version of the script with a correct file name
  • It creates an executable version of the script without comments to link to with a script element.
  • It can minify the script (remove all whitespace to cut down on file size)

In other words, it turns this source script into a tutorial like this using a template and some CSS (most taken from the YUI).

It is not a replacement for JSDoc but instead catered to be easier to use and explain the functionality of code rather than the syntax of the JS code itself.

Tutorialbuilder is licensed with BSD, so go nuts using it for yourself.

Code tutorials for lazy people with Ajax Code Display

Monday, January 28th, 2008

Currently I am writing a lot of tutorials for an online self-training course about web standards and I ran into the annoyance of having to maintain example code in two places: the code itself and the HTML document with the explanations. Therefore I took jQuery and wrote a small script that automatically turns links to HTML code examples with HTML entities and line numbers. You can define which lines to display, which lines should be highlighted and you can add a live preview in an IFRAME when the link is clicked.

A quick idea: JavaScript version controlling for static HTML documents

Monday, January 14th, 2008

When you write tutorials and you want people to use them wherever they are it is a good idea to offer the HTML documents as a zip for downloading. The benefit to the end user is that they don’t need to be online to look something up (I for example have the HTML 4.01 documents on my machine as HTML documents). The drawback is that the documents could be outdated without the user knowing – even when they are online while watching them.

Now, I pondered a bit about this and wondered if something like this wouldn’t be a solution:

  • You add a version number to the title of each document.
  • You add a remotely hosted versions.js script at the end of each document.
  • This script has a JSON object with the version information of each document and compares the file name and version.
  • If the version is outdated, it generates an error message that gets shown to the user.

You can try it out by downloading the two demo documents un-zip them and open them on a computer that is connected to the internet. The second document linked from the first one should be outdated.

The source of versions.js


(checkversion = function(){
// change as fit
var versions = {
‘documentexample.html’:’1.0’,
‘documentexample2.html’:’2.0’
};
var errorID = ‘versionerror’;
var errorMessage = ‘This document is outdated, please go to the homepage to download the new version!’;

// checking code
var d = document;
// get the version number
var cv = d.title.match(/(version (.*))$/);
// get the file name
var cn = window.location.href.split(‘/’);
cn = cn[cn.length-1].split(‘#’)[0];
// check and create error message if there is a mismatch
if(cv[1] && versions[cn]){
if(versions[cn] !== cv[1]){
if(!d.getElementById(errorID)){
var m = d.createElement(‘div’);
m.id = errorID;
m.appendChild(d.createTextNode(errorMessage));
d.body.insertBefore(m,d.body.firstChild);
}

}
}

}());

You could create both the titles and the JSON object in versions.js on the backend automatically by scanning the titles or from a version control system. What do you think?

Let’s make 2008 the year of embracing the server side with Ajax

Sunday, December 30th, 2007

I am always fascinated by the amount of Ajax tutorials and examples out there that totally ignore the backend part of an Ajax app. A lot of times you’ll find page-long ravings about the 6-7 lines of JavaScript that allow the client to make an HTTP request but when it comes to talking about the proxy script needed to allow for cross-domain requests a lot is glossed over as “you don’t need to know this, just use this script”.

That would not really be an issue if the scripts offered weren’t that bad. Unsanitized URLs are the main attacking point for cross-server-scripting attacks. If you use a PHP_SELF as the action of your forms you shouldn’t be too confused about a lot of mail traffic from your server or text links on your site you didn’t sign off and get money for.

The other thing about Ajax information on the web that amazes me is that people keep complaining about the slowness and problems with converting data from one format to another on the client side. Let us not kid ourselves: even after all the articles, books and podcasts about Ajax we still have no clue whatsoever what a visitor uses to look at our products. We cannot tell for sure what browser is used, if there is assistive technology involved or anything about the specs of the computer the browser runs on. This to me makes the client side the least preferable place to do heavy calculation and conversion.

The server side, on the other hand, is in your control and you know what it can do. Complex regular expressions, XSLT conversion, all of this is much easier to do on the backend – and you know that the text encoding will work to boot. A lot of complexity of Ajax apps is based on bad architecture and design decisions and on relying on the client side to provide necessary functionality.

So if you ask me what the ratio of client-to-server code of a good Ajax app is I’d say 30% client and 70% server. The 70% on the server should be used to provide security, non-JavaScript fallback functionality (yay accessibility) and conversion of data to small, easy-to-digest chunks for the client (think HTML and JSON). The 30% client side code should mainly be used up to enhance the usability of the product and make it easier for your visitors to reach their goals.

So here’s my plan for 2008: whenever I talk Ajax I will try to cover as much backend as frontend. I’ll do this by partnering with other experts as I myself created some terrible PHP in the past. I hope that others will follow that example as Ajax is a wonderful opportunity to bridge the gap between frontend and backend engineering – and we have to talk to each other to create a good app.