Hyland Connect

resplin · ‎06-05-2015

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

NOTE: Since the 3.3 Release similar examples to those detailed on this page have been included throughout the main Forms wiki page and within the Forms Development Kit where working demonstrations of the configuration can be found.

Back to 3.2_Forms

Introduction

This page contains a number of examples of how to configure, use and customize the new Forms Engine introduced in Alfresco v3.2.

All the customizations on this page should be applied to a custom configuration file. There are several choices available, a file named 'webscript-framework-config-custom.xml' or 'web-framework-config-custom.xml' can be placed in the 'alfresco/web-extension' package, however, these files are loaded by all Surf based applications so problems can occur if application specific configuration is placed in these shared files.

To resolve this potential issue all Surf based applications can supply an application specific custom configuration file. The Share application, which all of the examples on this page refer to, makes a custom configuration file named 'share-config-custom.xml' available.

Displaying Type Metadata

The following configuration exists in web-framework-config-commons.xml to define the fields for the cm:content type


<config evaluator='node-type' condition='cm:content'>
   <forms>
      <form>
         <field-visibility>
            <show id='cm:name' />
            <show id='cm:title' force='true' />
            <show id='cm:description' force='true' />
            <show id='mimetype' />
            <show id='cm:author' force='true' />
            <show id='size' for-mode='view' />
            <show id='cm:creator' for-mode='view' />
            <show id='cm:created' for-mode='view' />
            <show id='cm:modifier' for-mode='view' />
            <show id='cm:modified' for-mode='view' />
         </field-visibility>
      </form>
   </forms>
</config>

The configuration above defines that the cm:name property is visible in all modes, whereas the cm:creator, cm:created, cm:modifier and cm:modified properties will only be visible in 'view' mode.

The mimetype and size properties are known as 'transient' properties as they don't actually exist as properties in the model, they are formed from the cm:content property. The NodeFormProcessor knows about these properties and generates a field definition to represent them allowing them to appear in forms.

The force attribute as explained in the Forms Configuration section forces the NodeFormProcessor to search the entire Alfresco content model for the property or association definition before giving up and not returning anything.

Forms for custom types can also be defined in the same way, the configuration below shows the my:text, my:dateTime and my:association' properties being configured for the custom my:example type. This configuration would typically be placed in your custom config file.


<config evaluator='node-type' condition='my:example'>
   <forms>
      <form>
         <field-visibility>
            <show id='my:text' />
            <show id='my:dateTime' />
            <show id='my:association' />
         </field-visibility>
      </form>
   </forms>
</config>

In a similar manner it is also possible to add other fields to the default configuration, say for example, there was a requirement to show the node's DBID property for all cm:content nodes, the following configuration could be added to your custom configuration file to achieve this.


<config evaluator='node-type' condition='cm:content'>
   <forms>
     <form>
        <appearance>
           <field id='cm:description'>
              <control>
                 <control-param name='rows'>20</control-param>
                 <control-param name='columns'>20</control-param>
              </control>
           </field>
        </appearance>
     </form>
  </forms>
</config>

NOTE: The full prefix version of the type is required in the condition attribute, this is slightly different than what was expected in the Alfresco Explorer property sheet configuration.

Displaying Aspect Metadata

Adding the properties and associations defined on aspects is a simple case of adding them to the list of fields to show for a type.

Building on our previous example to show the cm:from and cm:to properties for the cm:effectivity the configuration would become


<config evaluator='node-type' condition='cm:content'>
   <forms>
      <form>
         <field-visibility>
            <show id='cm:name' />
            <show id='cm:title' force='true' />
            <show id='cm:description' force='true' />
            <show id='mimetype' />
            <show id='cm:author' force='true' />
            <show id='size' for-mode='view' />
            <show id='cm:creator' for-mode='view' />
            <show id='cm:created' for-mode='view' />
            <show id='cm:modifier' for-mode='view' />
            <show id='cm:modified' for-mode='view' />

            <show id='cm:from'/>
            <show id='cm:to'/>
         </field-visibility>
      </form>
   </forms>
</config>

This approach is far more flexible as the aspects that appear can be defined on a type by type basis and full control over the ordering of the fields is possible.

It is also possible to add custom aspects to the default configuration by overriding the configuration, the following example shows how to add the fields of an example aspect to all forms for the cm:content type.


<config evaluator='node-type' condition='cm:content'>
   <forms>
      <form>
         <field-visibility>
            <show id='my:aspectProperty' />
            <show id='my:aspectAssociation' />
         </field-visibility>
      </form>
   </forms>
</config>

Configuring A Form Control

Most of the built in controls have parameters allowing some basic customization, the example below shows how to change the number of rows and columns used for the textarea control that the cm:description field uses by default.


<config evaluator='node-type' condition='cm:content'>
   <forms>
      <form>
         <appearance>
            <field id='cm:description'>
               <control>
                  <control-param name='rows'>20</control-param>
                  <control-param name='columns'>80</control-param>
               </control>
            </field>
         </appearance>
      </form>
   </forms>
</config>

If ALL textarea controls in the application need to have these settings the control can be configured in the default-controls element. The configuration below shows an example of doing this.


<config evaluator='node-type' condition='cm:content'>
   <forms>
      <default-controls>
         <type name='d:mltext'>
            <control-param name='rows'>20</control-param>
            <control-param name='columns'>80</control-param>
         </type>
      </default-controls>
   </forms>
</config>

Grouping Fields

For some longer forms it is desirable to group fields together in logical sections, this is also possible via configuration. The following configuration shows how to group some fields from an imaginary custom my:example type.


<config evaluator='model-type' condition='my:example'>
   <forms>
      <form>
         <field-visibility>
            <show id='cm:name' />
            <show id='my:text' />
            <show id='my:mltext' />
            <show id='my:boolean' />
            <show id='my:int' />
            <show id='my:long' />
            <show id='my:double' />
            <show id='my:float' />
            <show id='my:status' />
            <show id='my:restricted-string' />
            <show id='my:date' />
            <show id='my:dateTime' />
         </field-visibility>
         <appearance>
            <set id='text' appearance='fieldset' label='Text Fields' />
            <set id='number' appearance='panel' label='Number Fields' />
            <set id='date' appearance='fieldset' label='Date Fields' />
               
            <field id='cm:name' set='text' />
            <field id='my:text' set='text' />
            <field id='my:mltext' set='text' />
            <field id='my:boolean' set='text' />
               
            <field id='my:int' set='number' />
            <field id='my:long' set='number' />
            <field id='my:double' set='number' />
            <field id='my:float' set='number' />
               
            <field id='my:date' set='date' />
            <field id='my:dateTime' set='date' />
         </appearance>
      </form>
   </forms>
</config>

Nested sets are also supported via the parent attribute in the set element. The configuration below shows the fields of the my:example type in a nested set.


<config evaluator='model-type' condition='my:example'>
   <forms>
      <form>
         <field-visibility>
            <show id='cm:name' />
            <show id='my:text' />
            <show id='my:mltext' />
            <show id='my:boolean' />
            <show id='my:int' />
            <show id='my:long' />
            <show id='my:double' />
            <show id='my:float' />
         </field-visibility>
         <appearance>
            <set id='builtin' appearance='fieldset' label='Built In' />
            <set id='custom' appearance='fieldset' label='Custom Data' />
            <set id='text' parent='custom' appearance='panel' label='Text' />
            <set id='number' parent='custom' appearance='panel' label='Numbers' />
               
            <field id='cm:name' set='builtin' />
               
            <field id='my:text' set='text' />
            <field id='my:mltext' set='text' />
            <field id='my:boolean' set='text' />
               
            <field id='my:int' set='number' />
            <field id='my:long' set='number' />
            <field id='my:double' set='number' />
            <field id='my:float' set='number' />
         </appearance>
      </form>
   </forms>
</config>

Changing Set Appearance

The following configuration shows an example form configuration illustrating the use of each set appearance value.


<config evaluator='node-type' condition='my:example'>
   <form id='simple-sets'>
      <field-visibility>
         <show id='my:text' />
         <show id='my:boolean' />
         <show id='my:int' />
         <show id='my:status' />
         <show id='my:date' />
         <show id='my:singleContent' />
      </field-visibility>
      <appearance>
         <set id='' appearance='bordered-panel' label='Bordered Panel' />
         <set id='text' appearance='fieldset' label='Fieldset' />
         <set id='number' appearance='panel' label='Panel' />
         <set id='date' appearance='title' label='Title' />
         <set id='assocs' appearance='' label='Empty String' />
         <set id='toggle' appearance='whitespace' label='Whitespace' />
         <field id='my:text' set='text' />
         <field id='my:boolean' set='toggle' />
         <field id='my:int' set='number' />
         <field id='my:date' set='date' />
         <field id='my:singleContent' set='assocs' />
      </appearance>
   </form>
</config>

The screenshot below shows how the above configuration appears in the Share application.

Set-appearances.png

The only two values that probably need explanation are the last two, '' and 'whitespace'. The empty string does not render any set 'chrome' therefore can be used group fields to ensure they always appear together. The 'whitespace' appearance renders an empty div element that provides some visual separation. It's also worth noting that neither of these values actually display the set label.

Changing The Default Set Label

Fields that do not specify a set belong to the implicit 'default' set. They will be rendered, by default, together but without any visual grouping. The appearance of the default set can be controlled in the same way as other sets, just use an id of an empty string, for example.


<set id='' appearance='panel' />

This will render a panel around all the fields with a label of 'Default', to specify a different label add the label attribute as follows.


<set id='' appearance='panel' label='General' />

Alternatively, a message bundle key can be used.


<set id='' appearance='panel' label-id='form.set.general' />

Providing A Custom Form Control

If none of the out-of-the-box controls are sufficient it is extremely easy to add new ones and reference them. Controls are simply Freemarker template snippets i.e. they only contain the HTML markup required to represent the control. The templates need to be stored in the 'alfresco/web-extension/site-webscripts' package, which will usually be in the appserver's shared classpath.

Shown below is a very simple custom text field control that always displays with a green background, white text and 700px wide. This would obviously be done using a CSS class in a production system but for sake of simplicity a hard coded style is used here.



   
         ${field.label?html}:
         ${field.value?html}
      

   <label for='${fieldHtmlId}'>${field.label?html}:*</label>

The example configuration below shows this control being used for the cm:name property, presuming the file is named 'my-textfield.ftl'.


<config evaluator='node-type' condition='cm:content'>
   <forms>
      <form>
         <appearance>
            <field id='cm:name'>
               <control template='/my-textfield.ftl' />
            </field>
         </appearance>
      </form>
   </forms>
</config>

Changing Field Label Position

By default forms are rendered with the field labels positioned above the input control as shown in the screenshot below.

Field labels on top.png

Due to the power of CSS changing this layout is a simple exercise of providing some custom CSS to override the default style rules. Control dependencies can be provided via custom configuration. Presuming the custom CSS is contained in the file named 'custom-label-layout.css' and located in the '/custom/forms' folder within the web application, the following configuration could be used.


<config>
   <forms>
      <dependencies>
         <css src='/custom/forms/custom-label-layout.css' />
      </dependencies>
   </forms>
</config>

To move the labels to the left of the input control the following CSS should be present in 'custom-label-layout.css'.


.form-container label
{
   display: inline;
   float: left;
   text-align: right;
   width: 6em;
   margin-right: 1em;
   margin-top: 0.4em;
}

The result of providing this customization is shown in the screenshot below.

Fields labels to left.png

Providing A Custom Form Template

The default template that renders the form UI generates one column of fields. There are scenarios where more control may be required over the layout or the out-of-the-box template is not sufficient. To enable these scenarios it is possible to replace the default template with a custom template. A different template can be provided for each form mode.

The custom templates need to be stored in the 'alfresco/web-extension/site-webscripts' package, which will usually be in the appserver's shared classpath.

The example below shows the 'edit' form for the standard 'cm:content' type being configured to render with 2 columns of fields, the example template '2-column-edit-form.ftl' is available in the distribution in the samples folder.


<config evaluator='node-type' condition='cm:content'>
   <forms>
      <form>
            <edit-form template='/2-column-edit-form.ftl' />
      </form>
   </forms>
</config>

For completeness the contents of the '2-column-edit-form.ftl' file is shown below, it uses some of the Freemarker macros available in 'form.lib.ftl' but supplies it's own renderSetWithColumns macro to render the HTML required to create the grid using YUI's grid CSS capabilities.


${error}


      
      *${msg('form.required.fields')}

      <form id='${formId}' method='${form.method}' accept-charset='utf-8' enctype='${form.enctype}' action='${form.submissionUrl}'>
       
        

         
      </form>
      

<fieldset><legend>${set.label}</legend>
      
            ${set.label}

            
      
         
         

         
</fieldset>

With the configuration and template in place the Edit Metadata page for a 'cm'content' type in Share has the appearance shown in the screenshot below.

Fields in 2 columns.png

Providing A Custom Set Template

The previous example shows how to provide a custom template for the whole form, but there may be a scenario where only a few fields need to have a different layout. To achieve this a custom template can be provided for a set of fields via the template attribute.

The custom templates need to be stored in the 'alfresco/web-extension/site-webscripts' package, which will usually be in the appserver's shared classpath.

The example below shows a custom template being applied for a set which in turn represents the properties of the Dublin Core aspect (cm:dublincore).

  <forms>
     <form>
        <appearance>
           <set id='dublin-core' appearance='' template='/custom-set-dublincore.ftl' />
           <field id='cm:publisher' set='dublin-core' />
           <field id='cm:contributor' set='dublin-core' />
           <field id='cm:type' set='dublin-core' />
           <field id='cm:identifier' set='dublin-core' />
           <field id='cm:dcsource' set='dublin-core' />
           <field id='cm:coverage' set='dublin-core' />
           <field id='cm:rights' set='dublin-core' />
           <field id='cm:subject' set='dublin-core' />
        </appearance>
     </form>
  </forms>

</config>

The contents of the 'custom-set-dublincore.ftl' example file (available as a sample in the distribution) is shown below. When in edit mode a 2 column layout of the fields is achieved by using YUI's grid CSS capabilities. As can be seen, in line with the saying 'with great power, comes great responsibility' the template has to determine whether the fields are actually available and also what mode the form is in so that a suitable layout is produced.

<pre>

With the configuration and template in place the Edit Metadata page for a 'cm:content' type that has the Dublin Core aspect applied in Share has the appearance shown in the screenshot below.

Custom-set-template.png

Tabbed Sets, WYSIWYG, Autocomplete and Dependent Controls And Accordion Set Layout

In Episode 35 of Tech Talk Live several examples were demonstrated, including a tabbed form containing a custom autocomplete control, custom WYSIWYG control, 2 dependent controls (the contents of one drop down list being controlled by the selection in another) and a custom set layout in an 'accordion' style.

The presentation and installation instructions for the examples can be found here.

The files (an AMP and a ZIP file) can be found here or they are available as sample files in the distribution (Community Records Management Edition onwards).