A Mere Formality

By now you'll be feeling like the purchaser of a new low fat grilling appliance. At first you're excited. "The potential! I could grill anything!!". After you've grilled the entire contents of the fridge, including the butter, the novelty begins to wear off. "Maybe I don't want to grill today. Let's call out for Chinese Food."

Well my friend we're here to breath new life into that XSLT grilling machine.

From the point of view of our browser application project, you'll have noticed that the last section was a bit of a con. Sure, we learnt how to apply an XSLT. But basically the browser application was no different to the first, we just put some bells and whistles on the same data. In this section we're going to move up a gear and make it interactive.

The results coming from the mls URA are much richer than just the logical filesystem tree we have already seen. For instance, each resource is associated with a module. It would be great to be able to filter the tree to see each module's resources. Stand back citizen, this calls for Form Processing Man ...

Try this application here

Easy Tiger

Don't worry you didn't miss anything. At first it might look complex but it's actually just a sequence of simple operations. All we've done is introduce a second transform to filter the modules. We've also added some form processing. Let's take it a step at a time.

It's just good Form, old boy

First let's look at the form. Below is the XSLT fragment which is used to generate the form. You can see it as the second element of the /html/body in transform2.xsl stylesheet here.

Now this is not as complex as it looks. It generates an XHTML <form> from the result of the mls instruction. You might remember that mls produces a document with a root mls and several dir, res elements. No? If not look here.

You've seen the form in action so you know that all we're doing here is creating an option for each module. There's also one special option '*' to select all modules, this appears as the first item in the select block. Don't worry about why we're adding position data as well as the module name to the value of each option; this is just a trick to save some work later on.

There's another thing that you'll have noticed. We're looking at an xsl:variable $modselected and testing the value to see if we need to set the selected attribute on the option. This just makes the app nicer to use since you don't have to keep reselecting the option each time you get back the result.

Finally we're using the $modules parameter to set a form entry for each module this uses the module's URI (identity/uri). We'll discuss how the $modules variable is produced and provided to the transform later.

That's the form dealt with, though it actually had nothing to do with DPML, but we needed to understand it's structure in order to look at how the app works. To some it'll have been a patronizing stating of the XSLT obvious, to others it'll have been a baffling immersion into XSLT and XHTML. Hopefully you were a Goldilocks who found it just right.

Nurse. Scalpel. We're Dissecting the App

For the squeamish it's not going to be too bad. The blood's been drained and there's a strong extractor fan taking the bad smell away.

Starting with the first instruction:

This uses the familiar copy accessor to create and put something into the variable var:myParam. What's new is the operand references the URI this:param. Each idoc can be passed a parameter document before it is executed. The parameter document is referenced by this:param. this being the current execution context and param being the standard identifier for the parameter document. It's really just like a variable that's been created externally and is available throughought the scope of the executing idoc.

Let's return to the form for a moment. You can see that the method and action attributes of the form tell it to post the data to app7.idoc. Which by a bizarre coincidence, is the idoc we're dissecting! I can hear you saying "So you wouldn't be mentioning this unless there's a connection with this:param. Get on with it!".

The HTTP transport we are using in the default configuration takes HTTP POST (and GET) data and passes it to the DPML runtime. When the DPML runtime uses this parameter resource, by referencing it using this:param, it is automagically transmuted by the HTTP module into an XML document. The document has a root element nvp, standing for name-value pairs, and child elements named after each of the parameterized GET or POST data fields. Which in the case of our form is mod and submit, though we don't care about submit since it's just the button to initiate the posting of the form. So what does this:param actually contain if we select '*' to view all modules?

As you can see, in our application the param document contains an element mod which holds the value we selected from the drop down selection form called mod. There's nothing special about the param document from the HTTP transport. It's just an xml resource like all the others we've encountered so far. It just happens to contain an XML representation of the parameterized HTTP POST/GET data. We will discover later that we can send an arbitrary param document to an idoc and it is always accessed via the this:param URI.

The Exception that proves the rule

Well we now know that we can get hold of the data POSTed from the form. Let's move on to the next block.

What happens if we invoke our browser application for the first time? No POST data, therefore no this:param, therefore trouble! If there's no param document the first instruction will throw an exception. Fortunately DPML has a straightforward exception handling model.

Exceptions are handled by an <exception> block, which is really just another instruction sequence like <seq>. Inside an exception block we find more <instr> instructions! When an exception is thrown it will seek to be handled by the first <exception> block in the current code block, in this case that's the outer <seq> block. If the code block does not contain an exception block it will cascade upwards to any outer instruction blocks until it is handled. If it never gets handled it will finally get output as the result of the idoc's execution. An exception is an xml document, just like every other resource in the system, and so can be processed. In the current case we catch the exception, and ignore it as there can be only one possible cause. We use the exception to indicate that we need to copy a default param document into var:myParam.

Here's that first instruction in an idoc of it's own. We're not sending any POSTed data so this:Param does not exist. An exception will be thrown and caught in the exception block. This exception block has an instruction that formats the exception into XHTML. An exception is always referenced by this:exception. Try it here

Since an <exception> block is just another instruction block they can be nested. So one exception block can contain other exception blocks ad infinitum. As we will see later exception processing is an extremely valuable aspect of DPML.

Lovely Rita Parameter Maid

Returning to the main part of the application. We are now sure that we have a valid document contained in var:myParam. The fourth instruction is our old favourite the mls operation we've seen throughout however here it is using a dynamically generated <mls> configuration which is built in instruction three using an xslt operation on var:myParam. In this case the mls config adds a module URI which directs mls to return the listing for only that module. So the operation of mls is controlled by the input we receive from the form.

You can examine the mlsbuilder.xsl stylesheet here.

The home stretch

We're now more than halfway through! It's all downhill from here, as Sir Edmund Hilary was fond of saying. In fact we're going to cover the last instructions in one go. Hold on it might go quite quickly...

The third from last instruction is another request for system introspection data. It calls the systemcomponent accessor with a param netkernel:module. This generates a document with all the modules known to the system. The systemcomponent can be used to get documents with the current state of many aspects of the kernel.

In the penultimate instruction we do all the real work. The list is styled by the XSL transform transform2.xsl. The module list var:modules is passed into the transform as a parameter in <param> - these values are used to set the entries in the drop-down module selection form element. In addition another parameter <selected> with the var:myParam is passed to the style sheet. The XSLT uses the selected parameter to create the $modselected variable that chooses the selected module.

The arguments <param> and <selected> are arbitrarily named arguments which will be passed to the xslt accessor. In syntax and types they are exactly the same as operand and operator, and take a URI or literal.

In fact any element name, except "type" and "target" which are reserved, inside an <instr> element may contain a URI or a literal. So far we have used <operand> , <operator> and <param>, though these are only a naming convention adopted by many accessors for their arguments.

Don't confuse <param> with this:param though they are related. Here <param> passes an additional resource to the accessor. this:param is a resource this idoc received before it executed. As we'll soon see we can use <param> to set this:param on a sub-idoc.

I've probably succeeded in confusing you further. Unfortunately we have to take things a step at time. All will become clear in the next section.

It is sufficient to know that the value referenced in param here is passed into the XSLT as a top level xsl:param parameter in the stylesheet.

Finally the last instruction casts this:response to HTML. We don't output HTML from the var:transfrom XSLT since the table is complex and using XHTML produces a result which all browsers can render.

Breathe. Breathe. And, relax

That's it. The whole application boils down to seven instructions. The explanation may have gone quickly in places but this application is the first we've shown with interaction and dynamic data.

Summary

In this section we built a real app and covered a lot of new stuff.

We learned that an idoc can receive a parameter document and that this is accessed through the this:param URI. We discovered that an <instr> can have one or more <param> elements (or any other name we choose) which provides an additional resource to a URA. Also we covered exception handling and showed a simple example of it's use and how an exception is accessed through the this:exception URI.

On top of all that we found out that, in an HTTP application, POST and GET data is available to the idoc within the param document.

In the next section we'll do all this again! You didn't think this was a good way to write an application did you ;-)