The designers of XForms put lots of thought into ways of making the design flexible enough to be customized at all the critical points. The following sections describe areas where XForms has explicitly been designed to be extended. 11.2.1 With ScriptIt's true that XForms eliminates the need for a great deal of scripting. But not all. This is a good thing, since any system that could replace an entire scripting language (and associated libraries) would end up nearly as complicated as what it tried to replace or worse. Instead, if a system replaces the 20% of the most commonly used functionality, it can still eliminate 80% of the need for script. XForms doesn't include a script element to hold any script that's a job for the host language. Typically, a script will be called as a result of XML Events processing, as described in Chapter 7. The XML-centric design of XForms influences the way script access to data works. Since a form at all times has a well-formed bit of XML behind it, represented by an XPath data model, script authors have a natural and familiar data structure with which to manipulate the form data. Availability of DOM access isn't a given there's no requirement for an implementation to be based on the DOM. In fact, of the existing XPath engines, they seem to be split fairly evenly between DOM-based and not. However, in implementations that support the DOM, a special function callable from a script returns a DOM document representing the form data, which can be read, manipulated, and updated. As with other DOM interfaces, these methods are available from the scripting object representing the model element in question. 11.2.1.1 The getInstanceDocument( ) methodThis method returns a DOM document that represents the current state of the instance data. One distinction about the DOM interfaces is that they are considered "live," in that they present a view of the document that stays in sync with any changes from external sources. But the DOM Document returned here is, at best, only half-live. The reason for this is that the spreadsheet-like XForms rules that ensure that changes to data are correctly propagated across the instance data do not take into account changes that happen due to script. For that, separate methods are needed. 11.2.1.2 The rebuild( ), recalculate( ), revalidate( ), and refresh( ) methodsGenerally, after changes have been made to the DOM document retrieved from getInstanceDocument( ), the rest of the system can be updated with a sequence of calls to rebuild( ), recalculate( ), revalidate( ), and refresh( ). Overall, the code tends to look something like the following JavaScript. var modelElem = document.getElementById("id_of_model_element"); var instDoc = modelElem.getInstanceDocument("id_of_instance_element"); // Perform manipulations on instDoc here ... modelElem.rebuild( ); modelElem.recalculate( ); modelElem.revalidate( ); modelElem.refresh( );
Each of the four methods perform a slightly different task.
As can happen in the standards process, having four separate methods to accomplish this provides a finer level of detail than nearly any form author would ever need. To tidy up your code, you might consider defining a single function to handle it all, like this: function fullUpdate( elem, structure_changed ) { if (elem) { if (structure_changed) elem.rebuild( ); elem.recalculate( ); elem.revalidate( ); elem.refresh( ); } } 11.2.2 With New Datatypes and LibrariesOne major reason for choosing XML Schema datatypes for use in XForms is that new datatypes can be defined easily. In fact, in Chapter 4, an example of a new email data type is provided. 11.2.3 With XPath Extension FunctionsNearly all XPath implementations provide hooks for additional functions to be defined, and also include several built-in ones. Such extensions can be used with XForms as well.
An XPath expression will evaluate as a syntax error if it references a function that the XPath engine doesn't know about. This can cause a problem for forms that use extension functions, since the poor user could be half-way through completing the form before the error shows up. A special attribute, functions, as part of the model element, is the place to list (by QName) any XPath functions absolutely necessary for the form to function. The XForms processor will check this list at startup and give a suitable (and immediate) error message, if necessary. 11.2.4 With New Form ControlsEven though XForms defines a broad range of general-purpose form controls, others might still be needed. For example, XForms 1.0 doesn't have an electronic signature form control. While it would be straightforward for a vendor to add such a form control in another namespace, any forms that used it probably wouldn't function as expected, since the new form control would be treated as an unrecognized foreign element, and summarily ignored. The xforms:mustUnderstand attribute helps a little, giving foreign elements a means to signal that they really are critical, and that it would be better to not render the form at all than to ignore a particular element, as the following example shows: <vendor:signature bind="sigdata" xforms:mustUnderstand="true"> <xforms:label>Click to sign</xforms:label> </vendor:signature> Even so, any XForms Processor that doesn't understand a special element as vendor:signature is still shut out from filling such a form, which undermines the main point of having a standard in the first place. (Determining whether a given organization considers this a feature or a bug is left as an exercise for the reader.) 11.2.5 With XForms ActionsXForms defines a number of elements that serve to specify declarative actions, such as setfocus, setvalue, and message. Sometimes, it is more convenient to add another declarative action than to write script. In such cases, a new element can be used as an XForms Action. As with other elements, the mustUnderstand attribute can be useful to override the ignore-if-unknown behavior that would otherwise occur. 11.2.6 With Custom EventsIt's also possible to use events other than the DOM-defined or XForms-defined ones. For example, when a certain condition happens, you might want to send an event that a listener elsewhere in the document can do something useful with. The element dispatch can be used to send off any event, and the XML Events machinery described in Chapter 7 can observe custom events just as well as xforms-prefixed ones. 11.2.7 With New Serialization FormatsControl over how form data is serialized comes from the method attribute on the submission element, and to a lesser degree, the details of the URI on the action attribute. Again, the XForms specification covers a wide range of useful values, but not every possible combination. In particular, there's no support for XML Protocol, including SOAP. (This is a planned feature for the next version of XForms. Even without the benefit of standardization, some vendors are already marching ahead with SOAP submission methods.) |