function myform_some_form($form_state) {
  $form['text'] = array(
    ’#type’ => ‘textfield’,
    ’#title’ => t(’Your submission’),
    ’#default_value’ => t(’Enter some text’),
    ’#description’ => t(’Please use this field to submit some text’),
    ’#required’ => TRUE,
  );
  return $form;
}

creats a form with:

• A single textfield element
• Accessible XHTML with form labels
• Potentially localized labels, translated into any number of languages
• A bit of similarly localized help text below the element
• Validation of the form submission, with the field content marked as required

That’s a separate item of form functionality for each array key. And as long as you use Form API, Drupal handles validation and input sanitization for you, thus massively reducing the risk of attack by SQL injection or XSS.

Bookmarkable search URLs with POSTed search terms

But there’s a catch. To encourage best practice in terms of form submission and friendly URLs, Form API defaults to HTTP POST. If site searching used Form API (which it does) then what impact would that have? Successful searches could never be bookmarked, because the URL on its own doesn’t capture the POST submission.

The search module tackles this by adding an extra twist to Form API. At the end of submission processing are the following two actions:

• Call either the function named in $form['#submit'] or $ID_submit, where $ID is typically the name of the original form creation function (”myform_some_form” above)
• Finally, either return to the original action page of the form, or redirect to any URL specified in $form['redirect']

The search module therefore uses a function called search_form_submit to grab the POSTed search terms, and redirect the user to search/$SEARCH_TYPE/$SEARCH_TERMS. $SEARCH_TYPE is “node” for Drupal’s out-of-box textual node searching, but if you install some other search module e.g. Apache Solr then it’ll be e.g. “apachesolr_search” instead. Result: bookmarkable search URLs.

Writing your own module to handle searches

This has important ramifications if you’re trying to piggyback off core search somehow: if, say, you’re still using core search or a third-party module for the actual result-finding, but then you want a page other than core search to display the results.

If you want the main site search form to redirect to your own pages, for example, then you have to (a) add your own $form['#submit'] function to the stack and then (b) use that to change the core search’s $form['redirect']:

// Implementation of hook_form_alter(), adding an extra submit callback to
// search forms identified by their existing callback
function mysearch_form_alter(&$form, $form_state, $form_id) {
  $submits = array(
    ’box’ => ’search_box_form_submit’,
    ’form’ => ’search_form_submit’,
  );
  if (is_array($form['#submit'])) {
    $which = array_intersect($submits, $form['#submit']);
    $which && ($form['#submit'][] = ‘mysearch_form_mysubmit’);
  }
}
// Submit callback, which changes the redirect using a regular-expression replace
function mysearch_form_mysubmit(&$form, $form_state) {
  $form_state['redirect'] = preg_replace(’/^search\/[^\/]+/’, ’search/my_special_search’,
    $form_state['redirect']);
}

Now you’ve got all your site search forms redirecting to a bookmarkable page at search/my_special_search/$SEARCH_TERMS. All you have to do now is write a menu callback for that page: from here on in you’re on your own for now.

You can read a breakdown of the worst bits on The Web Standards Project, but here’s the feedback I just emailed webguidelines@coi.gsi.gov.uk:

Hi,

I appreciate the COI’s desire to provide roadmaps for cross-browser support, but I’m otherwise dismayed at the recent publication’s back-to-front emphasis regarding browser standards support. It feels like the publication has been put together by people who are remote from the current thinking on web standards and how best to both promote them and take advantage of them.

As a web developer I’ve had a reasonable amount of experience in developing sites cross-browser, and generally the quickest and cheapest site creation (and the least patronising or inconveniencing to the eventual end users) is effected by developing first on the most standards-compliant browser available, regardless of its user base. Then, once the site is stable and well-built according to the standards (which are there for reasons other than semantic fussiness), one can use *freely* *available* frameworks to compensate for browsers which do not follow the standards (which may be more popular). It involves more effort at the start in exchange for a much smoother site construction later on.

Let me repeat that: building sites according to web standards, then accommodating bad browser behaviour, is CHEAPER, QUICKER and MORE ROBUST than what you implicitly propose i.e. building with bad-but-popular browsers in mind, and then looking at shoe-horning in browser-specific fixes for the others.

If you inconvenience the users of good browsers because there aren’t many of them, you are taking us back to the bad old days of 1990s browsing. I haven’t seen the phrase “We advise you to upgrade your browser version” (which I take verbatim from p4 of your report) on any site I respect and trust for almost ten years. Ask any decent web developer: it’s no longer necessary, and frankly it reveals far more about the mindset of the site designers than about the state of web technology.

Like the proposal’s guidelines, its consultation is happening the wrong way round, and highlights a top-down mentality behind composing such documents. Sharp, savvy developers recruited from any of the vibrant UK web conferences—dConstruct, OpenTech, Barcamps—would have been glad to have helped the COI out before this fundamental missing of the point was published, were they to have been asked. It would certainly have saved both COI and the web community at large a lot of heat, friction and wasted effort.

Yours faithfully,

J-P Stacey

PS: I was originally going to send this via your website’s feedback form. After having read your proposals for building good sites I decided to email it instead, just in case.

You’ve got a month to comment yourself, if you’re a UK or European developer. Feel free to use the above template, only I’d recommend changing the name at the bottom.

Web architects must understand that resources are just consistent mappings from an identifier to some set of views on server-side state. If one view doesn’t suit your needs, then feel free to create a different resource that provides a better view (for any definition of “better”). These views need not have anything to do with how the information is stored on the server, or even what kind of state it ultimately reflects. It just needs to be understandable (and actionable) by the recipient.

— Roy Fielding on creating new resources for REST architectures.

But what makes it all far, far worse is that IE6 and IE7 can sometimes produce error messages which, as is usual for those browsers, contain no useful information whatsoever.

Here’s a recent example:

Line: 64432871
Char: 2
Error: Expected identifier, string or number

See that impossibly high line number? That’s a result of the parser being struck soundly on the head by the syntax error, and consequently dribbling its way past the end of the Javascript file. IE’s incomprehensible “English” error message conspires with circumstance to make the whole report of no help at all.

Something like JSLint, on the other hand, is of tremendous help, and we’ll be running as much Javascript through it as possible in future. JSLint is just as unforgiving, but as it’s reliably unforgiving and incredibly communicative with it then that’s a bonus rather than a detriment.

It’s sometimes a little too strict to be useful, complaining about implicit global variables (even when that variable is called window). My suggestion is to ignore those reports, though; but watch those commas!

Drupal.org have produced a Licensing FAQ to explain some of the subtler aspects of licensing under the GPL. The questions themselves are Drupal-oriented, but the FAQ itself has been prepared by the SFLC, an independent body, so the answers are broader than that.

I’ve noticed from the slightly confused sidelines that Drupalers have been niggling away at these issues for ages. Their heated exchanges and occasional quarrels are the fuel that has kept this wagon moving, and they’ve finally rolled it into town with a GPL-in-practice primer that’s worth reading, whatever you’re working on, and especially if you’re integrating with web services or third-party libraries. Well done to all involved.

I’m realy looking forward to it, especially in the light of one of our clients wanting to implement the OAI-PMH protocol in the next month or two. I’ll have to toss a coin, though, to see if I dare stay in London late enough to miss the last bus out from Oxford to Eynsham….

As I spend the scraps and offcuts of January and February evenings ripping and filing my 2007’s CDs—some of which I won’t listen to very often once they’re fossilized in the collection—I’m aware of a tremendous weight of madeness and invested time and energy on the part of the manufacturers, and of a sort of casual luxuriating in my first-world lifestyle on my own part. You prepare a playlist before me in the presence of my enemies. You anoint my tapeheads with crude oil; my CD tray overflows. So in 2008 I hope to buy as few CDs as possible (none is the target) while also avoiding DRM-crippled music and staying legal.

To this end I’ve been seeking free and semi-free online music—free as in beer, semi-free as in of limited choice—since the new year. So far, outside of bittorrenting (which is obviously of variable legality, depending on what you’re downloading), I’m having some success with Last.fm. Until recently they offered a sort of customized “radio station”, where your input into the of the next track was limited to an intelligent deduction by Last.fm based on what you told it you enjoyed in the past. Now, alongside this potluck service, they’ve just started offering three free streamings of any explicitly chosen track before requiring you to buy the track from a commercial partner.

I’ve yet to try the former service (I think you might have to subscribe to be on the beta wagon: I’ll look into that later), but the latter has so far provided our house with unlimited, free access to a radio station for our very own target market. While such slightly sinister profiling might make it harder for me to discover truly new music, it does at least permit me to expand the boundaries of my comfort zone slowly, and cast a critical eye over my friends’ music preferences, while at the same time giving artists their due and most importantly avoiding physical recordings unless I really want them.

Most commercial support for Linux distributions still consists of monolithic installations, wrapped up with checksums to prevent you tampering with them, and installing themselves on your computer in whatever location and potentially harmful fashion they fancy. Until upgrading to Gutsy this was largely my experience (painfully and often repeated) with such packages as nVidia and wireless drivers, and interesting software that barely gave a second thought to existing Feisty users.

After a spot of Googling I was expecting to have to go through the same palaver with Last.fm’s client, and crossed my fingers that nothing would go horribly wrong. But I needn’t have worried: the Linux client for Last.fm is

1. free of cost, as in beer
2. free of restrictions, as in open source
3. free of hard work, as in a no-sweat installation utilizing the Debian packages and apt package management that’s core to Ubuntu

To install it on Gutsy, you first want to add the GPG key for the repository for security reasons. At a command line, type:

wget -q http://apt.last.fm/last.fm.repo.gpg -O- | sudo apt-key add -

You’ll be asked by sudo for your password. Then, open Synaptic Package Manager (under “System > Administration” in the GNOME menus); then, via “Settings > Repositories”, add the following new third-party repository:

deb http://apt.last.fm/ debian stable

You can then search for the Last.fm widget’s package in the manager (hint: it’s called lastfm) and install it. When you first run it after installation it’ll ask for your Last.fm account, so best have one of those in advance. And that’s it: you’ve now got Last.fm’s widget on your Ubuntu PC.

All of the above is explained briefly on the very URL of the apt repository. Not only that, but they have a free bonus photo of a very cute bunny in case all the apt stuff bores you rigid. Like a TV licence for the Flash version of the BBC iPlayer, all of this is practically worth a subscription alone. As I type, my mouse sits over the very location of the link to do so in a separate tab. I just need to know first: how many more rabbits do I get when I join?

Now I’d like to start exploiting that behaviour, and I’m going to use the hCard microformat to illuminate its use. Briefly: a microformat is a set of agreed HTML classes used to invisibly encode structured semantic data in HTML; hCard is the implementation in HTML of the vCard specification for “virtual business card” files, using microformat classes. If you mark up people’s addresses using the hCard classes, then it’s possible to automate the conversion from hCard-enabled HTML to vCards, meaning you can click on buttons on webpages and have a vCard served up to you containing the contact information present in the webpage, verbatim, in a format you can put into your address book of choice.

One of the most-used conversion methods—Brian Suda’s X2V, a web service which converts XHTML with hCard markup into vCards and then presents them to the site visitor—uses XSL. In fact, that was what got me thinking about this whole system. Brian’s work is neat, although his own server takes a hit every time someone uses the web service (and it only works on XHTML, not non-XML HTML. What if, I thought, we could get the browser to do it instead; if we could implement template-like functional Javascript?

Anyway, below we find a couple of hCards, culled more or less directly from the Microformats examples page.

Frank Dawson

Lotus Development Corporation

work address (mail and packages):

6544 Battleford Drive

Raleigh NC 27613-3502

U.S.A.

+1-919-676-9515 (w, vm)

+1-919-676-9564 (wf)

Frank_Dawson@Lotus.com alternative email fdawson@earthlink.net

Tim Howes

Netscape Communications Corp.

work address:

501 E. Middlefield Rd.

Mountain View, CA 94043

U.S.A.

+1-415-937-3419 (w, vm)

+1-415-528-4164 (wf)

They look like slightly unstructured HTML, don’t they? That’s sort of the point. But hidden in the HTML are vCard classes. How do we tease them out with Javascript?

Well, there’s a question to be asked before that, I suppose, which is: why would we follow your method, and not someone else’s? What’s so good about functional Javascript? Good question. Well, if every hCard looked like the above, then you could write some completely procedural Javascript to turn it into a vCard. No problem.

But what if the order of the content was changed? The hCard—indeed, microformats in general—has quite a malleable structure, with some classes sometimes appearing on elements inside other elements, and sometimes not. What if there were more telephone numbers and email addresses, and what if they turned up in all sorts of different orders? These are just HTML classes, after all. With procedural Javascript you could start writing switch/case statements to cover every opportunity, and essentially come up with one big unavoidably recursive function. It’ll be hard to structure, hard to maintain and completely unmodular. A document-driven method of extracting the vCard, on the other hand, doesn’t need to worry about all the various different combinations of nested elements: it would just keep one eye on context and process whatever it found. Also, the development cycle could be faster, because templates could be overridden without breaking existing behaviour: just use the template() command to override existing behaviour.

Let’s instead assume you’re following my every word. For this next bit, you’ll need Firefox and Firebug, or to stuff all these instructions into a single file. Otherwise, you’ll have to take my word for it. Firstly, I’ve included jQuery on every page of my blog, so if you’ve got the ‘bug then you don’t have to resort to my insert-JS bookmarklet to squirt it in.

So: first, create the treewalker() and template() functions from part 2. Next, assign treewalker() to body and everything below it:

template("body, body *", treewalker);
template("body, body *", treewalker, "default");

You could restrict this assignment to everything within the .vcard elements, by giving the relevant CSS specifier instead, if there were a lot of content outside the hCards. It would speed up the initial setup phase, but it does complicate the demonstration so I’ve left that refinement out.

Remember we ran the treewalking before? Do that now:

var result = document.body.treewalk();

All being well, you should get a blank string back. Now it’s time to start adding some alternative rules with template(). Try this:

template(".vcard", function() { return "BEGIN:VCARDn" + this.default() + "END:VCARDn" });

Now run the treewalker again. Oh, each hCard has just given you a vCard! An… empty vCard. Isn’t that great? Um. We can add to that, though:

template(".vcard .fn", function() { return "FN:" + $(this).text() + "n" + this.default(); });
template(".vcard .org", function() { return "ORG:" + $(this).text() + "n" + this.default(); });

Now document.body.treewalk() doesn’t just return a vCard for every hCard, but it knows about names and organisations. Also, because we keep including the call to this.default() in our overrides, we still treewalk into any element inside the FN or ORG containers.

What about emails? Well, in the source we can spot an a.email element up there, so let’s give the following a whirl:

template(".vcard .email", function() { return "EMAIL;TYPE=internet:" + this.href.replace(/mailto:/, "") + "n" + this.default(); });

Try running document.body.treewalk() again. Hm. I don’t know about you, but I’m getting an error from that. Ah, wait: sometimes we have span.email rather than a.email. Spans don’t have @href attributes. Well, we could change the above rule and immediately reapply it using template() with no ill effects. But instead let’s keep it in place, and use a more specific specifier to override it just on spans:

template(".vcard span.email", function() { return "EMAIL;TYPE=internet:" + $(this).find(".value").text() + "n" + this.default(); });

Re-run the treewalker. It now finds all email hCard elements and brings them out into the vCards!

I’ll leave you with one more demonstration, for the slightly more complex TELephone field. As you can see above, there are lots of “types” for this field (Work, VoiceMail, etc.) and these sit in child elements of the telephone element. So we need to assign overrides to both the telephone element and its children.

Here’s a rule for the TELephone container:

template(".vcard .tel", function() {
  var t = "TEL";
  // Run defaults to get types where appropriate
  t += this.default().replace(/,/, ";") + ":";
  // See if we’ve got a “value” child
  var val = $(this).find(".value");
  return t + (val.length ? val.text() : $(this).text()) + "n";
});

This method is a bit more complex because we need default() to just get the .type children, and then we reach down to get. Maybe if we could give specifier argument to the default behaviour e.g. default('.type') first, then default('.value')… But that’s a project for another day, I think. Right now, let’s assign a rule to the types children and then run our treewalker:

template(".vcard .tel .type", function() {
  var jQ = $(this);
  return "," + (jQ.attr("title") ? jQ.attr("title") : jQ.text());
});

Result? You should now have Javascript which can produce vCards (currently without geographical address support, as I don’t have time and you might get bored) from the hCard microformat. It’s easy to extend, easy to maintain and, in my opinion, fairly concise. Here’s the whole shebang, less the two framework functions from my previous posts:

// Start with body
template("body, body *", treewalker);
template("body, body *", treewalker, "default");
// vCard wrapper
template(".vcard", function() { return "BEGIN:VCARDn" + this.default() + "END:VCARDn" });
// FN and ORG
template(".vcard .fn", function() { return "FN:" + $(this).text() + "n" + this.default(); });
template(".vcard .org", function() { return "ORG:" + $(this).text() + "n" + this.default(); });
// Email - A and SPAN tags
template(".vcard .email", function() { return "EMAIL;TYPE=internet:" + this.href.replace(/mailto:/, "") + "n" + this.default(); });
template(".vcard span.email", function() { return "EMAIL;TYPE=internet:" + $(this).find(".value").text() + "n" + this.default(); });
// TEL
template(".vcard .tel", function() {
  var t = "TEL";
  // Run defaults to get types where appropriate
  t += this.default().replace(/,/, ";") + ":";
  // See if we’ve got a “value” child
  var val = $(this).find(".value");
  return t + (val.length ? val.text() : $(this).text()) + "n";
});
// TEL types
template(".vcard .tel .type", function() {
  var jQ = $(this);
  return "," + (jQ.attr("title") ? jQ.attr("title") : jQ.text());
});

And that’s it. I hope the approach comes in useful. By next year, you’ll have hCard-enabled pages, with vCard conversion in the browser. Happy Christmas!

So: functional Javascript. Not just functional, but with all the automation of XSL transformations and CSS applications, where you can set it all running and it’ll produce something and hopefully throw no errors. Let’s start with jQuery.

jQuery provides Javascript with a functional framework. Here’s the equivalent of the examples in XSL and CSS, supported by the inclusion of jquery.js:

jQuery("p.intro").each(
  function() { this.style.color = green; }
);

I hope the similarities are clear, and not too strained. Now all three languages do implicit looping over sets of element nodes, and no longer require checks for missing elements; that’s evidence that it’s starting to behave functionally. There’s still a few pieces missing, though. We’d like to be able to iterate over the tree with a set of default rules, and also replace the default rules with our own where necessary.

What would the default rule look like? Well, we can pass around all sorts of objects—this being an object-oriented language—but for now let’s play it safe and follow XSL’s lead, and have each node return the concatenated text returned by all its child nodes. That means that, by default, the whole HTML document would return an empty string. It might be nice to return an array of equivalent objects, or even some transformed tree, but let’s remain old-skool. Anyway, we can always serialize any HTML elements we want to include as text, and then stick them back into the DOM later. There’s probably a way of doing some of these tasks with core jQuery, but as we’re also passing result data around as well as input data, I’m going to step outside the framework (its extension model typically takes a jQuery object in, and returns a modified jQuery object, which isn’t quite what we’re after).

Here’s a default rule: it says “call the default rule (i.e. me) on all my children”. We’ll call this rule treewalker, because that’s what it does. We’ll also assume that we’re going to assign this function as the .treewalk method on each element:

var treewalker = function(i) {
  var t = "";
  $(this).children().each(function(i) { t += this.treewalk(); } );
  return t;
}

And here’s a way of assigning rules to elements. It’ll assign the rule as the .treewalk method unless we specify otherwise.

var template = function(specifier, fn, property) {
  if (typeof property == "undefined") property = "treewalk";
  $(specifier).each(function(i) { this[property] = fn; });
}

It looks a bit clunky, because falling back on the default property means we have to have an if-exists check. That’s to be avoided where possible in functional programming, but bear in mind that we’re still looking under the bonnet (or “hood” if you like), not at the actual functional code. We’ll get to the fully-functional bit shortly.

We’ve got one last bit and we’re done. We want to put the default rule on every element within a certain scope: we’ll assume for now that the whole HTML document body is to be treated; that might be computationally heavy for big documents, but we could change that. We’ve already defined a way of putting rules onto things, so let’s use that to put the treewalker function in as both .treewalk and .default. That way, we have a copy of the method hanging around, that we can fall back on if we overwrite it:

template("body, body *", treewalker);
template("body, body *", treewalker, "default");

That’s it. We’re now ready to pretend our Javascript is XSL. Here’s how we run it:

var result = document.body.treewalk();

Try it. “But that’s just an empty string!” you might, if you were feeling ungrateful, complain. Are you never satisfied? More on this later.

p.intro { color: green; }

And here’s a sort-of XSL equivalent:

<xsl:template match="p[@class='intro']">
  <p color="green"><xsl:apply-templates /></p>
</xsl:template>

They both take place in the context of some generic processor, which rattles through the document executing default rules (XSL: strip out all but text nodes; CSS: apply the plain styles of your browser) unless your program—a list of disconnected rules, really—tells it differently. The combination of (XSL/CSS)+(X)HTML+defaults is thus turned into an explicit script for the browser to run.

So far, so reasonable. But what about the third technology, Javascript? Well, plain Javascript is an object-oriented procedural language. It orders the browser around for a bit, and then when you want to do something to the current page, Javascript manipulates the (X)HTML tree by grasping hold of it with both hands and giving it a tug, using DOM methods like .getElementById(id) and attributes like .parentNode. This procedural approach expects the tree to have a certain structure, or at the very least has to keep checking if the structure has changed and coping with that. This means that the programmer generally has to construct a lot of loops over, say, child elements, and also check for existence a lot. There’s a slight anomaly, in that you could think of the event-driven aspect of Javascript as being functional—it turns the user’s input through clicks, mouse movement and keypresses into browser behaviour, remaining otherwise dormant—but by and large Javascript’s meat is procedural.

There’s two routes you can take at this point. You can either say that, because Javascript is meant to be object-oriented, then the best way to work with it is to augment its functionality and simplify object construction, but ultimately leave it as that: if it weren’t functional, then it wouldn’t be Javascript. Or you can say that, given the advantages that XSL and CSS gain by being functional—a kind of “safety”, some scaleability, and document-driven processing—Javascript might want to have a piece of that too, while sacrificing some of its object orientation.

The first route is entirely laudable, because some problems are object-shaped and some are function-shaped. But, in the spirit of adventure, let’s investigate the second route for a while: pack some sandwiches and get some stout shoes on, and I’ll meet you in my next blog post.