Forms Authoring Guide
From AlfrescoWiki
XForms are used to render a UI Form capture XML input from the user. The XForms UI is automatically generated from the developer-provided XML schema.
To render the UI to the user, an open source project Chiba is used. It transforms the XML schema into an internal representation of a form (XForms ), and then presents UI controls for elements and attributes described in the schema.
Contents |
[edit] XForm User interface customization
By default, most of XML Schema types have default renderings.
In order to provide customization of the user interface, Alfresco provides the ability to annotate the xml schema with hints to tune certain view parameters of the UI. Localized labels and alert text can be described within these annotations. For most schema types there is a one to one mapping between the type and the UI control. For a few where there are multiple ways to render the same control, an appearance hint can be provided as an annotation.
[edit] Using Schema Annotations
Adding Alfresco-specific annotations in your schema allows you to customize labels, alerts, and the appearance of UI controls in your Web Form.
An example of adding the three supported types of annotations in your schema follows:
<xs:element name="used_by_default_to_generate_a_label" ...>
<xs:annotation>
<xs:appinfo>
<alf:label>override generated label</alf:label>
<alf:alert>
custom alert text (e.g. The value entered for element x is not a
valid email address)
</alf:alert>
<alf:appearance>
generally one of full, compact, or minimal.
As of 2.1, this can map to any appearance name configured
in the xforms section web-client-config-wcm.xml. See below
for file picker examples.
</alf:appearance>
</xs:appinfo>
</xs:annotation>
</xs:element>
When adding any Alfresco-specific annotations, do not forget to declare alf as part of your namespaces. For example:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:alf="http://www.alfresco.org"
elementFormDefault="qualified">
[edit] Form Localization
By default, the label created by the form processor for each element is simply the element's name:
<xs:element name="XXX" type="xs:string"/> <!-- The label for element XXX is "XXX" -->
To localize labels and alerts, you can specify a key in your annotations that will be looked up in one of three properties files locations.
For example, in the following annotation:
<alf:label or alert>Not a localized value</alf:label or alert>
<alf:label or alert>${key_in_property_file}</alf:label or alert>
If the value starts with "${" and ends with "}", the Forms UI will look up "key_in_property_file" in a chain of property files. These default configured property file locations from highest to lowest precedence are:
- /Company Home/Data Dictionary/Web Forms/<form name>/strings.properties
- /Company Home/Data Dictionary/Web Forms/strings.properties
- webclient.properties (within the webapp)
Please note that these can be overridden/configured in web-client-application-context.xml by modifying the Schem2XFormsProperties bean.
[edit] Using one XML Schema to define multiple forms
Because XForms permits specifying schemas with alternative root-level elements, if you take advantage of this feature, the end user must decide which root element they'd like to select (whenever there's a choice). Grouping highly-related schemas into a common XForms .xsd file can sometimes help to organize related data types; however, the appropriateness of this technique depends on both the application and its context.
[edit] Using dynamic types in schemas
Forms can include dynamic types by using the xs:include tag. For instance: <xs:include schemaLocation="/get_reviewers.jsp"/> can be backed by a jsp which produces a simpleType containing a list of users by querying an ldap server. The jsp in this case would be at the root of the webapp in the sandbox where the form instance data is being generated.
[edit] XML Schema support and appearance
[edit] Overview of supported XML Schema structures and data types
There are many structures and data types defined by the XML schema specification. The goal is to cover as much of the spec as possible. However, at this time many concepts are explicitly unsupported or have never been tested. Below is a table describing features that are either explicitly supported or unsupported. Those that have not been tested are omitted and most likely do not work.
| tag | support level | description |
|---|---|---|
| xs:complexType | ||
| xs:simpleType | ||
| xs:sequence | elements within a sequence populate an xf:group | |
| xs:choice | treated as a sequence - should be an xf:switch | |
| xs:all | untested | |
| xs:element | generates an xform control based on the data type | |
| xs:attribute | generates an xform control based on the data type. There are currently issues with multibyte values for attributes. | |
| xs:enumeration | generates an xf:select1 | |
| xs:list | generates an xf:select | |
| xs:pattern | pattern restrictions are enforced on xs:normalizedString types | |
| xs:length | pattern restrictions are enforced on xs:normalizedString, xs:string, and most numerical types. | |
| xs:key | ||
| xs:keyref | ||
| xs:totalDigits | works on decimals, not integers. see WCM-450 for details. | |
| xs:fractionDigits | ||
| xs:maxInclusive, xs:minInclusive, xs:maxExclusive, xs:minExclusive | ||
| xs:string | produces an xf:textarea | |
| xs:normalizedString | produces an xf:input | |
| xs:boolean | produces an xf:select1 rendered as a checkbox | |
| types derived from xs:decimal | produces an xf:input or xf:range if max/min inclusive/exclusive restrictions are defined | |
| xs:date | produces a calendar. selectable range can be restricted using min/max exclusive/inclusive | |
| xs:time | produces a time picker | |
| xs:dateTime | produces a date & time picker. | |
| xs:gDay, xs:gMonth, xs:gYear, xs:gYearMonth, xs:gMonthDay | produces pickers for each type | |
| xs:duration | unsupported by chiba | |
| xs:anyURI | produces a FilePicker | |
| xs:anyType | produces a rich text editor, but xs:string should be used instead | |
| xs:hexBinary, xs:base64Binary | produces an xf:input, but really isn't an appropriate control for this type. | |
| recursive structures | Filed as issue WCM-435 | |
| xs:include, xs:import | Used to include or import a separate XML schema. Relative schemaLocations (eg. "/xsd/CommonTypes.xsd") are resolved relative to the root directory of the Web Project, so the included schema must be stored in the Web Project. Absolute schemaLocations (eg. "http://www.mycompany.com/xsd/CommonTypes.xsd" are loaded directly. Support for including schemas dynamically generated by a Web Script will be added soon - see WCM-555. | |
| xs:any | ||
| xs:Name | unsupported by chiba - can use xs:normalizedString or define a local equivalent (using xs:token as base restriction with pattern value="[_:A-Za-z][-._:A-Za-z0-9]*") | |
| xs:NCName | unsupported by chiba - can use xs:normalizedString or define a local equivalent (using xs:token as base restriction with pattern value = "[_A-Za-z][-._A-Za-z0-9]*") | |
| xs:NMTOKEN | unsupported by chiba - can use xs:normalizedString or define a local equivalent (using xs:token as base restriction with pattern value = "[-._:A-Za-z0-9]+") | |
| default facet | populates the widget with a default value | |
| fixed facet | makes the widget read-only |
[edit] Supported XML Schema Data Types in Alfresco 2.0 and higher
| XML Schema Datatype | Appearance Parameter | XForms Control | UI Control |
|---|---|---|---|
| xs:string | Not supported | xf:input | textfield |
| xs:boolean | Not supported | xf:input | checkbox |
| xs:date | Not supported | xf:input | date picker |
| xs:integer | Not supported | xf:input | textfield |
| xs:double | Not supported | xf:input | textfield |
| xs:decimal | Not supported | xf:input | textfield |
| xs:float | Not supported | xf:input | textfield |
| xs:anyType | Not supported | xf:textarea | WYSIWYG editor |
| xs:complexType | Not supported | xf:group | group with header |
| xs:anyURI | Not supported | xf:upload | file picker |
| any type with maxOccurs > 1 | Not supported | xf:repeat | repeat |
| xs:anyType | Not supported | xf:textarea | rich text editor |
| xs:string | full | xf:textarea | rich text editor |
| minimal | xf:textarea | textarea | |
| xs:normalizedString | Not supported | xf:input | textfield |
| xs:time | Not supported | xf:input | time picker |
| xs:gDay | Not supported | xf:input | day picker |
| xs:gMonth | Not supported | xf:input | month picker |
| xs:gYear | Not supported | xf:input | year picker |
| xs:gYearMonth | Not supported | xf:input | year-month picker |
| xs:gMonthDay | Not supported | xf:input | month-day picker |
| xs:dateTime | Not supported | xf:input | textfield |
| xs:integer (w/inclusive bounds) | Not supported | xf:range | slider |
| xs:double (w/inclusive bounds) | Not supported | xf:range | slider |
| xs:decimal (w/inclusive bounds) | Not supported | xf:range | slider |
| xs:float (w/inclusive bounds) | Not supported | xf:range | slider |
| xs:list | full | xf:select | checkboxes |
| minimal | xf:select | multi-select list | |
| default | xf:select | checkbox or multi-select based on list length | |
| xs:enumeration | full | xf:select1 | combobox |
| minimal | xf:select1 | radio button group | |
| default | xf:select1 | combobox or radio button based on list length | |
| xs:anyURI | full | xf:upload | file picker |
| minimal | xf:upload | textfield | |
| xs:complexContent with Base | Not supported | xf:switch | switch group |
[edit] Additional features as of Alfresco 2.1
The following additional appearance annotations can now be used to specify the presentation of the form:
| XML Schema Datatype | Appearance Parameter | XForms Control | UI Control |
|---|---|---|---|
| xs:string | full | xf:textarea | rich text editor |
| default | xf:textarea | rich text editor with minimal controls | |
| minimal | xf:textarea | textarea | |
| xs:complexType | minimal | xf:group | group with horizontal layout |
| default | xf:group | group with vertical layout | |
| xs:anyURI | configurable | xf:upload | a file picker with filters defined in configuration |
Return to Forms Developer Guide
