WCM Forms Authoring Guide

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com


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.

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' ...>
        <alf:label>override generated label</alf:label>
          custom alert text (e.g. The value entered for element x is not a
          valid email address)
          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.

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'

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)

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}' />


  • 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: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: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:totalDigits works on decimals, not integers. see WCM-450 for details.
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: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