3.2 Forms

resplin · ‎6 Jun 2015

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

NOTE: This document details the Forms Engine for Alfresco 3.2, for the latest documentation click here.

The Changes section outlines the modifications applied between the 3.2 Community Release and 3.2 Enterprise Release.

Introduction

The Alfresco web client presents 'forms' (data view & entry dialogs) throughout its user interface (DM & WCM). In v2.X, these 'forms' are implemented in multiple ways, from hand-coding JSF to declaring an XSD.

The v3 web client is being built on a web framework that is designed to enable the development of all kinds of web sites (by the wider community). Forms play an important part of web sites and as such the framework needs to provide a convention for implementing them.

The Forms architecture in v3.2 onwards replaces the monolithic and duplicated approach of the JSF property sheet component and xforms.js in v2.X. The same services will be used for both DM and WCM forms, meaning there will be only one configuration syntax and one set of UI controls.

Where Are Forms Used?

At the time of writing the only place the new Forms Engine is used is for the View and Edit Metadata pages within the Share client.

A screenshot of the form component in use on the Edit Metadata page is shown below.

Field labels on top.png

As the contents of the form is completely driven from configuration custom types, custom aspects, their properties and their associations can be displayed within Share without a single line of code.

In the future the Forms Engine will be used for all forms in the Share client, the Records Management module and will be heavily used by the Web Studio application.

How Do Forms Work?

The Forms Engine consists of 4 major parts, the Form Service, the Form Component, Form Configuration and the JavaScript FormUI component which includes the Forms Runtime.

Architecture

The diagram below shows a high level architecture diagram of the Forms Engine.

High Level Forms Architecture.png

Event Sequence

When a request is made to a page containing the Form Component the following sequence of events occur.

The Form Component looks up the Form Configuration for the item being requested.
The Form Component retrieves the list of fields to display (if any) and requests a form definition for those fields and the item from the Form Service via it's REST API.
The Form Service looks for a FormProcessor that can process the kind of item.
The Form Processor is asked to generate a form definition.
The Form Processor executes any registered Filters before and after the main processing.
The REST API takes the result from the Form Processor/Form Service and constructs the form definition JSON response.
The Form Component receives the result from the Form Service and combines it with the Form Configuration to produce the form UI model.
The Form Component's Freemarker template iterates around the fields and includes the relevant controls.
The Form Component's Freemarker template instantiates the FormUI JavaScript component.
The FormUI JavaScript instantiates the Forms Runtime and registers all validation handlers.

At this point the form is ready for the user to interact with, as they do the Forms Runtime constantly checks the validation rules enabling and disabling the submit button appropriately. When the user submits the form the following sequence of events occur.

The browser submits the form by calling the REST API
The Form Service looks for a FormProcessor that can process the kind of item.
The Form Processor is asked to persist the form data.
The Form Processor executes any registered Filters before and after the main processing.
The REST API takes the result from the Form Processor/Form Service and constructs the JSON response.
The browser receives the response and processes it appropriately.

Controls

Controls are represented by a Freemarker template snippet, each field has a control and an optional set of parameters.

The controls available out-of-the-box are described below.

association.ftl

The association control is used to allow objects in the repository to be picked and ultimately associated with the node being edited. The control uses the JavaScript Alfresco.ObjectPicker component to allow the user to browse the repository and pick objects.

Parameters:

- compactMode: Determines whether the picker will be shown in compact mode

- showTargetLink: Determines whether a link to the document details page will be rendered to content items

category.ftl

The category control is used to allow the user to select categories for the node being edited. The control uses the JavaScript Alfresco.ObjectPicker component to allow the user to browse the category hierarchy

Parameters:

- compactMode: Determines whether the picker will be shown in compact mode

checkbox.ftl

The checkbox control renders a standard HTML checkbox control.

Parameters:

- styleClass: Allows a custom CSS class to be applied to the checkbox

date.ftl

The date control renders a date field allowing free form entry of dates as well as a calendar widget allowing dates to be selected visually. If appropriate a time field is also rendered.

Parameters:

- showTime: Determines whether the time entry field should be displayed

encoding.ftl

The encoding control renders a selectable list of encodings.

Parameters:

- property: The name of a content property to retrieve the current encoding from, if omitted the field.value value is used

- styleClass: Allows a custom CSS class to be applied to the select list

invisible.ftl

The invisible control literally renders nothing at all, it can be used when a form definition needs to be requested and returned but not displayed. This control has no parameters.

mimetype.ftl

The mimetype control renders a selectable list of mimetypes.

Parameters:

- property: The name of a content property to retrieve the current mimetype from, if omitted the field.value value is used

- styleClass: Allows a custom CSS class to be applied to the select list

period.ftl

The period control renders a selectable list of periods and an expression entry field. This control has no public parameters.

selectone.ftl

The selectone control renders a standard HTML select list.

Parameters:

- options: A comma separated list of options to display, for example 'First,Second,Third'. If a value for an option also needs to be specified the 'First|1,Second|2,Third|3' format can be used.

- size: The size of the list i.e. how many options are always visible

- styleClass: Allows a custom CSS class to be applied to the select list

selectmany.ftl

The selectmany control renders a standard HTML select list allowing multiple selections.

Parameters:

- options: A comma separated list of options to display, for example 'First,Second,Third'. If a value for an option also needs to be specified the 'First|1,Second|2,Third|3' format can be used.

- size: The size of the list i.e. how many options are always visible, the default is 5.

- styleClass: Allows a custom CSS class to be applied to the select list

size.ftl

The size control renders a read only human readable representation of the content size.

Parameters:

- property: The name of a content property to retrieve the current content size from, if omitted the field.value value is used

textarea.ftl

The textarea control renders a standard HTML textarea field.

Parameters:

- rows: The number of rows the textarea will have

- columns: The number of columns the textarea will have

- styleClass: Allows a custom CSS class to be applied to the textarea

textfield.ftl

The textfield control renders a standard HTML text field.

Parameters:

- styleClass: Allows a custom CSS class to be applied to the text field

- maxLength: Defines the maximum number of characters the user can enter

- size: Defines the size of of the text field

Configuring Forms

Although backwards compatibility is ideal, there are some features required, such as control configuration and grouping of fields, that are not compatible with the existing property sheet configuration objects. Additionally, a few of the attributes used in the JSF client don't apply to Surf-based applications. As a result, a new schema has been defined for forms.

The existing configuration service is used so anyone used to property sheet configuration in v2.x should already be familiar with the new configuration syntax shown below.


<config>
   <forms>
      <default-controls>
         <type name='type' template='path'>
            <control-param name='name'>value</control-param>
         </type>
      </default-controls>

      <constraint-handlers>
         <constraint type='id' validation-handler='function' [message-id='key'] [message='string'] [event='string'] />
      </constraint-handlers>

      <dependencies>
         <js src='path' />
         <css src='path' />
      </dependencies>
   </forms>
</config>

<config evaluator='node-type' condition='type'>
   <forms>
      <form [id='string'] [submission-url='url']>
         <view-form template='path' />
         <edit-form template='path' />
         <create-form template='path' />
         <field-visibility>
            <show id='string' [for-mode='view|edit|create'] [force='boolean'] />
            <hide id='string' [for-mode='view|edit|create'] />
         </field-visibility>
         <appearance>
            <set id='string' appearance='fieldset|panel' [parent='string'] [label='string'] [label-id='key'] [template='path'] />

            <field id='string' [label-id='key'] [label='string'] [description-id='key'] [description='string']
                        [read-only='boolean'] [mandatory='boolean'] [set='string']>
               <control [template='path']>
                  <control-param name='name'>value</control-param>
               </control>
               <constraint-handlers>
                  <constraint type='id' validation-handler='function' [message-id='string'] [message='string'] [event='string'] />
               </constraint-handlers>
            </field>
         </appearance>
      </form>
   </forms>
</config>

The default Forms configuration can be found in the file named 'web-framework-config-commons.xml' which can be found in the WEB-INF/classes/alfresco folder when deployed in an appserver. The source file can be found in the root/projects/web-framework-commons/config/alfresco folder. This file contains all the default controls and constraint handlers for the Alfresco content model and the form configuration for the 'cm:content' and 'cm:folder' types. An example of configuring the 'cm:content' type can also be found here.

Form configuration customizations should be supplied in a file named either 'web-framework-config-custom.xml', 'webscript-framework-config-custom.xml' or 'share-config-custom.xml' if the Share application is being used, the file needs to be placed in the 'alfresco.web-extension' package, which in Tomcat will be the tomcat-home/shared/classes/alfresco/web-extension folder.

Each part of the XML configuration syntax is described in detail below.

default-controls

The type element defines what control to use by default for each type defined in the Alfresco content model. The name attribute contains the prefix form of the data type for example 'd:text'. The template attribute specifies the absolute path to the template snippet to use to represent the field. The control-param element provides a mechanism to pass parameters to control templates, meaning that control templates can be re-used.

constraint-handlers

The constraint element defines what JavaScript function to use to check that fields with constraints are valid before being submitted. The id attribute is the unique id given to the model constraint in the Alfresco content model, for example 'LIST'. The validation-handler attribute represents the name of a JavaScript function that gets called when the field value needs to be validated. The event attribute defines what event will cause the validation handler to get called, this will be a standard DOM event i.e. 'keyup', 'blur' etc. The validation handler called usually has a default message to display when validation fails, the message and message-id attributes provide a way to override this message, please note however, these are for future use as validation messages are not shown currently (the submit button gets enabled/disabled).

dependencies

The dependencies element defines the list of JavaScript and CSS files required by any custom controls being used in the application. In order for valid XHTML code to be generated the dependencies need to be known ahead of time so the relevant links can be generated in the HTML head section.

The src attribute of both the js and css elements contains the path to the resource, the path should be an absolute path from the root of the web application (but not including the web application context).

form

The form element, as the name would suggest, represents a form to display. If the form element exists within a config element that provides an evaluator and condition the form will only be found if the item being requested matches the condition. If the form element exists within a config element without an evaluator and condition the form is always found.

The optional id attribute allows an identifier to be associated with the form, thus allowing multiple forms to be defined for the same item. The submission-url allows the action attribute of the generated form to be overridden so that the contents of the form can be submitted to any arbitrary URL.

view-form

The view-form element allows the default template that auto generates the form UI to be overridden. The template attribute specifies the absolute path to the template to be used when the form is in 'view' mode. If this element is present the field-visibility element is effectively ignored and therefore does not have to be present.

edit-form

The edit-form element allows the default template that auto generates the form UI to be overridden. The template attribute specifies the absolute path to the template to be used when the form is in 'edit' mode. If this element is present the field-visibility element is effectively ignored and therefore does not have to be present.

create-form

The create-form element allows the default template that auto generates the form UI to be overridden. The template attribute specifies the absolute path to the template to be used when the form is in 'create' mode. If this element is present the field-visibility element is effectively ignored and therefore does not have to be present.

field-visibility

The field-visibility element defines which fields are going to appear on the form, unless a custom template is used as explained above.

show

The show element specifies a field that should appear on the form. The id attribute represents the unique identifier for a field, for example 'cm:name'. The optional for-mode attribute indicates when the field should appear, valid values for the attribute are 'view', 'edit' and 'create'. If the attribute is not specified the field will appear in all modes, if present the field will only appear for the modes listed, for example to only show a field in view and edit modes the for-mode attribute would contain 'view,edit'.

There are fields that may be optional for an item, by default they may not be returned by the server, the force attribute can be used to indicate to the FormService that it should do everything it can to find and return a definition for the field. An example might be a property defined on an aspect, if the aspect is not applied to the node a field definition for the property will not be returned, if force is 'true' it would indicate that server needs to try and find the property on an aspect in the content model.

hide

The hide element normally comes into play when multiple configuration files are combined as it can be used to hide fields previously configured to be shown. The id attribute represents the unique identifier for a field, for example 'cm:name' that should not be displayed. The optional for-mode attribute indicates in which modes the field should not appear, valid values for the attribute are 'view', 'edit' and 'create'. If the attribute is not specified the field will never appear, if present the field will be hidden for the modes listed, for example to hide a field in view and edit modes the for-mode attribute would contain 'view,edit'.

The algorithm for determining whether a particular field will be shown or hidden works as follows

If there is no field-visibility configuration (show or hide tags) then all fields are visible in all modes.
If there are one or more hide tags then the specified field(s) will be hidden in the specified modes. All other fields remain visible as before.
However, as soon as a single show tag appears in the config xml, this is taken as a signal that all field visibility is to be manually configured. At that point, all fields default to hidden and only those explicitly configured to be shown (with a show tag) will actually be shown.
Show and hide rules will be applied in sequence with later rules potentially invalidating previous rules.
Show or hide rules which only apply for specified modes have an implicit element. e.g. <show id='name' for-mode='view'/> would show the name field in view mode and by implication, hide it in other modes.

appearance

The optional appearance element controls the look & feel of the controls that make up the form. Unlike the field-visibility element this element will be processed and the information available to custom templates defined with the view-form, edit-form and create-form elements, it is up to those templates whether they use the available data.

The configuration of what fields are present and how they appear has been separated to provide the maximum flexibility, although maybe slightly more verbose, the separation allows the appearance to be defined for fields that are not explicitly mentioned within the field-visibility element, a feature that will be exploited in the future.

set

The optional set element provides the basis of creating groups of fields. The id attribute gives the set a unique identifier that other set definitions and fields can refer to. The parent attribute allows sets to be nested, the value should reference a valid set definition previously defined. The appearance attribute specifies how the set will be rendered, currently the supported allowable values are 'fieldset', 'panel', 'bordered-panel', 'title' and 'whitespace', an example of these is use can be found here. If an appearance attribute is not supplied the set will not be rendered, whereas if it is set to '' the set will be rendered but without any decoration. The label and label-id attributes provide the title for the set when it's rendered, if neither are supplied the set's id is used. The template attribute specifies the absolute path to the template to be used when the set is rendered, allowing the layout of the set's fields to be customized.

A default set with an id of '' (empty string) is always present, any fields without an explicit set membership automatically belong to the default set. The default set will be displayed with a label of 'Default', to change the label see this example.

field

The field element allows most aspects of a field's appearance to be controlled from the label to the control that should be used. The only mandatory attribute is id, it specifies the field to be customized, however, the field id does not have to be present within the field-visibility element.

The label and label-id attributes define the label to be used for the form, if neither attribute is present the field label returned from the FormService is used. The description and description-id attributes are used to display a tooltip for the field, if neither is present the description returned from the FormService is used (this could also be empty).

The read-only attribute indicates to the form UI generation template that the field should never be rendered as editable.

The mandatory attribute marks the field as mandatory, this will add a mandatory validation handler to the form so that the form can only be submitted once all data has been provided. A required field marker will normally be rendered as well. Note that if a field is returned from the server marked as mandatory, setting this attribute has no effect, the field will always be mandatory.

Finally, the optional set attribute contains the id of a previously defined set. If the attribute is omitted the field belongs to the default set.

control

The control element allows the control being used for the field to be configured or customized. If present the template attribute specifies the absolute path to the template snippet to use to represent the field overriding the default-control template.

The control-param sub-elements provide a mechanism to pass parameters to control templates, this template could either be the one defined locally or the template defined in the default-control element for the data type of the field. Examples of these scenarios can be found here and here.

constraint-handlers

The constraint sub-elements define what JavaScript function to use to check that fields with constraints are valid before being submitted. The main purpose of this element is to allow aspects of the constraint to be overridden for a particular field. Each attribute effectively overrides the equivalent attribute explained above.

Using the Form Component

The Form component is a SURF Component, as such it can be placed in a template via a region tag, for example:

As with any SURF Component it is bound to the page and configured using an XML file.

As mentioned above the Edit Metadata page in Share uses the form component, it's component binding is shown below:


<component>
   <scope>template</scope>
   <region-id>edit-metadata</region-id>
   <source-id>edit-metadata</source-id>
   <url>/components/form</url>
   <properties>
      <itemKind>node</itemKind>
      <itemId>{nodeRef}</itemId>
      <mode>edit</mode>
      <submitType>json</submitType>
      <showCaption>true</showCaption>
      <showCancelButton>true</showCancelButton>
   </properties>
</component>

The form component accepts several properties, most of which are shown above, the complete set are described below.

itemKind

The 'kind' of item the form is for, the only supported kind currently is 'node'.

itemId

The identifier of the item the form is for, this will be different for each 'kind' of item, for 'node' it will be a NodeRef.

formId

The form configuration to lookup, refers the id attribute of the form element. If omitted the default form i.e. the form element without an id attribute is used.

mode

The mode the form will be rendered in, valid values are 'view', 'edit' and 'create', the default is 'edit'.

submissionUrl

Provides a URL to submit the form to, if omitted the default URL returned from the FormService is used.

submitType

The 'enctype' to use for the form submission, valid values are 'multipart', 'json' and 'urlencoded', the default is 'multipart'.

destination

Provides a destination for any new items created by the form, when present a hidden field is generated with a name of alf_destination.

showCaption

Determines whether the caption area above the form is displayed, by default this contains the '* Required Fields' message. If omitted the caption is not shown.

showCancelButton

Determines whether the Cancel button is displayed. If omitted the Cancel button is not shown.

showResetButton

Determines whether the Reset button is displayed. If omitted the Reset button is not shown.

Customizing Forms

There are multiple points in the Forms Engine stack where customizations can be applied, the most common ones are outlined below and some examples are also available.

Controls

Probably the most common customization will be added new controls. A control is classed as the label for the field and UI the user interacts with in order to set and/or edit the value for the field.

A control is defined as a Freemarker template snippet i.e. it just includes the markup to define the control. Refer to the Configuration section above for details on specifying any dependencies the control has.

As you'd expect a model is available representing the field and form being generated, represented by a field and form object, respectively.

The structure of the form object is detailed in the Form Template section.

The structure of the field object is shown below (using the cm:name property as an example):


{
   kind : 'field',
   id : 'prop_cm_name',
   configName : 'cm:name',
   name : 'prop_cm_name',
   dataType : 'd:text',
   type : 'property',
   label : 'Name',
   description : 'Name',
   mandatory : true
   disabled : false,
   repeating : false,        
   dataKeyName : 'prop_cm_name',
   value : 'plain-content.txt',
   control:
   {
      params: {},
      template : 'controls/textfield.ftl'
   }
}

Although the id property provides a unique identifier for the field it is only scoped to the current form. If there are multiple forms on the page containing the same field this id will not be unique. The remaining model property to mention fieldHtmlId should be used as the id for the control as this is guaranteed to be unique for the page.

The state of the disabled property must always be adhered to when implementing controls as this is driven from the field definition returned from the FormService and from the read-only attribute in the form configuration. If this is set to 'true' the control should never allow the value to be edited.

The control is also responsible for rendering an appropriate UI representation for the mode the form is currently in. The form mode can be retrieved from the form.mode property. A pattern used by most the out-of-the-box controls is shown below.

The final rule for controls is that they MUST supply the fields current value in a DOM element that has a value property and the id property set to the value of fieldHtmlId Freemarker variable. For advanced controls i.e. association, date, period etc. this usually means a hidden form field.

An example custom control can be seen in this example.

Validation Handlers

A validation handler is a small JavaScript function that gets called by the Forms Runtime when a field value needs to be validated.

The interface for a validation handler is shown below.


/**
 * Validation handler for a field.
 * 
 * @param field {object} The element representing the field the validation is for
 * @param args {object} Object containing arguments for the handler
 * @param event {object} The event that caused this handler to be called, maybe null
 * @param form {object} The forms runtime class instance the field is being managed by
 * @param silent {boolean} Determines whether the user should be informed upon failure
 * @param message {string} Message to display when validation fails, maybe null
 * @static
 */
function handler-name(field, args, event, form, silent, message)

The definition of the built in 'mandatory' validation handler is shown below.


Alfresco.forms.validation.mandatory = function mandatory(field, args, event, form, silent, message)

The field parameter is usually the HTML DOM element representing the field's value, this is normally an HTML input DOM element so that the value property can be accessed. The structure of the args parameter is totally dependent on the handler being implemented, by default these will be the parameters of the constraint defined on the field. All the other parameters are self sufficiently described above in the code documentation.

The handler is responsible for taking the value from the field and using the args to calculate whether the current value is valid or not returning true if it is valid and false if it is not.

Form Template

The out-of-the-box templates that generate the form UI are fairly limited in terms of layout, without sets fields are just rendered from top to bottom in a single column. Sets can be used to group fields and have them rendered within a standard HTML fieldset or within a headed panel. Customized sets will be possible in the future but that still not be flexible enough for some scenarios.

Via configuration it is possible to specify an alternative Freemarker template to use for the form in each mode using the view-form, edit-form and create-form elements. If present the FormUI component will use the custom template instead of the default one.

As you'd expect a model is available representing the form, sets and fields being generated, represented by a form object as shown below (using a cm:content node as an example):


{
   mode : 'edit',
   submissionUrl : '/share/proxy/alfresco/api/node/workspace/SpacesStore/fe06c598-2a97-4807-aaff-aacbf614bd87/formprocessor',
   showCaption : true,
   showCancelButton : true,
   showResetButton : false,
   enctype : 'application/json',
   method : 'POST'
   arguments :
   {
      itemId : 'workspace://SpacesStore/fe06c598-2a97-4807-aaff-aacbf614bd87',
      itemKind : 'node'
   },
   fields :
   {
      'prop_cm_name' :
      {
         id : 'prop_cm_name',
         ...rest of field info goes here...
      }
      ...rest of fields go here...
   },
   structure :
   [
      {
         id : '',
         kind : 'set',
         label : 'General',
         appearance : 'panel'
         children :
         [
            ...fields and/or sets go here...
         ]
      }
   ],
   constraints :
   [
      {
         params : '{}',
         event : 'keyup',
         validationHandler : 'Alfresco.forms.validation.mandatory',
         fieldId : 'prop_cm_name'
      }
   ],
   data :
   {
      prop_cm_name : 'example.txt',
      ...rest of data goes here...
   }
}

The fields property is an object representing a map of all available field objects.

The structure property is an array of objects representing the root sets. The children property is also an array, an array of further nested sets or the field objects that belong to the set.

The constraints property represents all the constraints defined for all the fields for the whole form, these are registered with the Forms Runtime to enable validation.

The custom form template is free to use as much or as little of the supplied form model as it wants, the only caveat is that the generated form UI must ensure that any fields that need to be disabled are rendered as such.

FormProcessor Filter SPI

The FormService uses a FormProcessor to handle the generation and persistence of a form. The default FormProcessor implementations provide custom hook points via the Front Controller pattern, very similar to the approach used by Servlet Filters.

The Filter interface defined by the Forms Engine is shown below.


package org.alfresco.repo.forms.processor;

...

public interface Filter<ItemType, PersistType>
{
   public boolean isActive();
    
   public void beforeGenerate(ItemType item, List<String> fields, List<String> forcedFields, Form form, Map<String, Object> context);
    
   public void afterGenerate(ItemType item, List<String> fields, List<String> forcedFields, Form form, Map<String, Object> context);
    
   public void beforePersist(ItemType item, FormData data);
    
   public void afterPersist(ItemType item, FormData data, PersistType persistedObject);
}

A filter registry is associated with each FormProcessor implementation, each registered Filter is then called (within the same transaction) for each request processed by the FormProcessor. The order the Filters are executed is not guaranteed.

To register a new Filter (for the NodeFormProcessor) the following Spring configuration needs to be defined.


<bean id='yourCustomFilter'
             class='your.CustomFilter'
             parent='baseFormFilter'>
   <property name='filterRegistry' ref='nodeFilterRegistry' />
</bean>

Debugging & Testing

As a majority of the Forms Engine stack is based on Web Scripts all the information pertaining to Web Script Administration is valid here.

Any changes made to custom config files, custom controls and custom templates (as long as they are outside the core WEB-INF classloader) can be reloaded via the Refresh button on the Web Script index page.

Logging can also be enabled, for Web Scripts logging can be enabled with the following log4j statements:


log4j.logger.org.alfresco.web.scripts.ScriptLogger=debug
log4j.logger.org.alfresco.repo.jscript.ScriptLogger=debug

and FormService logging can be enabled with the following log4j statements:


log4j.logger.org.alfresco.repo.forms=debug
log4j.logger.org.alfresco.web.config.forms=debug

A temporary test 'Form Console' is also currently available in the Share client via the url: http://share-host:share-port/share/page/form-test, this will probably be re-factored at some point soon though to use the Share admin console framework.

Examples

Several examples of configuration and customization of the Forms Engine can be found here.

Forms Roadmap

There is still a lot of work ahead for the Forms Engine, some of the planned features are listed below:

Repeating field and set support
XML Schema Support (to replace current XForms technology)
Replace all forms in the Share client with the form component
Form level validation
Submit time validation
Advanced controls i.e. sliders, TinyMCE control
Control help text support

Changes Applied Since 3.2 Community Release

This section highlights the minor changes made to the Forms Engine since the 3.2 Community Release, all these changes are available in SVN HEAD and will be part of the 3.2 Enterprise Release.

TypeFormProcessor

A new FormProcessor implementation has been added which provides support for creating new instances of types via a form, to use this type of form the item kind needs to be set to 'type' and the item id is the name of the type to create i.e. 'cm:folder'. To support this a new config evaluator named 'model-type' has been added allowing the fields for the 'create' form to be defined.

In order to create a new instance a destination location is required, this can either be supplied via a hidden field named 'alf_destination' in the form or the new 'destination' component binding property can be set which will automatically add a hidden field to the generated form.

Enhanced Custom Template Support

Several changes have been made to enhance the support for custom templates. Any custom template can now directly access a field's model via a new fields property in the form UI model, to support this however a change was necessary in the default freemarker templates. The items property has been renamed to structure and the object representing a field within a set now only consists of the kind property and the id field which is now essentially a pointer to the new fields property.

The custom template example has also been updated to reflect this change.

A custom template can now also be provided for an individual set thus allowing a group of fields to be laid out independently of the main form template, a new example has been added to show this new feature.

Form Context Data

A use case was found where more context than just the item was required during the Form generation phase. In order to pass this context through the stack several interfaces have had to be altered slightly to accommodate the context parameter, namely the Form Filter interface.

In order to minimize the potential changes in the future and in the interest of stabilizing the APIs as early as possible now was deemed to be the best time to make these changes as it's unlikely there are many (if any) custom form processors or filter implementations yet. The changes have currently only been made at the Java API layer, the ability to pass context via the REST and JavaScript APIs will be added at a later date as these changes can be made in a backwards compatible manner.

Strong Typing Introduced

Generics have been added to the FilteredFormProcessor class and Filter interface to allow stronger typing of the 'item' expected by a FilteredFormProcessor or Filter implementation. Furthermore, the FilterRegistry used by the FilteredFormProcessor is also strongly typed meaning only Filters declared with the appropriate types can be registered. Overall, this greatly reduces the likelihood of runtime errors from casting exceptions.

Set Appearances

This list of allowable values for the appearance attribute in the set element has been increased, it is now 'fieldset', 'panel', 'bordered-panel', 'title', 'whitespace' and '', an example of the effect these have is shown in this example.

The CSS class name for the 'panel' appearance has changed from 'form-panel*' to 'set-panel*' to follow the naming convention of 'set-[appearance-value]'.

Mandatory Fields

An optional field can now be marked as mandatory via a new mandatory attribute on the field element, see the Configuration section for details.

3.2 Forms

3.2 Forms

Table of Contents

Introduction

Where Are Forms Used?

How Do Forms Work?

Architecture

Event Sequence

Controls

Configuring Forms

Using the Form Component

Customizing Forms

Controls

Validation Handlers

Form Template

FormProcessor Filter SPI

Debugging & Testing

Examples

Forms Roadmap

Changes Applied Since 3.2 Community Release

TypeFormProcessor

Enhanced Custom Template Support

Form Context Data

Strong Typing Introduced

Set Appearances

Mandatory Fields

We use cookies on this site to enhance your user experience