xforms tutorial by rajamaniM


e-forms technology (xforms) details included

More Info
									+ MENU 

Developer Home   Developer library   YES Certified  Program   Project hosting   Current events   Help   What links here   Related changes   Upload file   Special pages   

Search   Go   Search  

XForms tutorial 
About the tutorial  This tutorial introduces XForms technology—an evolving standard for the implementation of Forms technology in a Web application. You will  look at how XForms are written (the code) and how that code translates into an implementation.  To see the forms in action, you will use the Novell XForms Technology Preview (Processor) application. This application is an XForms  processor implemented using Java Swing. Along with rendering the form and implementing the behavior of the form, it allows you to take an  under­the­covers look at the workings of an XForms processor. You will be able to see the instance data changing as you navigate, along with  the events fired during the use of the form.  Before diving into the guts of XForms, the tutorial will first review the problem with forms today and how XForms resolves it. Then it will provide  an overview of XPath, an important XML technology used in XForms. (You can find more Resources at the end of the tutorial.) About XForms  and XPath  About XForms and XPath  Overview of XForms  Today most Web applications are being developed to work using a Web browser as the user interface (UI). Great strides have been made in  server implementations that are providing the services required for applications that are presented in a browser. And the look and feel of these  applications has been greatly improved.  What has fallen behind is the area of accepting input from the user—more often called the form. Although some advances have been made in  forms technology, its inconsistent implementation across browsers and reliance on scripting for client­side processing has made  implementing robust forms difficult, with most processing being done on the server and thus not taking advantage of the power of the client  hardware running the browser.  XForms resolves these and other forms issues by presenting an abstract definition of the form that does not describe the implementation, but  rather separates the form into data, logic, and presentation. An XForms processor can be implemented on a browser as part of an HTML page  and rendered as HTML with JavaScript. Or it can be implemented as a Java Swing application (as done in the Processor application). XForms  also provides for the use of an event­driven model in an application, familiar as a GUI application using a keyboard and mouse where the user  controls the flow and direction of the application.  XForms is an XML language for describing what a form in a Web application is to do and how it is to be presented. The implementation is  typically going to be part of an XHTML form, and the tutorial discusses it in that context. A key design feature of XForms is the separation of  purpose from presentation in a form.  Data  The purpose of the form is called the model and is described in the head element of an XHTML form. The model specifies the instance data  used on the form and is requested as input from the user. This instance data can be referenced in the model directly or as a link to an external  XML file. A schema for the instance data can be used to provide data typing and validation requirements.  Logic  The model also contains actions that specify the behavior of the form and validation requirements. You can specify which fields are required  and under what conditions they are required. The XForms processor can then guide the presentation and interaction with the user without  making a round trip to the server—improving response time while taking advantage of the power of the client hardware. Also, you can call  many functions that are native to XForms, such as sum, avg, min, max, and so on.  Presentation  XForms provides a standard set of UI visual controls that describe an abstract concept of collecting data from the user but leave the  implementation to the XForms processor. For example, the select1 provides a list of values from which the user can select only one. This  could be implemented as a series of radio buttons, a dropdown list, or some other mechanisms appropriate to the target platform.   For describing the layout, color, and fonts used in the presentation, XForms uses Cascading Style Sheets (CSS). This provides for a flexible  approach to design and separates the controls used on the form from their style features. This way different styles can be used with the same  form—styles that take advantage of the features of a particular target platform or even provide a different look and feel.   

Overview of XPath  An important part of XForms is the use of other XML technologies to provide a robust and rich feature set. Some of these XML technologies  are XML Schema, XML events, and XML Path language (XPath). For more information, see Resources at the end of this tutorial.   XPath is a language that provides a mechanism for identifying what content of XML document (elements and attributes) you are interested in  using or retrieving. A rich set of functions is provided that allows you to manipulate the content. The syntax used to address elements and  attributes in a document is similar to the syntax in navigating and using a file system. Similarly, the context node is like the current directory  of a file system in that it is used to resolve relative expressions.  XPath models the XML document as a tree of nodes, including element, attribute, and text nodes. These nodes can be converted into a string  value, and some nodes (such as element and attribute) have names. The name fully supports XML Namespaces, and therefore a name is  comprised of a local name and an optional namespace URI. In using XPath you create an expression that will evaluate to one of the following  four basic types: 

   * Node ­set (an unordered collection of nodes without duplicates)    * VALUE=1>Boolean (true or false)    * VALUE=1>Number (a floating ­point number)    * VALUE=1>String (a sequence of UCS characters) 

Expressions  The expression is evaluated to identify a node or node­list with respect to a context. The most common kind of expression is a location path  (similar to a path in a file system) that can be expressed in an unabbreviated syntax or more commonly with an abbreviated syntax. The  location path can be relative or absolute. A relative location path consists of a sequence of one or more location steps separated by "/". An  absolute location path consists of "/" optionally followed by a relative location path, which again consists of a number of location steps. A  location step has three parts: 

   * An axis, which specifies the tree relationship between the nodes selected by the location step and the context node    * A node test, which specifies the node type and expanded name of the nodes selected by the location step    * Zero or more predicates, which use arbitrary expressions to further refine the set of nodes selected by the location st

The XPath expression can also include functions that will operate on the contents of the selected node or are evaluated to identify the node or  nodes. The following sections list most common operators and abbreviated axes, functions, and some examples of XPath in action.    XPath in XForms  If you are familiar with XPath and have used it in the past, there are three important things to understand when writing an XPath expression in  an XForms application. 

   * When you use XPath in XForms, you specify the XPath expression in an attribute of an XForms element. If the instance da    * When you refer to instance data in an XForms document, absolute paths begin in the <instance> element of that data:          o So "/a/b/c" might refer to "/html/head/xforms:model/xforms:instance/a/b/c".     * For relative paths, the context node is the root element of the instance data ("a" above), so you would use "b/c" to re          o So children of an <xforms:group ref="/a/b"> element have b as their context node, and so "c" would refer to the "

Operators and abbreviated axes  The following table provides a list of the more common operators and abbreviated axes used in writing an XPath expression. For a complete  list, see the specification and online references specified in Resources.  Syntax  Description  para  Selects the para element children of the context node  .  Selects the context node  ..  Selects the parent of the context node  @  Identifies an attribute, followed by the attribute name or * for all attributes of the context node  /  Node separator (when the first character, indicates absolute path from document root)  //  The descendant­or­self axis that contains the context node and the descendants of the context node 

Selects all element children of the context node  []  Predicate that filters a node­set with respect to an axis to produce a node­set  Functions  This section documents the most commonly used functions with brief descriptions of what the functions do. For a complete list, see the  specification and online references specified in Resources.  Node test functions  Function  Description  boolean text()  Returns true if the context node is a text node  boolean comment()  Returns true if the context node is a comment node  boolean node()  Returns true if the context node is a node  boolean processing­instruction (string?)  Returns true if the context node is a processing instruction node  Node set functions  Function  Description  number last()  Returns a number equal to the context size from the expression evaluation context  number position()  Returns a number equal to the context position from the expression evaluation context  number count(node­set)  Returns the number of nodes in the argument node­set  node­set id(object)  Relects elements by their unique ID  string local­name(node­set?)  Returns the local part of the expanded­name of the node in the argument node­set that is first in document order  string namespace­uri(node­set?)  Returns the namespace URI of the expanded­name of the node in the argument node­set that is first in document order  string name(node­set?)  Returns a string containing a fully qualified name representing the expanded­name of the node in the argument node­set that is first in  document order  String functions  Function  Description  string string(object?) 

Converts an object to a string  string concat(string, string, string*)  Returns the concatenation of its arguments  boolean starts­with(string, string)  Returns true if the first argument string starts with the second argument string  boolean contains(string, string)  Returns true if the first argument string contains the second argument string  string substring­before(string, string)  Returns the substring of the first argument string that precedes the first occurrence of the second argument string in the first argument string    string substring­after(string, string)  Returns the substring of the first argument string that follows the first occurrence of the second argument string in the first argument string    string substring(string, number, number?)  Returns the substring of the first argument starting at the position specified in the second argument with length specified in the third argument   number string­length(string?)  Returns the number of characters in the string  string normalize­space(string?)  Returns the argument string with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of whitespace  characters by a single space  string translate(string, string, string)  Returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding  position in the third argument string  Boolean functions  Function  Description  boolean boolean(object)  Converts its argument to a boolean  boolean not(boolean)  Returns true if its argument is false, and false otherwise  boolean true()  Returns true  boolean false()  Returns false  boolean lang(string)  Returns true or false depending on whether the language of the context node as specified by xml:lang attributes is the same as or is a  sublanguage of the language specified by the argument string  Number functions  Function  Description  number number(object?)  Converts its argument to a number  number sum(node­set) 

Returns the sum, for each node in the argument node­set, of the result of converting the string­values of the node to a number  number floor(number)  Returns the largest (closest to positive infinity) number that is not greater than the argument and that is an integer   number ceiling(number)  Returns the smallest (closest to negative infinity) number that is not less than the argument and that is an integer   number round(number)  Returns the number that is closest to the argument and that is an integer  Examples of XPath in action  The following examples will show how XPath can be used to locate and extract the content of an XML node. The examples are in the format of  XPath expression, and what is returned by the expression from the sample document is highlighted in bold.   Example 1  /root/a/b[last()]/text()  <root> 

 <a>    content 1      content 2      <c one="1" two="2" />    <d>       content 3        <c>content 4</c>    </d>  </a>  <c>    <d>content 5</d>    content 6    </c>

</root>  Example 2  //b  <root> 

 <a>    content 1      content 2      <c one="1" two="2" />    <d>       content 3        <c>content 4</c>    </d>  </a>  <c>    <d>content 5</d>    content 6    </c>

</root>  Example 3  /root/a/c/@two  <root> 

 <a>    content 1      content 2      <c one="1" two="2" />    <d>       content 3        <c>content 4</c>    </d>  </a>  <c>    <d>content 5</d>    content 6    </c>

</root>  Example 4  /root/a/d/c  <root> 

 <a>    content 1      content 2      <c one="1" two="2" />    <d>       content 3        <c>content 4</c>    </d>  </a>  <c>    <d>content 5</d>    <d>content 6</d>  </c>

</root>  Example 5  /root/a/d  <root> 

 <a>    content 1      content 2      <c one="1" two="2" />    <d>       content 3        <c>content 4</c>    </d>  </a>  <c>    <d>content 5</d>    <d>content 6</d>  </c>

</root>  Example 6 /root/a/c/@*  <root> 

 <a>    content 1      content 2      <c one="1" two="2" />    <d>       content 3        <c>content 4</c>    </d>  </a>  <c>    <d>content 5</d>    <d>content 6</d>  </c>

</root>  Preparing to use the tutorial  Prerequisites 

   * As stated previously, XForms builds on existing XML technologies—so you need to be comfortable with the XML specificati    * You also need a basic understanding of XML Namespaces ( http://www.w3.org/TR/REC ­xml­names/ ) and XML Schema ( http://www.    * To fully appreciate and understand the power and flexibility of XForms, you need an understanding of HTML forms.    * Last, you should be familiar with the concept of an event ­driven model —such as what an event source is and what the eve

Instructions for using the tutorial  In this tutorial you will look at XForms code fragments and see what the code is designed to do. You will also see what happens as the code  is executed in the Processor application. You will be provided step­by­step instructions for using Processor, along with screens of the results  as they appear in Processor.  To run the Processor application, you need first to have installed J2SE 1.4 (available for download from  http://java.sun.com/j2se/1.4.1/download.html). Next, you need to install the Processor, itself. The downloads are available at  http://www.novell.com/xforms, for the Windows, Linux, and Solaris platforms. This page also includes a Java Web Start version of the  processor. Once you have J2SE 1.4 installed, you can click on the Java Web Start link and the processor will be downloaded and started,  automatically. After you install the Processor application, you can start it. In Windows, you can use the short cut by clicking Start>Novell  exteNd>xForms Technology Preview>xForms Technology Preview. You can also use the startup.bat file or shell script in the install directory. 

  1. In the install directory double click startup.bat .

  2. The Processor application will start. 

Location of source examples  The tutorial reviews three examples of increasing complexity to explore the features of XForms: 

   * Example 1 from the XForms specification. The entire source code can be found in the installation directory at:

     samples\SpecEx\example1.xml    * A phone search form that searches a data set of names and phone numbers by last name. The entire source code can be fou


For each example the tutorial will discuss the code, and you will view the impact —both in the presentation and in the instance data produced  using the form.  Viewing the source code  You can view the source code for the examples used in the tutorial. If in your Windows environment you have associated files with an .XML  extension to an application such as Novell exteNd Workbench or Internet Explorer, you can open the source as follows: 

        1. In the main window of the Processor application, select            View>Open source external.

           Alternatively, you can use the Ctrl ­E keyboard combination.         2. This opens the application associated with XML files —in this example, Internet Explorer.  

If you do not have a file association you will get the following message.  You can also view the source code by choosing the Processor application's Source View 


         In the main window of the Processor application, select View>View Source.       2.

         This opens a basic Source View window.

Setting up the Processor windows for the tutorial  The tutorial will examine how the XForms code will interact with a user on a form and what it is doing behind the scenes to the data being  processed on the form. The tutorial will discuss various pieces of XForms code and then you will see the impact using the Processor  application. The Processor provides an Instances window that allows you to view the changes to the instance data and what events were fired  as you interact with the form. This window also enables you to see the entire form including the UI controls and triggers, again showing the  events fired.  To make it easier to view a form in one window and at the same time view the changes to the instance data (along with the events driving the  application), you need to set up the Instances window and main window so that you can see them side by side, as follows: 

        1. Start the Processor application.         2. Select View>Instances.

When you have both application windows open, you need to resize and lay them out such that you can easily see one window as you interact  with the other. Figure 1 shows a sample layout. You may also want to set the Instances window so that the view of the model at the top has  more space so that you can better view changes to the model.  Figure 1 The XForms browser home page with the Instances window and main window open. The two windows are sized so they can be  viewed together. Tutorial for Example 1  The first XForms example discussed is Example 1 used in the XForms specification (see Resources) to demonstrate the features of XForms.   Before you begin  Make sure you have followed the instructions in Setting up the Processor windows for the tutorial before starting the tutorial.   You can also open the source code using your favorite XML or text editor (you can find the source in the installation directory at  samples\SpecEx\example1.xml) . If you have a file association to your favorite XML editor in your Windows environment, you can open the  source by typing Ctrl­E. (If you need to, see Viewing the source code.)  Exercises 

   * Internationalization    * Internationalization Code    * Behind the Scenes in the Form    * Instance Data    * Accepting Input 

Internationalization  In this first exercise, you will see the forms default presentation and then change the language used for displaying labels for input fields and  buttons. One of the benefits of XML is that it is very easy to support Internationalization in your applications. Because XForms is XML, it is  easy to implement forms that support multiple languages. 

  1. Go to the Processor application home page (if you are not already there) by clicking the button on the toolbar.   2. Click Example 1 in the specification Examples block.

     The forms default display for the labels used for input fields and buttons is French.

  3. Click the English button to change the language to English.

Internationalization code  In the first exercise you saw that the text displayed on the form defaults to French but is controlled by clicking the buttons displayed at the  top of the form. Now you will examine the XForms code used to generate this example.  

   * The buttons are defined on the form as trigger form controls with a toggle user action. Both triggers are contained in 

     <group ref="." xmlns=" http://www.w3.org/2002/xforms/cr ">         <trigger>          <label>Fran çais</label>            <toggle case="fr" ev:event="DOMActivate" />        </trigger>        <trigger>          <label>English</label>          <toggle case="en" ev:event="DOMActivate" />        </trigger>      </group>

   * The trigger element is used to define user ­triggered actions and can be rendered as buttons or whatever is appropriate 

   * The label element defines the text to be displayed.

     <label>English</label>    * The toggle element defines the case attribute and listens for the DOMActivate event as defined in the ev:event attribut

     The DOMActivate event is dispatched by the trigger. This is the default action required of a form control when the user

     The toggle will dispatch the xforms ­select and xforms ­deselect events to change the switch element

     <toggle case="en" ev:event="DOMActivate" />    * The event triggers a switch form control.

     <switch xmlns=" http://www.w3.org/2002/xforms/cr "> 


      </switch>      * The block of code to be "executed" is specified by the case attribute, which is the value of the id attribute in the ca

     <toggle case="en"  … 


      <case id="en">      * The initial value displayed (French) is determined by the first case element in the switch .

     <switch xmlns=" http://www.w3.org/2002/xforms/cr "> 

     <case id="fr">





Behind the scenes in the form  By clicking on the language buttons, you cause the displayed text to change. In the previous exercise you reviewed the XForms controls. Now  you will look behind the scenes of how the model is impacted as you use the language buttons. Processor provides the ability to do this by  using the Instances window (see Setting up the Processor windows for the tutorial). The window will display the events fired and the data  changed on the form.  The Instances window is divided into two panels (see Figure 2). The top panel displays the instance data or the entire form, displaying the  actual changes as you interact with the form in the main window. The bottom panel displays the events fired as you interact with the main  window. The index number on the event is referenced in the top panel next to the element or attribute that was impacted by the event. The two  options available for viewing the data allow you to display the entire XHTML/XForms file (use Instance root) or a specific form model by  selecting it from the dropdown list.  Figure 2 The Instances window showing both panels. The panels are placed side by side in this figure but are actually top to bottom when you  run the application. The top (left) panel displays the instance data. The bottom (right) panel displays the events fired.  

  1. To split the window so that the top panel takes half the screen, drag (click and hold the left mouse button) down the m

  2. Select Instance root from the Models dropdown list.

  3. Click the next to DOCUMENT to expand the tree view. Then expand the body, group, and switch trees until your view looks

  4. In the main browser window, click the button, changing the text to French.   5. Look in the Instance window. In the bottom half, you see several events numbered in the order in which they were fired.

  6. In the top half, you see the index numbers next to the elements impacted by the event, when either the element (in the 

   * Depending on how you interacted with the main window, your index number and number of events in this window may differ.    * 7 ( DOMactivate ) started the process when you clicked on the button. In the Internationalization Code exercise, you sa

   * 8 ( xforms ­deselect ) changed the text by deselecting the English case in the switch .

   * 9 ( xforms ­select changed the text by selecting the French case in the switch .

Instance data  As discussed in Intro to XForms, XForms consists of a model that includes one or more instance data definitions. The XForms model is  defined in the head element of the XHTML document. When this information is filled in, it will be transmitted to the server when the user  initiates the submission. 

   * The instance element includes the data for the form. It can be the data to be filled in by the user via the form contro


     <my:payment as="credit">

      …     * This value is used as the initial value in the select1 form control. The ref attribute is an XPath expression pointing 


      <select1 ref="@as">  

     <label xml:lang="en">Select Payment Method</label>

      …     * The my:payment element contains two child elements: my:cc (credit card number) and my:exp (expiration date).  


      <my:cc />  

     <my:exp />


  1. Change Models in the Instance window to [Default Model] by selecting [Default Model] from the dropdown list.  

  2. Click the next to DOCUMENT to expand the tree view. Expand the my:payment, Attributes, and as entries until the top pan

1 Accepting input   2 The code   3 Entering data: credit   4 Entering data: cash   5 Tutorial for the Phone Search  5.1 Two instance data references in the model  5.2 The search in action   5.3 Start the search   5.4 Search and populate   5.5 Controlling the presentation    5.6 CSS support in the Processor    5.7 Optional advanced exercise   6 Resources   

Accepting input 
Now you will take a look at the process of accepting input from the user into the defined fields. In the XForms specification, there are form  controls that define the layout and input mechanisms to be used for accepting input to fill the instance data. These controls provide an  abstraction (not implementation) of what and how data is to be accepted by the user. The actual implementation is left to the rendering  application, using the method appropriate for the underlining implementation. How the field is displayed is defined in the input control, and  validation on the data can be defined in the schema (if one is specified) or in the model. 

The code 
You will use the code examples for the English entry with the understanding that the only difference between the two sections is the text  displayed. You will examine the code contained in the case element, shown in Code 1. 

<case id="en">   <select1 ref="@as">     <label xml:lang="en">Select Payment Method</label>     <choices>       <item>         <label xml:lang="en">Cash</label>

        <value>cash</value>         <alert xml:lang="en">Please do not mail cash.</alert>       </item>       <item>         <label xml:lang="en">Credit</label>         <value>credit</value>       </item>     </choices>   </select1>   <input ref="my:cc">     <label xml:lang="en">Credit Card Number</label>   </input>   <input ref="my:exp">     <label xml:lang="en">Expiration Date</label>   </input>   <submit submission="s00">     <label xml:lang="en">Buy</label>   </submit> </case>

Code 1 Form controls that display the input fields for the English portion of the code. Being part of a case in the switch, it will be  displayed only when the trigger sets its case value.  The select1 element provides a list of items from which the user may select only one. This could be rendered as a dropdown list or as radio  buttons. The ref attribute identifies (using XPath) the instance data that will hold the selected value —in this example, the as attribute in the  my:payment element. 

     <select1 ref="@as">       …        </select1>  

The label element is required in all XForms controls to specify the label or prompt for the input control. The text to be displayed can be  inline as content (as in this example) or as a reference to instance data or an external link. 

     <label xml:lang="en">Select Payment Method</label>

The choices element is used to group available alternatives in a selection control such as select1.  

     <choices>       …        </choices>  

The item element is used to provide the label and value that will be used in a list. 

     <item>      <label xml:lang="en">Credit</label>      <value>credit</value>      </item>

The input element is used to provide for single­line, freeform data entry. The ref attribute identifies (using XPath) the instance data that will  hold the selected value—in this example, the my:cc element.  

     <input ref="my:cc">      <label xml:lang="en">Credit Card Number</label>      </input>

The submit element provides a control that allows the user to specify that the instance data should be transmitted to the server, taking all  the input values the user provided in the various input controls after handling any validation specified. 

     <submit submission="s00">      <label xml:lang="en">Buy</label>      </submit>

The submission attribute in the submit element (above) references the id attribute of a submission element in the model that specifies the  action (read location) and method to be used by the submit . 

     <xforms:submission      action=" http://www.example.com/buy.rb "       method="post"      id="s00" />

Entering data: credit 
Now that you have reviewed the code for the form controls that will accept data and bind the entered values to the instance data, you will  examine the code in action by entering some information. You will start with the payment method of credit.  1. The initial payment method is set to credit, because that is the value in the as attribute of my:payment in the instance element in the  model (see Instance Data) making it the default value. Leave the selection at credit.


2. Tab to the Credit Card Number field and enter 333­444­5555.   3. Tab to the Expiration Date field and enter 12/2002 (this field may span over two lines depending on your screen resolution and window  size).   4. The last entry is the submit , which you will not use in this exercise—because there is no back­end server waiting to receive the  request.   5. As you enter the information, the Instance window shows what is happening to the instance data in the model .  6. Of particular interest are the values for Credit Card Number ( my:cc ) and Expiration Date ( my:exp with the references to the indexes.   

7. The events referenced are listed in the bottom panel.  

Depending on how you interacted with the main window, your index number and number of events in this window may differ. In the  following discussion, only those that pertain to the code of interest are used. The index numbers referenced are the ones in the screen  above.  8. The events in action for Credit Card Number:  10 and 16 ( DOMSubtreeModified ) was fired when you entered the value.  11 and 14 ( novell­value­changed ) was fired as you exited the field by tabbing to the next field.  12 and 15 ( novell­constraint­changed ) indicates that the required data was entered. 

Entering data: cash 
Selecting the Payment Method cash will change the data entry requirements. Credit Card Number and Expiration Date are not required. Now  you will examine how this is accomplished, by examining the code and then seeing it in action.  In the model there is a bind element that has been been defined for the Credit Card Number ( my:cc ) and Expiration Date ( my:exp )  instance data values. 

     <xforms:bind nodeset="my:cc" relevant="../@as='credit'" required="true()"/>      <xforms:bind nodeset="my:exp" relevant="../@as='credit'" required="true()"/>

The attribute nodeset provides the link to the instance data affected using XPath.  


The relevant attribute specifies that the instance data is affected only when the as attribute equals credit. 


The required attribute is set to true by the XPath function specifying that the value is required if the as attribute has a value of credit.  


1. Change the Payment Method by clicking Image:Image34.gif and then selecting cash. Notice that the Credit Card Number and  Expiration Date fields are grayed out. (If you try to enter values in the fields, they are not accepted. This is the result of the bind  element (see above discussion). The fields are no longer applicable.)   

2. In the Instance window you see that only the as attribute changed.   

3. The seven new events fired when you changed the Payment Method to cash.  

Depending on how you interacted with the main window, your index number and number of events in this window may differ. In the  following discussion, only those that pertain to the code you are interested in is discussed. The index numbers referenced are the ones  in the screen above.  4. Events 0—2 impact the actual selection of the new Payment Method.    

5. Event 3 ( novell­relevant­changed ) are the result of the bind element. They flag the Credit Card Number element and content as no  longer relevant.    6. Event 4 ( novell­relevant­changed ) are the result of the bind element. They flag the Expiration Date element and content as no longer  relevant.   

Tutorial for the Phone Search  
The Phone Search example (see Figure 3) under the Forms category presents a simple phonebook sample application that will search a set  of data provided as instance information. All actions on this form will be performed by the Processor. If this were to be done as a standard  HTML form, the browser would require either JavaScript or a round trip to a server to perform the same functionality. One of the advantages of  XForms is the ability to have processing done on the client rather than the server, without extensive JavaScript.  You can open the source code using your favorite XML or text editor (you can find the source in the installation directory at  samples\Search\search.xml) . If you have a file association to your favorite XML editor in your Windows environment, you can open the source  by typing Ctrl­E or you can use the Processor's internal Source Viewer, clicking View>Source . (If you need to, see Viewing the source  code.)   

Figure 3 Initial display of the Phone Search form. Entering a last name and clicking the Search button will initiate a search  through the instance data.    1. You can get to the Processor application home page by clicking the   button on the toolbar.  2. On the Forms section of the home page, select the Phone Search link.   

3. This displays the default phone search ready to accept a search. Notice that it has no initial default values.   


4. You should have the form open in the main Processor window with the Instance window next to it, as shown below. (If you need  instructions on setting it up, go to Setting up the Processor windows for the tutorial.)   

Two instance data references in the model 
What is interesting about this form is the use of two instance references in the model. One is the database you will search, with names and  phone numbers. The other is a placeholder for the data that is displayed on the form—the search results.   The first instance element has the attribute src ; this is a reference to an external data file that will be loaded by the Processor application  and used as your search database. This reference is an URL, in this case relative to the parent document, the XHTML file you are viewing  in the Processor application. It could also be an URL pointing to some other server or location. The id attribute uniquely identifies this data  instance and distinguishes it from the other data instance in the model . 

     <xforms:instance src="search_instance.xml" id="default"/>

The following is a representative entry from the external file (database) you will use in the search. You could edit this file and add your own  data as long as you followed the structure. 

     <phone>        <firstName>Sebastian</firstName>        <lastName>Schnitzenbaumer</lastName>        <home>????? ?????</home>        <cell>????? ?????</cell>      </phone>

The second instance element is used in performing the search and displaying the search results. The id attribute uniquely identifies this  data instance. 

     <xforms:instance id="ui">        <ui xmlns="ui">          <phone>            <firstName/>            <lastName/>            <home/>            <cell/>          </phone>          <searchField update="true"/>          <viewField id="view"/>        </ui>      </xforms:instance>

Now you will take a look at how individual parts of this data are used on the form (see Figure 3) that is rendered.  The searchField element is used to accept input on the form and is displayed on the form with an input element control. 

     <xforms:input id="sss" ref="ui:searchField">      <xforms:label>Last Name Search:</xforms:label>      </xforms:input>

The layout you see in Figure 3 is created by the input controls as you saw in Tutorial for Example 1. The fields are made read ­only by a  bind on the nodeset and by setting the readonly attribute to true using the true() XPath function. 

     <xforms:bind nodeset="xforms:instance('ui')/ui:phone/*"      readonly="../../ui:searchField/@update = 'true'"/>

The viewField element is used to hold the value from the lastName field of the first data instance in your database that satisfied the search  request. You will look at its use in the next exercise (The Search in Action).  

     <viewField id="view"/>

1. Look at the Instance window and you will see that the model [Default Model] has two DOCUMENT entries, one for each instance.    

2. Click 

 to expand the first DOCUMENT instance. This is the database you will use to search.     

3. Click   to expand the second DOCUMENT instance. This is the user interface instance that holds the search results and is used for  entry of the search value.   

The search in action 
All behavior of this form is performed by the rendering application. Searching the "database," copying the files to the UI, and rendering the  results are all done without making a round trip to an application server. In this example a file is being used (your database), but in a real  application this information could have been extracted from a database and provided to the XForms processor as an XML file. The key point to  remember is that complex user interaction can be specified without using JavaScript or making a request to an application server.   The search field layout is defined in Code 3Code 3. The interesting part of this code is the action with the dispatch of an event to the model.  This action is what will trigger the search to be started and the results to populate the UI instance so that the results can be shown on the  screen. 

<xforms:group class="searchBox" ref="xforms:instance('ui')">   <xforms:input id="sss" ref="ui:searchField">     <xforms:label>Last Name Search:</xforms:label>   </xforms:input>   <xforms:trigger>     <xforms:label>Search</xforms:label>     <xforms:action ev:event="DOMActivate">       <xforms:dispatch name="novell ­update" target="model"/>     </xforms:action>   </xforms:trigger> </xforms:group>

Code 3 Search field and trigger that fire an event that causes the search to be done and populates the UI data instance.  You will examine this code—first by doing a search and seeing the result on the form and in the instance data, and then by looking at how the  search is actually performed. 

Start the search 
1. In the Last Name Search field, enter S and click the Search button.  


The search field is defined as an input element. 

            <xforms:input id="sss" ref="ui:searchField">             <xforms:label>Last Name Search:</xforms:label>             </xforms:input>

The search button is a trigger element. 

            <xforms:trigger>             <xforms:label>Search</xforms:label>              …               </xforms:trigger>  

In the trigger element, there is an action element that will fire an DOMActivate event that will start the ball rolling. See Search and  Populate. 

            <xforms:action ev:event="DOMActivate">              …               </xforms:action>  

In the action element, you see a dispatch element that will dispatch an event in the model as referenced in the target attribute with  the name in the name attribute. 

            <xforms:dispatch name="novell ­update" target="model"/>

2. Click   to expand the second DOCUMENT instance, and keep clicking until you see all the values. The next exercise (Search and  Populate) will discuss the events.  

Search and populate 
When you clicked the Search button, the novell­update event was fired (see Start the Search). This is the event defined in the action element  of the model located in the head element of the XHTML document. 

<xforms:action ev:event="novell ­update">

Now you will examine the code behind the search button in more detail.  The first setvalue element in the list sets (via the ref attribute) the viewField in the UI data instance. This step performs the search based on  last name. 

     <xforms:setvalue      ref="xforms:instance('ui')/ui:viewField"

The viewField is used as the key in the following setvalue elements to retrieve the remaining data. NOTE It will hold the value for only the  first entry found in the "database." Any other entries are not displayed.  In the value attribute, check the value in the lastName field of the default instance (the database). 

     Value = "xforms:instance('default')/phone/lastName[

Check if lastName starts with the value in the searchField. This is done using the XPath function starts­with . 

     starts ­with(  …        ) 

To handle any potential lettercase mismatches, convert the lastName and searchField to all uppercase using the XPath translate function.   Convert to uppercase the lastName. 

     translate( ., 'qwertyuiopasdfghjklzxcvbnm',      'QWERTYUIOPASDFGHJKLZXCVBNM') ,

Convert to uppercase the searchField. 

     translate( xforms:instance('ui')/ui:searchField,      'qwertyuiopasdfghjklzxcvbnm',      'QWERTYUIOPASDFGHJKLZXCVBNM')

The next step is to populate each of the ui instance data elements with the corresponding value from the default instance. The code  example used in the following discussion shows the setvalue element for the firstName (ref attribute) field. All other fields are populated  with similar code. 

     <xforms:setvalue       ref="xforms:instance('ui')/ui:phone/ui:firstName"

The value attribute XPath expression selects the lastName from the database. 

     value= "xforms:instance('default')/phone/lastName[

The viewField is set using the starts­with function. The uppercase test is not needed, because the viewField has the value extracted in the  first setvalue . 

     starts ­with( ., xforms:instance('ui')/ui:viewField)

The firstName value is copied by backing up from your current context (lastName) using XPath. 

     ]/../firstName "

1. Now you will review the result in the Instance window of the Processor application. In the top panel, you see the data values populated  by the action you just reviewed.  2. The events that were fired are shown in the bottom panel.  


Depending on how you interacted with the main window, your index number and number of events in this window may differ. In the  following discussion, only those that pertain to the code of interest are used. The index numbers referenced are the ones in the screen  above.  3. The events 0 ( DOMSubtreeModified ) and 1 ( novell­value­changed ) were fired when you entered a value in the searchField, starting the  entire process.   4. It then followed up by setting the remaining UI data instance from the selected database instance.         5. The result of the first setvalue element updated the viewField.  6. Change the view in the Instance window to Instance root by selecting Instance root from the Models (   ) dropdown list.  

7. Click 

 to expand the DOCUMENT instance, and keep clicking until you see the head and body elements.    

8. Expand the head element, then the model, and then the action element.   

9. Expand the body element and then the last group element. Then expand the trigger, action, and dispatch elements in this element.   

10. Do another search by going to the main window of the Processor application. In the  Last Name Search field enter P, and then click  the Search button.   


11. In the Instance window in the bottom panel, you see lots of events fired—especially as you move the mouse over the window. The ones  that are of interest are shown below.  

12. In the top panel, you see what part of the model in the head and what controls in the body were impacted by the events.   4 ( DOMFocusIn ) is when you first set the focus to the main window of the Processor application.  6 (click) is when you click on the search field  12 – 14 causes the XForms controls and model to recalculate ( xforms­recalculate ), revalidate ( xforms­revalidate ), and refresh  ( xforms­refresh ).  15 ( xforms­value­changed ) is when you entered the value.  16 ( DOMFocusOut ) is when you tab over to the Search button.  17 ( DOMFocusIn ) is when you are on the button.  18 ( DOMActivate ) is when you click the button and get the entire ball rolling.   43 ( DOMFocusOut ) is when you change focus in the application to the Instance window. 

Controlling the presentation 
One last thing to point out is how the presentation was controlled in the application. Notice the border and colors (see Figure 4) around the  search result. The XForms specification allows for the use of a Cascading Style Sheet (CSS) to control the layout and presentation.     

Figure 4 The effect of applying a style sheet for the group form controls that contain the display form controls.  The group element that contains the UI controls has a class attribute defined as " detailBox ". 

     <xforms:group ref="xforms:instance('ui')" class="detailBox">

The value in the class attribute is found in the style sheet referenced by the processing instruction at the beginning of the XHTML  document that contains the form you are using. 

     <?xml ­stylesheet href="search_css.css"?>

Sample of the entries from the style sheet being referenced in the class attributes. You can view the file using your favorite editor (the file is  in the installation directory at Search\search_css.css) . 

     .innerBox {        border ­style: none;      }      .innerBox > input {        border ­style: none;        background ­color: #ffffdd      }      .detailBox {       background ­color: #ffffcc      }      .searchBox {       background ­color: #99cc99      }      .searchBox > input > label {       font ­weight:bold;      }

Notice that the detailBox provides a background color of #ffffcc. 

CSS support in the Processor 
The XForms specification encourages the use of CSS in XForms applications, and the Processor provides support for CSS 2 selectors.   Category  Information  display: inline block none  position: relative, absolute, static, fixed  width, height ,left, top, bottom, right  Supported properties:  margin, margin­left, margin­right, margin­top, margin­bottom  padding, padding­left, padding­right, padding­top, padding­bottom  border, border­style, border­width, border­color (though its currently only possible to have the same border on all  four sides of the component)  background­color, color, font­size, font­weight, font­family, text­align  Supported pseudo  classes:  hover, active, focus, enabled, disabled, invalid, valid, readonly, readwrite, optional, and required. 

The XForms controls and user interface components have the following default properties:   repeat, group, switch, case {display: block;}  submit, button, trigger {border­style: outset; border­width: 3px; padding: 2px 1px}   select, select1, input, secret, textarea {background­color: white; border­style: inset; border­width: 3px; width: 160px;}   textarea {height: 60px;} 

Optional advanced exercise 
1. Open the samples\Search\search_css.css in the installation directory with your favorite text editor and change the background color in  detailBox from #ffffcc to #ffff00 .  2. Save the file.  3. Click the   button on the toolbar. The detail box should now be yellow.     

XForms Web site at W3C   XForms specification   XML Path language (XPath)   Namespaces in XML   XML Schema   XML events  

Extensible Hypertext Markup Language (XHTML)   XSLT and XPath references   XSLT and XPath tutorial   Cascading Style Sheets (CSS)  



edit history    

Create an account or log in   

Updated 2 May 2006  Views 6,650  Legal     


Novell  Making IT Work As One



Contact Us 



© 2009 Novell, Inc. All Rights Reserved.

To top