WCM Forms Authoring Guide

[resplin]

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

• 1 XForm User interface customization
  
  
  
  • 1.1 Using Schema Annotations
  
  
  • 1.2 Form Localization
  
  


• 2 Using one XML Schema to define multiple forms


• 3 Using multiple XML Schema to define a single form
  
  
  
  • 3.1 Web Project includes (deprecated as of Alfresco v3.0)
  
  


• 4 XML Schema support and appearance
  
  
  
  • 4.1 Overview of supported XML Schema structures and data types
  
  
  • 4.2 Supported XML Schema Data Types in Alfresco 2.0 and higher
  
  
  • 4.3 Additional features as of Alfresco 2.1
  
  


• 5 Related Links

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)
  

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
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

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

• Learning Alfresco Web Forms by Examples (Part 1) | Dr. Q’s Workshop
  

---

Return to WCM Forms Developer Guide