Introduction to custom controls

Encapsulation

There are a number of reasons why you might want to create a custom control, but perhaps the most common is in order to encapsulate some functionality, so that the main document remains clean and free of distracting code. A typical example of this would be where the control contains processing that we want to hide because it is irrelevant to the 'logic' of our main form. For example, we might want to show a nice looking clock on a page, but we really don't want to see a lot of SVG or XAML mark-up, and we certainly don't care about the calculations that are involved in working out the angle of rotation of the clock hands, or the amount of skew needed to get LED-style numbers. To use a clock in a form, all we really want to see is simple mark-up, like this:

<xf:output ref="clock" appearance="fp:LED" />

or this:

<xf:output ref="clock" appearance="fp:analogue-clock" />

In each of these examples, the value of the control is coming from the instance data, but the rendering is different for each control, based on the setting of @appearance. Our LED clock widget might look like this:

whilst our analogue clock widget might look like this:

Inheritance

The custom control support in formsPlayer also allows us to create a hierarchy of objects, with one widget being defined as an extension of another. To illustrate how this also helps encapsulation, imagine that we have created a custom control that binds to an XForms output and shows an image; a typical use of this control might be to show the BBC's JamCam for the Elephant and Castle, in London:

<xf:output
  value="'http://www.bbc.co.uk/london/travel/jamcams/cctv/543603.jpg'"
  mediatype="image/jpeg"
/>

Now, imagine that we also want to show a map of some geographical location; there are a number of servers available that will give you an image of a map that is centred at the location you specify, so it would seem pretty simple to use the image custom control that we just saw, as follows:

<xf:output
  value="'http://ssems1.esrin.esa.int/mapServer/mapServer?...'"
  mediatype="image/png"
/>

This retrieves the correct image, but the URL is extremely long, and very difficult to manage. More importantly, as far as our form is concerned the only thing we're really interested in is the location--the longitude and latitude values--rather than which particular server is used.

So instead of using the image custom control directly, we build another custom control that inherits from or extends this image custom control. This new control works out what the image URL should be, based on the longitude and latitude fed in, but hides that URL from our main form:

<xf:output value="'52;4'" appearance="geoposition" />

This means that were we ever to need to change to a new mapping server at some point, this would be easily done in the custom control's definition.

Our control might look like this:

Accessibility

One final advantage of using the custom control approach is that, since the 'value' of this new control is 52;4 rather than some long, meaningless URL, it makes the control much more accessible; a voice system that does not support visual maps would still be able to read aloud the values 52 and 4 to a user.

In the next sections we'll look at the custom control architecture in more detail, and walk through how to create some controls.