 |
|
XPE Forms GUI elements
Description
XPE Forms has many elements to define all commonly used GUI widgets expected of an advanced forms engine.
Here is an example of a simple but complete XPE form definition. The documentation that follows will explain the use and purpose of the XPE form elements illustrated in the example.
<xf:form method="POST" action="http://localhost:8888/xpe/ws/register" onSuccess="http://localhost:8188/xpe/site/index" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
<xf:schema name="http://example.com/authentication.xsd" src="http://localhost:8188/xpe/test/xsd/authentication.xsd" reload="true" />
<xf:instance schema="http://example.com/authentication.xsd" >
<registration xmlns="" >
<username>
username
</username>
<password>
password
</password>
<email>
abc@def.com
</email>
<cc>
visa
</cc>
</registration>
</xf:instance>
<xf:group display="Registration" >
<xf:field required="yes" size="20" maxlength="50" ui="input" ref="registration/username" display="Username" type="xs:string" >
<xf:hint>
upto 20 characters
</xf:hint>
<xf:help>
Please enter your registered username. (upto 50 alphanumeric characters)
</xf:help>
</xf:field>
<xf:field required="yes" size="20" maxlength="20" ui="password" ref="registration/password" display="Password" >
<xf:hint>
5 to 20 alphanumeric characters
</xf:hint>
<xf:help>
Please enter your password (5 to 20 alphanumeric characters).
</xf:help>
</xf:field>
<xf:field required="no" size="1" maxlength="20" qa:type="xs:string" xmlns:qa="http://www.xml.org/pipe/xpe/xs/simple" display="CC" ui="dropdown" ref="registration/cc" >
<xf:option value="Visa" />
<xf:option value="American Express" />
<xf:option value="Mastercard" />
</xf:field>
<xf:repeat nodeset="registration/email" >
<xf:field required="no" size="25" maxlength="25" qa:type="xs:string" xmlns:qa="http://www.xml.org/pipe/xpe/xs/simple" ui="input" ref="text()" display="Email" />
</xf:repeat>
<xf:group render="sameline" >
<xf:trigger name="action:insert" value="registration/email" >
Button
</xf:trigger>
<xf:trigger name="action:delete" value="registration/email" >
Remove Email
</xf:trigger>
</xf:group>
</xf:group>
<xf:submit display="Logon" withReset="yes" />
</xf:form>
The following describes all the currently defined widgets.
xf:field
The xf:field element is the most common forms element. It provides the basis for most of the input fields used within XPE forms.
Attributes
| Attribute name | Description |
| required | Marks the field as either a mandatory field required="yes" or an optional field required="no". If omitted, the default value is required="no" |
| size | Specifies the size (length) of the displayed field in character positions.
size="25"
The meaning of this attribute depends on the type of field specified by the ui attribute. If the ui is the normal input type, then the size is the length
of the input field. If the ui is "dropdown" then the size should be set to 1.
|
| maxlength | Specifies the maximum number of characters to be accepted.
maxlength="25"
|
| ui | Specifies the type of field to create and display. valid values are:
|
| qa:type | Specifies the data type allowable within the field. This attribute has its own namespace xmlns:qa="http://www.xml.org/pipe/xpe/xs/simple". Allowable values are any acceptable W3C XSD Schema types. This is an optional attribute. qa:type="xs:string" |
| ref | Specifies the element in the instance data that corresponds to this form field. This can be any xpath expression. When the form is initially rendered, the value from the instance data element (or attribute) is used to populate the forms field. When the form is submitted, the value in the field is copied back to the identified instance ref="authentication/password" |
| display | Specifies the label to place with the field. This is an optional attribute. display="Credit Card Type" |
The illustrated form example has a number of simple fields defined. The username field:
<xf:field required="yes" size="20" maxlength="50" ui="input" ref="registration/username" display="Username" type="xs:string" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
...
</xf:field>
- takes its initial value from the registration/username instance data element: ref="registration/username"
- has a display field width of 20: size="20"
- will allow a maximum of 50 characters to be entered: maxlength="50"
- is mandatory: required="yes"
- has a label of Username: display="Username"
- will accept a string datatype value: type="xs:string"
The password ui="password" field:
<xf:field required="yes" size="20" maxlength="20" ui="password" ref="registration/password" display="Password" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
...
</xf:field>
xf:option
This element is used to specify the possible options available to a dropdown field. It must be a child element of a dropdown field.
Attributes
| Attribute name | Description |
| value | Specifies the option value to be displayed within the dropdown field.
|
<xf:field required="no" size="1" maxlength="20" qa:type="xs:string" xmlns:qa="http://www.xml.org/pipe/xpe/xs/simple" display="CC" ui="dropdown" ref="authentication/cc" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
<xf:option value="Visa" />
<xf:option value="Amex" />
<xf:option value="MasterCard" />
<xf:option value="SharkCard" />
</xf:field>
xf:display
This contents of this element is used to provide a legend to a group of related fields.
xf:group element
The xf:group element is used (as you may guess) to group related fields together.
Attributes
| Attribute name | Description |
| display | Specifies a label to be displayed with the grouped fields.
|
<xf:group display="Registration" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
<xf:field required="yes" size="20" maxlength="50" ui="input" ref="registration/username" display="Username" type="xs:string" >
<xf:hint>
upto 20 characters
</xf:hint>
<xf:help>
Please enter your registered username. (upto 50 alphanumeric characters)
</xf:help>
</xf:field>
<xf:field required="yes" size="20" maxlength="20" ui="password" ref="registration/password" display="Password" >
<xf:hint>
5 to 20 alphanumeric characters
</xf:hint>
<xf:help>
Please enter your password (5 to 20 alphanumeric characters).
</xf:help>
</xf:field>
...
</xf:group>
xf:repeat
The repeat element allows repeating data items to be added and deleted dynamically within the XPE forms engine.
When the form is submitted, the instance fragment will contain the repeated data items in the element referenced by the ref attribute of the form field.
For example, assuming the form defined by the example at the top of this page is displayed as:
If the Add Email button is pressed, then the XPE Forms engine will add a new Email
row to the displayed form:
Each press of the Add Email button will add a further row to the form.
If the Remove Email button is then pressed, then the XPE forms engine will remove the last Email row from the displayed form.
Eventually when the form is submitted, the displayed data is copied to the instance data. For example, if the form is displayed as:
Then the instance element submitted would be:
<registration xmlns="" >
<username>
username
</username>
<password>
password
</password>
<email>
email1@isp.com
</email>
<email>
fred@bedrock.com.br
</email>
<cc>
visa
</cc>
</registration>
The repeat element can be used to construct arbitrarily complex repeating groups of data. Multiple input fields within a repeat group are simply created within the group with each input field referencing a specific instance data element. For example if our instance data looked like:
<xf:instance schema="http://example.com/authentication.xsd" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
<registration xmlns="" >
<username>
username
</username>
<password>
password
</password>
<contact>
<email>
abc@def.com
</email>
<phone>
1111
</phone>
</contact>
<contact>
<email>
abc1@def.com
</email>
<phone>
2222
</phone>
</contact>
<cc>
visa
</cc>
</registration>
</xf:instance>
And our form definition contained:
<xf:form method="POST" action="http://localhost:8888/xpe/ws/register" onSuccess="http://localhost:8188/xpe/site/index" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
...
<xf:repeat nodeset="authentication/contact" >
<xf:group display="Contact Details" >
<xf:field required="no" size="25" maxlength="25" qa:type="xs:string" xmlns:qa="http://www.xml.org/pipe/xpe/xs/simple" ui="input" ref="email" display="Email" />
<xf:field required="no" size="25" maxlength="25" qa:type="xs:string" xmlns:qa="http://www.xml.org/pipe/xpe/xs/simple" ui="input" ref="phone" display="Phone" />
</xf:group>
</xf:repeat>
<xf:group render="sameline" >
<xf:trigger name="action:insert" value="registration/contact" >
Add Contact
</xf:trigger>
<xf:trigger name="action:delete" value="registration/contact" >
Remove Contact
</xf:trigger>
</xf:group>
</xf:form>
Then our displayed form would contain a repeating group consisting of repeating sets of email and phone fields:
Nested repeat groups are created simply by (as expected) nesting one group within another.
xf:trigger
The trigger element is used to define a form widget used to generate various events. The most common event being a button press event that can then be used to trigger a form action of some kind. There are a few such form actions that can be defined within XPE Forms.
Attributes
| Attribute name | Description |
| name | Identifies a trigger action
|
| value | if name is action:insert or action:delete then value
identifies the instance data element to be acted upon by the trigger (xpath expression).
|
The possible actions are:
- action:insert: Used to add an item to a repeating form field.
- action:delete: Used to delete an item from a repeating form field.
<xf:group render="sameline" xmlns:xf="http://www.xmlpipe.org/xpe/form" >
<xf:trigger name="action:insert" value="registration/email" >
Button
</xf:trigger>
<xf:trigger name="action:delete" value="registration/email" >
Remove Email
</xf:trigger>
</xf:group>
xf:submit
The xf:submit creates the controls that allow the form to be submitted to a business pipeline (defined as the action pipeline in the xf:form action attribute).
The form will only be submitted once it passes all level of defined validations.
Attributes
| Attribute name | Description |
| display | Specifies a label for the submit button.
|
| withReset | If set to "yes" XPE Forms will create a second button allowing the form data fields to
be reset to their initial values. If set to "no" (the default) no reset button will be created.
|
If our form definition includes:
<xf:submit display="Register" withReset="yes" xmlns:xf="http://www.xmlpipe.org/xpe/form" />
Then the following buttons will be created to reset and submit the form:
