WCM Forms Developer Guide

[resplin]

Obsolete Pages{{Obsolete}}

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

{{AVMWarning}}
AVM
Back to WCM Developer Documentation

Table of Contents

• 1 Overview


• 2 Forms Development Process Overview


• 3 Forms Development Steps
  
  
  
  • 3.1 WCM Forms
  
  
  • 3.2 ECM Forms
  
  
  • 3.3 Form Processing and Rendering Extensibility
  
  


• 4 Terminology


• 5 Form Deployment Configuration
  
  
  
  • 5.1 Output Path Patterns (Web Forms only)
  
  
  • 5.2 Output Path Pattern Examples
  
  
  • 5.3 Accessing Web Forms from a virtualized Alfresco web application
  
  


• 6 Other Forms Resources

Overview

Forms are used to capture content from the user, store it as XML in Alfresco at a certain path.  For capturing content, an XML Schema needs to be created by developer.  It is then rendered automatically using a user-friendly Web Form (using XForms technology embedded in Alfresco).  

Web Forms are created and administered within the 'Web Forms' space within the Data Dictionary.  DM (ECM) Forms are created and administered within the 'Forms' space within the Data Dictionary.

The content contributor will have as few decisions to make as possible when creating content; the majority of the process is automated and configured in advance.  A Form is configured by specifying an XML schema to be used by the Form Processor to generate the UI and manage the collected form instance data. 

In the case of Web Forms, these can also be configured with rendering engine templates to be used for generating renditions of the collected content.  In addition, a default workflow is defined for managing the process by which form instance data and renditions generated by the form are submitted to the staging sandbox.

Forms Development Process Overview

Forms are used to capture content from the user, store it as XML in Alfresco at a certain path.  For capturing content, an XML Schema needs to be created by developer.  It is then rendered automatically using a user-friendly Web Form (using XForms technology embedded in Alfresco).  

While Alfresco has default form renderings for all types (string, date, etc), it is possible to extend Alfresco and write your own WCM Forms Widgets.  An example of why you might want to do that is if you want to create a widget that automatically does automatic suggestions based on an internal data source.   The Web Forms can be extended by writing custom WCM Widgets.

When the user is done authoring the Web Form, the resultant XML documents are stored at a pre-specified path. 

After the data is captured, it can be 'rendered' in different ways (e.g.: as HTML, PDF, etc.).

Forms Development Steps

1. Create XML schema (XSD files) to represent web content types.  Please see WCM Forms Authoring Guide page for more information.
   
2. Add XSD schema to Web Forms or Forms space in Data Dictionary
   
   • (WCM Forms) Configure output paths
     
3.   (Optional) XForms UI Customization.  Please see Configuring XForms Widgets for more information.
   
   • Create Custom XForms Widgets for customized data input.  Please see Creating XForms Widgets.
     
   • Customize the way XForms are rendered in configuration files.
     

After the data is captured as XML, you can either have your site framework read it from alfresco and perform its own rendering, or you can use Alfresco for rendering.

If you decide to use Alfresco for rendering your content (or generating static HTML or HTML fragments), you have two additional steps: 

1. Develop Rendering Templates in FreeMarker or XSL.  Please see WCM Forms Rendering Page.
   
2. Configure Rendering Templates
   

Alfresco now supports forms both in WCM (Web Content Management) and ECM (Enterprise Content Management). Let's examine the terms defined below.

WCM Forms

WCM Forms, also known as 'Web Forms', have been available since Alfresco 2.0. These allow structured XML content to be created based on an XML schema (XSD). They also allow multiple renditions to be generated, by configuring one or more template and associated rendering engines.

For a quick tutorial, refer to WCM Forms Quick Tutorial. For a step-by-step tutorial, download the latest WCM Product Evaluation Guide from sourceforge.

ECM Forms

ECM Forms, also known as 'DM Forms' or simply 'Forms', are now available in Alfresco 2.9 Community Labs release for testing and evaluation. These allow structured XML content to be created based on an XML schema (XSD). Unlike 'Web Forms', they do not directly support renditions although Content Transformations can be used to achieve similar results.

Refer to ECM Forms for basic steps to define and use a form.

Form Processing and Rendering Extensibility

Alfresco ships with a single form processor and two different rendering engines.  The form processor isn't pluggable yet; however, the two bundled rendering engines can co-exist (and more might be added later).  Meta information is associated with renditions so the Alfresco web application's  'edit' functionality is intelligent:  editing a rendition is interpreted as opening  its associated form user interface, pre-populated with the form instance data used to create the rendition.  When editing form instance data, on saving the changes Alfresco will automatically regenerate renditions.  If the form definition is changed then it is also possible to explicitly choose to regenerate renditions by invoking the associated wizard.

Terminology

Form: A user defined unit which defines a method for collecting user input, serializing it into an xml representation, and then generating renditions based on the xml representation.  More specifically, a form is configured with the following parameters:

• an xml schema describing the xml content to be collected
  
• a set of rendering engine templates to use for generating renditions of the xml content collected
  
• a set of output path patterns to use when writing form instance data and renditions to the repository
  
• the workflow definition to use when form generated content is being submitted.
  

Form User Interface: The interactive graphical user interface corresponding to a form  (e.g.: HTML + JavaScript, as displayed by a web browser).

Form Processor: A program that takes a form, produces a form user interface, captures form instance data, and then persists it.  Currently, the form processor takes a lightly annotated XML schema (XSD) and transforms it into an XForms form. The persisted data is valid XML with respect to its defining XSD.

Form Instance Data: Data captured by a form processor (e.g.: XML).

Rendering Engine: A program that uses a rendering engine template in conjunction with optional form instance data to produce a rendition. Xalan and FreeMarker are two different rendering engines.

Rendering Engine Template:  A file whose contents govern what an associated rendering engine emits.  For example, .xsl and .ftl files are Rendering engine Templates for the XSL and FreeMarker rendering engines (respectively).  A rendering engine template may contain programmatic instructions, references to form instance data,  and/or in-line data.

Rendition: The output of a rendering engine, when given a rendering engine template and (optionally) form instance data as input.  Note that different renditions of what is fundamentally the same information can vary by I18N encoding (e.g.:  UTF-8, ISO-8859-1), localization, file format type (e.g.:  HTML, PDF), pagination, printer-friendly markup, etc.

XForms controls: An abstract data-collection 'widget' specified by the XForms Working Group.  The XForms form processor maps XForms schema types into XForms controls.

Form User Interface Generator:  A program or library used by the form processor in order to map abstract data collection 'widgets' (for example, XForms Controls) into something concrete and usable, such as HTML text fields, combo boxes, radio buttons, etc.   Although this is not currently supported, future releases of Alfresco will allow this to be 'skinned' by CSS on a per-form basis to produce the final Form user Interface (assuming an HTML interface is being generated).

Form Deployment Configuration

When content is created based on a form, Alfresco needs to know where to store the resultant files.  Each form has ability to set output paths for the resultant files.

Output Path Patterns (Web Forms only)

Output path patterns are used to define where web form instance data and renditions are saved in the repository.  They are intended to be used for enforcing the structure of the web project.  Output Path Patterns are FreeMarker expressions that are evaluated once the contributor has entered in the form instance data and the content and renditions are ready to be saved.  Below are the variables available to these expressions and some examples.

name: The name of the form instance data as specified by the user when creating the form instance data.  The default output path pattern for form instance data is ${name}.xml and the default output path pattern for renditions is ${name}.${extension}.

extension: The corresponding extension for the mime type specified by the rendering engine template.  This variable only applies to output path patterns for renditions since it's assumed that the extension for form instance data will always be xml.

webapp: The name of the webapp folder in which the content is being created.  This variable is important when building output paths that are not relative to the location in which the content is being created.

cwd: The current working directory when the content is being created.  This is a web application relative path.  The output path pattern ${name}.${extension} which will save content into the directory relative to where content is being generated is equivalent to the output path pattern /${webapp}/${cwd}/${name}.${extension}.

date: A FreeMarker date object.  An output path pattern ${name}-${date?string('MM')}.${extension} will extract the current month from the date and append it to the file name.

node: This variable only applies to rendition output path patterns.  This will provide a reference to the node object for the form instance data which can be used for extracting properties from the node.  For instance /${webapp}/${node.author}/${name}.${extension} will categorize renditions based on the author of the form instance data.

xml: This variable provides a FreeMarker node corresponding to the root of the form instance data entered by the user.  For a full reference of how to work with xml in FreeMarker, please refer to the XML Processing Guide.  The following are important caveats when processing XML using FreeMarker:

• All namespaces are automatically made available to the output path pattern.  A <#ftl ns_prefixes={...}> declaration is auto generated and prepended to the output path pattern.
  
• When xml node names contain non java safe characters, the XPath notation must be used in place of bean notation.
  

Output Path Pattern Examples

parameter values used in these examples

name	value
name	foo
extension	html
webapp	ROOT
cwd	/d1/d2
date	Sat Sep 01 2007 13:33:59 GMT-0700 (PDT)
xml	<root_tag xmlns:myns='http://www.myns.org/myns>   <name>bar</name>   <date>1776-07-04</date>   <node-name-with-dash>moo</node-name-with-dash>   <myns:namespaced>cow</myns:namespaced> </root_tag>

examples

output path pattern	output path
${name}.xml	/ROOT/d1/d2/foo.xml
${name}.${extension}	/ROOT/d1/d2/foo.html
/${name}.${extension}	/foo.html
/${webapp}/renditions/${name}.${extension}	/ROOT/renditions/foo.html
/${webapp}/renditions/${date?string('MM')}/${name}.${extension}	/ROOT/renditions/09/foo.html
/${webapp}/renditions/${date?string('yyyy')}/${cwd}/${name}.${extension}	/ROOT/renditions/2007/d1/d2/foo.html
${xml.root_tag.name}.xml	/ROOT/d1/d2/bar.xml
${xml['root_tag/name']}.xml	/ROOT/d1/d2/bar.xml
/${webapp}/${xml.root_tag.date?date('yyyy-MM-dd')?string('yyyy')}/${name}.xml	/ROOT/1776/foo.xml
${xml['root_tag/node-name-with-dash']}.xml	/ROOT/d1/d2/moo.xml
${xml['root_tag/myns:namespaced']}.xml	/ROOT/d1/d2/cow.xml

Accessing Web Forms from a virtualized Alfresco web application

See the Alfresco demo website for details on how to use
ServletContextFormDataFunctionsAdapter,  parseXMLDocument, and parseXMLDocuments  (particularly, look at the comments within the jsp files).

Other Forms Resources

These are linked to above already, this is another set of related links. 

• WCM Forms Authoring Guide
  
• Creating XForms Widgets
  
• WCM Forms Rendering
  
• Configuring XForms Widgets