Deciding on a custom control 'interface'

The first thing that we need to do when creating a custom control is to decide how we want it to be used, i.e., what is the mark-up that authors should use to make use of our new features?

One custom control that we're going to create will have an image that is a map, centred on a specified longitude and latitude. We'll therefore use the 'value' of the control to provide that location. However, we'd like to also control the size of the map, since sometimes we'd like to have thumbnails, and sometimes much larger images. The obvious way to do this would be to make use of the CSS properties width and height, and allow them to govern the size of the map. Finally, since we don't want the user to be able to update the value of the location we'll use xf:output as the control that we'll be modifying.

A typical usage of this 'interface' might be:

<xf:output value="'51.523004;-0.106859'" appearance="geolocation" style="width: 200px; height: 100px;" />

which gives us a map centred on the formsPlayer office in London.

We'll also create a number of clock custom controls, to illustrate the many different ways we could approach this. For our LED clock, we might want the background colour of our control to be used to determine the background of the clock, and we might want the text colour to set the colour of the digits. As before, since we don't want the user to be able to update the time we would use an xf:output, so our 'interface' might look like this:

<xf:output value="'14:52:00'" appearance="fp:LED" style="color: red; background-color: black;" />

Choosing a base control

Custom controls are extensions to more basic controls so we'll always need some control to enhance. But it's a good idea to choose a base control that reflects in some way the functionality of the control you are trying to build. For example, if you are creating a video player widget, base it on xf:output rather than xf:range or xf:upload. Similarly, even if you are creating a complex control that is more like a dialog-box which is made up of lots of other controls--if ultimately all this control does is to allow a user to choose a colour from a palette then it can be based on xf:select1.

By building on a control that already has some of the behaviour you require, you automatically get a good fall-back mechanism if your forms are used on processors that don't support custom controls, and perhaps more interestingly, you also create the possibility of users replacing your custom control with one of their own choosing, from a personalised stylesheet.

Indicating which controls are custom controls

Since we are going to want some of our controls to be maps and others to be clocks, we need to provide a 'hook' that identifies which controls need to be extended.

Extensions are added based on rules defined using XPath, so we can add pretty much any hook we want. A common convention is to use the class attribute from XHTML or the appearance attribute from XForms. However, it is also possible to use a more dynamic approach, and add extensions based on the underlying data type in the XForms model. In both of our examples above we used the XForms appearance attribute:

<xf:output value="'52;4'" appearance="geolocation" />
<xf:output value="'14:52:00'" appearance="fp:LED" />

But we could also have used the HTML class attribute. In the following example, if a user browsed to our form using an XForms processor that did not have a clock custom control, they would still see the time in green:

<style type="text/css">
  .clock { color: green; }
</style>

<xf:output value="'14:52:00'" class="clock" />

In the next section we'll look at how the custom controls we create can be made available to authors.

Importing custom controls into a form

Linking to a set of bindings rules

We saw earlier how we generally provide an extension 'hook' on a base control that allows us to extend it with our custom functionality. The binding is expressed in a set of binding rules, so the first step is to provide a link to some rules. We do this by using the HTML link element, as follows:

<?xml version="1.0" encoding="utf-8" ?>
<html
 xmlns="http://www.w3.org/1999/xhtml"
 xmlns:xf="http://www.w3.org/2002/xforms"
>
  <head>
    <title>Map widget</title>
    <link rel="bindings" href="my-bindings.xml" />
  </head>
  <body>
    <xf:output value="'52;4'" appearance="geolocation" />
  </body>
</html>

Defining binding rules

The binding rules simply map some expression to a file that defines the behaviour we want. For example, to attach the functionality from the file geo.xbl to all xf:output controls that have appearance="geoposition" we would use the following rule (in my-bindings.xml):

<?xml version="1.0" encoding="UTF-16"?>
<bindings xmlns="http://www.x-port.net/bindingresolver/" xmlns:xf="http://www.w3.org/2002/xforms">
  <binding match="xf:output[@appearance='geoposition']/xf:pe--value" binding="geo.xbl" />
</bindings>

Note that we don't actually bind to the xf:output control as a whole, but the ::value part. This is because a control is actually made up of not just the interactive part (such as an input box), but also includes a label, as well as help, hint and alert messages. Since we may want to bind to each of these items with different custom controls, we always bind to the smallest--or most specific--part of a control that we can. (For more on this, see Anatomy of a control.)

Now that we've made the custom control available to a form, it can be used in any of the ways that the equivalent base control can be used, as we saw earlier in Using custom controls in a form. Our next step is to define the control.

HOWTO: A simple map control

We've established the connection between our form and a list of controls (using link), and we've indicated the rules under which our functionality should be bound to some control (in my-bindings.xml); now we need to define the custom control itself, which we'll place in the file referred to in the binding definitions--geo.xbl.

Our simple control will be based on the standard image control. Since the image control handles its own initialisation and event registration, and because we don't have any special initialisation to do in our map control, then we don't need to add any specific handlers. This makes our control very straightforward, since all it will need to do is support the setValue method which will be called by the backplane whenever the bound data changes.

Since we've decided that the input to our control will be a string that contains a longitude and latitude:

<xf:output value="'51.523004;-0.106859'" appearance="geolocation" style="width: 200px; height: 100px;" />

then the setValue method will need to split the input value apart to get the two coordinates, and then use those values to create a URL for the map image. This is then placed into the src attribute in the image control.

Creating a document to hold custom controls

The first thing we need to do is create a document that will hold our custom control functionality. A bindings document can hold one or more control definitions, so the general format is to have one or more binding elements contained within a bindings element:

<?xml version="1.0"?>
<bindings xmlns="http://www.mozilla.org/xbl">
  <binding>
    ...
  </binding>
  <binding>
    ...
  </binding>
</bindings>

Building on the image control

The binding element defines our control, and since it extends the image control, we indicate this using the extends attribute:

  <binding extends="http://libxh-apps.googlecode.com/svn/trunk/_chrome/image.xbl">
    ...
  </binding>

It's possible for controls that are extended to in turn be an extension of another control, to any depth.

Declaring the setValue method

To create a method we need an implementation element, which will in turn contain as many methods and properties as we care to define for a control. In the simple example we're creating here, we need only one method--setValue--and it will take a single parameter, of the value passed from the backplane:

  <binding extends="http://libxh-apps.googlecode.com/svn/trunk/_chrome/image.xbl">
    <implementation>
      <method name="setValue">
        <parameter name="newVal" />
        <body>
          ...
        </body>
      </method>
    </implementation>
  </binding>

Implementing the setValue method

The actual code for the function is written in JavaScript. The first thing we want to do is obtain the longitude and latitude values from our input string, which we've decided will look something like this:

51.523004;-0.106859

then we need to have a regular expression that looks for a signed floating point number, followed by a separator, followed by another signed floating point number. To give a little flexibility, we might as well allow alternate separators, like a space or comma, and any number of them. This will allow any of the following strings to be parsed:

51.523004 ; -0.106859
51.523004,-0.106859
51.523004 -0.106859
51.523004,; ,; -0.106859

The code to obtain the longitude and latitude is simply:

      <method name="setValue">
        <parameter name="newVal" />
        <body>
          try {
            newVal.match( /([-+]?\d*\.?\d+)[\,\s\;]*([-+]?\d*\.?\d+)/ );

            var nLong = RegExp.$1;
            var nLat = RegExp.$2;

You'll recall that we also decided to set the width and height of the map based on values from the CSS:

<xf:output value="'51.523004;-0.106859'" appearance="geolocation" style="width: 200px; height: 100px;" />

To achieve this we need to retrieve the current width and height, and pass it on to the map server:

            var nLong = RegExp.$1;
            var nLat = RegExp.$2;
            var nWidth = parseInt(this.parentElement.currentStyle.width, 10);
            var nHeight = parseInt(this.parentElement.currentStyle.height, 10);

Now that we have the longitude and latitude on which to centre the map, and we know how big the map should be, we can work out the URL for the image. Although there are many ways we could do this, in this particular control we're going to use a server that conforms to the OpenGIS Web Map Server (WMS) specification. This provides a service where the URL used to request an image can contain all sorts of information to indicate what part of the world the map should show, what type of image should be returned (JPEG, PNG, etc.), what type of map should be shown (terrain, weather, urban centres, etc.), and much more. To illustrate how WMS should work, the following query should work on any WMS-compliant server:

http://[some server and path]?VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326&BBOX=-30.106859,36.523004,29.893141,66.523004&WIDTH=200&HEIGHT=100&LAYERS=DEM_30sec&STYLES=&FORMAT=image%2Fpng&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&EXCEPTIONS=application%2Fvnd.ogc.se_inimage&QUALITY=QUICKEST

The result will be a map image that has a bounding box from -30.106859,36.523004 to 29.893141,66.523004, is 200px by 100px, is a PNG file, and so on. The following is the image obtained from European Space Agency servers, using these exact parameters:

Returning to our code, we'll create our image by concatenating the parameters we need to create the URL, and then storing this value into our control's src property. The image control we've inherited from has conveniently given us a property to write the URL into; we don't need to worry how that property maps to an attribute in mark-up, since all we need to do is set this.src to some value:

            var nWidth = parseInt(this.parentElement.currentStyle.width, 10);
            var nHeight = parseInt(this.parentElement.currentStyle.height, 10);

            this.src = "http://ssems1.esrin.esa.int/mapServer/mapServer?VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326"
              + "&BBOX="
              + (Number(nLat) - 30) + ","
              + (Number(nLong) - 15) + ","
              + (Number(nLat) + 30) + ","
              + (Number(nLong) + 15)
              + "&WIDTH=" + nWidth
              + "&HEIGHT=" + nHeight
              + "&LAYERS=DEM_30sec&STYLES=&FORMAT=image%2Fpng&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&EXCEPTIONS=application%2Fvnd.ogc.se_inimage&QUALITY=QUICKEST";
            }
            catch(e)
            {
              // some error handling
            }
        </body>
      </method>

If you have a recent version of formsPlayer installed then you can run this demonstration directly. If you'd like to obtain the source files to edit locally, they are available at http://libxh-apps.googlecode.com/svn/trunk/tutorials/custom-controls/map/.

<Canvas Opacity="0" x:Name="parentCanvas" Loaded="setClockTime">
  <Canvas.Triggers>
    <EventTrigger RoutedEvent="Canvas.Loaded"
      <EventTrigger.Actions>
        <BeginStoryboard>
          <Storyboard>
            <DoubleAnimation x:Name="hourAnimation" Storyboard.TargetName="hourHandTransform" Storyboard.TargetProperty="Angle" From="180" To="540" Duration="12:0:0" RepeatBehavior="Forever"/>
            <DoubleAnimation x:Name="minuteAnimation" Storyboard.TargetName="minuteHandTransform" Storyboard.TargetProperty="Angle" From="180" To="540" Duration="1:0:0" RepeatBehavior="Forever"/>
            <DoubleAnimation x:Name="secondAnimation" Storyboard.TargetName="secondHandTransform" Storyboard.TargetProperty="Angle" From="180" To="540" Duration="0:1:0" RepeatBehavior="Forever"/>
            <DoubleAnimation Storyboard.TargetName="parentCanvas" Storyboard.TargetProperty="Opacity" From="0" To="0.7" Duration="0:0:4"/>
          </Storyboard>
        </BeginStoryboard>
      </EventTrigger.Actions>
    </EventTrigger>
  </Canvas.Triggers>
  ...
</Canvas>

HOWTO: A clock control using XAML and Silverlight

As with our simple map control, our first step is to decide how authors can make use of our control. A typical usage might be:

<xf:output value="'10:10:10'" appearance="xaml:analogue-clock" style="width:150px;height:150px;" />

This will create a static clock, 150px by 150px, showing a time of 12:10:10. We'll also ensure that the control can cope with full time and date formats, such as:

<xf:output value="'20010604T112000Z'" appearance="xaml:analogue-clock" style="width:150px;height:150px;" />

Now we know how authors will use the control, we can go ahead and build it. Once we're finished, it will look something like this:

The XAML definition of the clock

The definition we'll use for the visual side of the clock is pretty much the same as in the example we saw in the last section. The main change is that we don't need the animations that move the clock hands, since we'll be setting the hands based on the bound data. There is a fourth animation though, which fades in the clock, and we'll keep that.

We won't go into XAML in detail, but one point that needs drawing out is that for each attribute we want to modify, we need to provide a unique name for the element that contains that attribute. In the case of the clock, this has already been done, but were we creating the XAML from scratch we would need to follow this rule. To understand why we need to do this let's look at how the minute hand is defined:

  <Path Data="M -4, 16 l 3 70 3 0 2 -70 z" Fill="white">
    <Path.RenderTransform>
      <TransformGroup>
        <RotateTransform x:Name="minuteHandTransform" Angle="180"/>
        <TranslateTransform X="150.5" Y="145"/>
      </TransformGroup>
    </Path.RenderTransform>
  </Path>

The actual shape of the hand is defined by the Path element, but its orientation is defined by the Angle attribute on the RotateTransform element. So that we can write code to gain access to the attribute, we need to be able to locate the element, and to do this we use the XAML x:Name attribute, which uniquely names the element. Once we've located the attribute, setting it to some value--based on the time value fed into the control--will automatically update the display of the minute hand.

Managing the interaction with the XAML object

Our custom control will play the role of interacting with a XAML object on behalf of the backplane. (We'll show how to indicate which XAML file to use, below.) Since much of what is involved in doing this will be common to any control we develop that uses XAML, we have taken the functionality out into a common base class:

<?xml version="1.0"?>
<bindings xmlns="http://www.mozilla.org/xbl">
  <binding extends="http://svn.x-port.net/svn/public/samples/chrome/com.microsoft.xaml/xf-pe-value.xbl">
    ...
  </binding>
</bindings>

Defining properties to hide interfaces

We saw earlier that positioning the hands of the clock requires setting the Angle attribute on each hand. Whilst we could use code to find this attribute each time we need it, this would make our code very specific, since the method for finding attributes in XAML is very different say, to SVG. Our custom control architecture provides a means to map properties in the XAML object to properties on the custom control. The mapping is handled in the XAML-specific code that we are extending, and all we need to do is specify the relationships:

  <binding extends="http://svn.x-port.net/svn/public/samples/chrome/com.microsoft.xaml/xf-pe-value.xbl">
    <implementation>
      <property name="hourOrientation" element="hourHandTransform" attribute="angle" />
      <property name="minuteOrientation" element="minuteHandTransform" attribute="angle" />
      <property name="secondOrientation" element="secondHandTransform" attribute="angle" />

With these mappings in place, we can now write code like this:

this.hourOrientation = 30;

which will have the effect of setting hourHandTransform.angle.

Specifying the XAML object to load

The next part of our custom control indicates the XAML file to load:

      <property name="secondOrientation" element="secondHandTransform" attribute="angle" />
      <constructor>
        this.firstChild.source = "analogue-clock.xaml";
      </constructor>

Finally, as with our map control, we need to provide an implementation for the setValue method, which will need to crack open the data input, and then use the hours, minutes and seconds to set each of the hands on the clock. First we declare the method and its parameter:

      </constructor>
      <method name="setValue">
        <parameter name="newVal" />
        <body>
          ...
        </body>
      </method>
    </implementation>
  </binding>
</bindings>

Next we parse the input value in order to get the hours, minutes and seconds:

        <body>
          try
          {
            String(newVal).match( /((\d{4})(\d{2})(\d{2})T)?(\d{2})[\:]?(\d{2})[\:]?(\d{2})[Z]?/ );

            var hours = parseInt(RegExp.$5, 10);
            var minutes = parseInt(RegExp.$6, 10);
            var seconds = parseInt(RegExp.$7, 10);

Now we can work out the angle of each hand. Each hour is 30 degrees, although the display will look better if we also add a sixtieth of that for each minute. Once we have the angle we can use the this.hourOrientation to set the correct attribute in the XAML object:

            var seconds = parseInt(RegExp.$7, 10);

            var angle = (hours / 12) * 360 + minutes/2;

            angle += 180;
            this.hourOrientation = angle.toString();

Finally, we can do the same thing for the minutes and seconds:

            this.hourOrientation = angle.toString();

            angle = (minutes / 60) * 360;
            angle += 180;
            this.minuteOrientation = angle.toString();

            angle = (seconds / 60) * 360;
            angle += 180;
            this.secondOrientation = angle.toString();
          }
          catch(e)
          {
            // some error handling
          }
       </body>

Using our custom control

All we need to do now is to create a bindings file:

<?xml version="1.0" encoding="UTF-16"?>
<br:bindings
 xmlns:br="http://www.x-port.net/bindingresolver/"
 xmlns:xf="http://www.w3.org/2002/xforms"
 xmlns:xaml="http://schemas.microsoft.com/winfx/2006/xaml"
>
  <br:binding match="xf:output[@appearance='xaml:analogue-clock']/xf:pe--value" binding="analogue-clock.xbl" />
</br:bindings>

Assuming that we call this file my-bindings.xml then we can now use the binding rules in the normal way:

  <head>
    <title>Silverlight Clock</title>
    <link rel="bindings" href="my-bindings.xml" />
    .
    .
    .
  </head>
  <body>
    <xf:output ref="clock" appearance="xaml:analogue-clock" class="clock" />
  </body>

If you have a recent version of formsPlayer installed, as well as a version of Microsoft's Silverlight then you can run this demonstration directly. If you'd like to obtain the source files to edit locally, they are available at http://libxh-apps.googlecode.com/svn/trunk/tutorials/custom-controls/silverlight-clock/.