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.
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.
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'>
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:
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.
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.
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:
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.
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.
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 | |
xsattern | 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 |
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 |
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 WCM Forms Developer Guide
Ask for and offer help to other Alfresco Content Services Users and members of the Alfresco team.
Related links:
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.