Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
{{AVMWarning}}
AVM
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.
Table of Contents
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.
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 value='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'>
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)
- /Company Home/Data Dictionary/Web Forms/<form name>/strings.properties
See I18N for more informations about Localization.
Please note that these can be overridden/configured in web-client-application-context.xml by modifying the Schem2XFormsProperties bean.
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.
Using multiple XML Schema to define a single form
The XML schema for a Web Form can include other XML schemas (both static XSD files and dynamically generated XML schemas) by using the standard XML schema xs:include or xs:import constructs and referencing one or more Web Scripts as targets. For instance <xs:include schemaLocation='webscript://path/to/webscript'/> will execute the Web Script associated with path '/path/to/webscript' and include its output into the parent XML schema (the Web Script is required to emit a valid XML Schema as output, for example a series of simpleType and/or complexType definitions).
Examples, including parameters:
<xs:include schemaLocation='webscript://path/to/webscript?storeid={storeid}&ticket={ticket}' />
<xs:import namespace='imported_namespace' schemaLocation='webscript://path/with/the/{storeid}/embedded?ticket={ticket}' />
Notes:
- the path must not include the initial 'service' component of the Web Script's URI ('/alfresco/service' or '/alfresco/wcservice') - this is automatically added by the Web Form functionality.
- the (optional) {storeid} parameter will be replaced with the storeid of the sandbox the Web Form content is being created in - this allows the Web Script to interrogate that sandbox if it's using other WCM content to calculate the resulting XML Schema.
- the (optional) {ticket} parameter will be replaced with the authentication ticket of the user who requested the form. Although this parameter is optional, it is strongly recommended that you always include it in a query string parameter called 'ticket' - this will ensure that the Web Script executes with the same user credentials as the user requesting the Web Form.
This mechanism can also be used to include or import a static XSD file from either the DM or AVM repositories - this is described in detail in this blog post.
Web Project includes (deprecated as of Alfresco v3.0)
Versions of Alfresco prior to v2.2SP3 also supported a 'Web Project include' mechanism, whereby an asset stored in the Web Project could be included or imported directly. For instance <xs:include schemaLocation='/get_reviewers.jsp'/> would execute a jsp called 'get_reviewers.jsp' stored in the root directory of the staging sandbox of the Web Project and include its output (the jsp is required to emit a valid XML Schema as output, just as with Web Script includes). Similarly, this mechanism could also be used to include a static XSD file stored in the Web Project.
This mechanism has proven to be problematic and has been deprecated as of Alfresco v3.0. It will be removed in a future release of Alfresco.
XML Schema support and appearance
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 and attributes have to be required i.e. use='required' | |
| xs:enumeration | generates an xf:select1 | |
| xs:list | generates an xf:select | |
xs attern | 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 |
Supported XML Schema Data Types in Alfresco 2.0 and higher
| XML Schema Datatype | Appearance Parameter | XForms Control | UI Control |
|---|---|---|---|
| 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 | radio button group |
| minimal | xf:select1 | combobox | |
| default | xf:select1 | radio button group or combobox 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 |
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 |
Related Links
Return to WCM Forms Developer Guide
