XForms/Custom Controls

Motivation

Very often complex forms need functionality that go beyond the basics offered by the W3C XForm standard. The good news is that XForms is designed to be easy to extend. This process is called creating a Custom Control.

There are several reason to create XForms custom controls:

custom presentation - XForms controls as rendered by your XForms processor do not provide the right presentation for your form
custom data types and date type to UI mappings - existing XForms controls do now work properly with your data types (for example binding a boolean to a check box)
advanced XForms controls - you need customized controls to extend the functional of the base XForms controls
new host language - you'd like to support XForms in host languages

The following example uses a technology called XML Bindings to create a new control. This control displays a different image when a select1 list is selected.

Screen Image

Sample Program

<html 
  xmlns="http://www.w3.org/1999/xhtml" 
  xmlns:xf="http://www.w3.org/2002/xforms">
   <head>
      <title>Custom Image Control Sample</title>
      <bindings id="xformsBindings" xmlns="http://www.mozilla.org/xbl" xmlns:html="http://www.w3.org/1999/xhtml">
         <binding id="output-image" extends="chrome://xforms/content/xforms.xml#xformswidget-base">
            <content>
               <html:div>
                  <html:img anonid="content" />
               </html:div>
            </content>
            <implementation implements="nsIXFormsUIWidget">
               <method name="refresh">
                  <body>
                  <!-- 
                  set the src attribute on the html:img to be the simpleContent
                  of the instance node bound to this control
                  -->
	          var img = document.getAnonymousElementByAttribute(this, "anonid", "content");
	          img.setAttribute("src", this.stringValue);
	          return true;
	          </body>
               </method>
            </implementation>
         </binding>
      </bindings>
      <xf:model>
         <xf:instance xmlns="">
            <data>
               <curimg />
               <img label="Firefox">http://www.mozilla.org/foundation/identity-guidelines/firefox-128.png</img>
               <img label="Thunderbird">http://www.mozilla.org/foundation/identity-guidelines/thunderbird-128.png</img>
               <img label="Bugzilla">http://www.mozilla.org/images/p-bugz.gif</img>
               <img label="Mozilla">http://www.mozilla.org/images/mozhead-80x64.gif</img>
            </data>
         </xf:instance>
      </xf:model>
      <style type="text/css">
      @namespace xf url(http://www.w3.org/2002/xforms);

      xf|output[mediatype="image/*"] {
        -moz-binding: url('#output-image');
      }
    </style>
   </head>
   <body>
      <h1>Custom Control Sample</h1>
      <xf:select1 ref="curimg">
         <xf:label>Select image to display: </xf:label>
         <xf:itemset nodeset="../img">
            <xf:label ref="@label" />
            <xf:value ref="." />
         </xf:itemset>
      </xf:select1>
      <xf:output ref="curimg" mediatype="image/*" />
   </body>
</html>

Discussion

This example uses the xbl:binding structure, a few lines of JavaScript and a binding in the CSS file. Note that example will only work within FireFox since XML bindings are not currently part of the XForms specification.

Note that the XML Binding Language (xbl) in currently a w3C working draft. See XBL working draft. When XBL becomes a recommendation these examples may have a better chance to run in multiple implementations of XForms. Right now we need to use implementation specific tags.

References

This example program was posted on the FireFox XForms documentation web site in July 2005 by Allan Beaufour: XForms Custom Controls

Next Page: Warn on Navigate Away | Previous Page: Search Amazon
Home: XForms