3.4 Forms Development Kit

[resplin]

Obsolete Pages{{Obsolete}}

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

3.4Forms

NOTE: This document details the Forms Development Kit in the 3.4 Release, for the latest documentation click here.

Table of Contents

• 1 Introduction


• 2 Getting Started
  
  
  
  • 2.1 Installing the AMP
  
  
  • 2.2 Installing the JAR
  
  
  • 2.3 Building the FDK
  
  


• 3 Using the FDK
  
  
  
  • 3.1 Form Console
  
  
  • 3.2 Examples
    
    
    
    • 3.2.1 Gadget Type
    
    
    • 3.2.2 Company Type
    
    
    • 3.2.3 Aspects
    
    
    • 3.2.4 Left Aligned Labels
    
    
  
  
  • 3.3 Unit Tests
  
  
  • 3.4 XML Schema
  
  


• 4 Roadmap

Introduction

Welcome to the Alfresco Forms Development Kit (FDK).

The Alfresco FDK was introduced in the 3.3 release, it provides support for administrators and developers who wish to configure, extend or customize forms in Spring Surf based applications, for example, Share.

Getting Started

Installing the AMP

The AMP (alfresco-fdk.amp) can be installed into the alfresco.war file using the normal techniques, either with the Module Management Tool or using the apply_amps script provided with the installer.

Installing the JAR

Presuming the Tomcat instance you are using has been configured to use the shared folder you can simply drop the  JAR file (alfresco-fdk.jar) into <tomcat>/shared/lib.

You can of course drop the JAR file into  the application's WEB-INF/lib folder too i.e. <tomcat>/webapps/<appname>/WEB-INF/lib but this will be removed when you update or upgrade your application so the technique above is recommended.

If you are installing the FDK into an older Spring Surf application that does not contain the required import statement the fdk-context.xml file can be manually added to your application using the following import:

<import resource='classpath:alfresco/fdk-context.xml'/>

Building the FDK

If you are building Alfresco from source using a development environment you may wish to also build and deploy the FDK.

The main Ant build.xml file provides several targets to allow for this.

incremental-fdk

Builds the repository and client FDK files

install-fdk-amp

Builds the FDK AMP and installs it in the repository WAR file, the 'deploy-webclient-tomcat' needs to be called subsequently to deploy the WAR file to Tomcat

deploy-repo-fdk-exploded

Deploys the FDK repository files to Tomcat in exploded mode

deploy-share-fdk

Builds the FDK client JAR and deploys it to Share

deploy-share-fdk-exploded

Deploys the FDK client files to Share in exploded mode

Using the FDK

The AMP installs an example model and the JAR provides a 'Form Console' page, form configuration for the example model, a unit test page and some Share specific configuration overrides.

The 'Change Type' action in Share will now have three options (for cm:content nodes), 'Gadget', 'Company Details' and 'Everything'.

The FDK also provides an extension point (alfresco/web-extension/fdk-config-custom.xml) so that further form configuration can be provided and tested via the form console page.

A landing page is provided, available at http://localhost:8080/share/page/fdk (presuming you are using a default Alfresco installation) which provides links to the Form Console and Unit Tests pages

Form Console

If you've worked with forms in the 3.2 release you may recognize the Form Console as the old form-test page available in Share. It has now been renamed and moved to the FDK so it can be used in any Spring Surf based application.

The 'Form Console' page can be accessed via the following URL:

http://<host>:<port>/<app>/page/form-console

for example: http://localhost:8080/share/page/form-console if you are using a default installed Alfresco instance.

All the unit tests added to the FDK in this release make use of the Form Console, the screenshot below shows the Form Console displaying the 'nested-sets' form configuration.

Nested-sets-form-console.jpg

All the unit test form configurations are supplied in a file named 'fdk-unit-tests-config.xml', this can be a useful source of examples. The 'fdk-config-custom.xml' file mentioned above can be used to define more forms for further testing.

Examples

In it's current state the FDK provides a demonstration of what can be done with some of the features of the forms engine, all the samples previously distributed with Share have been moved into the FDK and made available in an easy to install package, this includes most the examples from Episode 35 of Tech Talk Live where the forms engine was discussed and demonstrated.

The following sections show a few screenshots and configuration of the example forms.

Gadget Type

When an instance of the 'Gadget' (fdk:gagdet) type is created and it's metadata edited the following form is displayed.

Fdk-tab-edit-form.png

The configuration required to achieve this is shown below.

<config evaluator='node-type' condition='fdk:gadget'>
   <forms>
      <form>
         <edit-form template='/fdk/templates/tab-edit-form.ftl' />
         <field-visibility>
            <show id='cm:name' />
            <show id='cm:description' />
            <show id='fdk:make' />
            <show id='fdk:model' />
            <show id='fdk:summary' />
            <show id='fdk:type' />
            <show id='fdk:subType' />
            <show id='fdk:rrp' />
            <show id='fdk:releaseDate' />
            <show id='fdk:endOfLifeDate' />
            <show id='fdk:retailers' />
            <show id='fdk:rating' />
            <show id='fdk:contact' />
            <show id='fdk:reviews' />
            <show id='fdk:company' />
            <show id='fdk:pressRelease' />
            <show id='fdk:images' />
         </field-visibility>
         <appearance>
            <set id='' label-id='fdk.tab.label.details' />
            <set id='press' label-id='fdk.tab.label.press' />
            
            <field id='cm:description'>
               <control template='/org/alfresco/components/form/controls/richtext.ftl' />
            </field>
            <field id='fdk:model'>
               <control template='/fdk/controls/autocomplete.ftl'>
                  <control-param name='ds'>/service/ds/autocomplete/google</control-param>
               </control>
            </field>
            <field id='fdk:releaseDate' set='press' />
            <field id='fdk:endOfLifeDate' set='press' />
            <field id='fdk:retailers' set='press' help-id='fdk.help.gadget.retailers' />
            <field id='fdk:rating' set='press' />
            <field id='fdk:contact' set='press' />
            <field id='fdk:reviews' set='press' />
            <field id='fdk:company' set='press' />
            <field id='fdk:pressRelease' set='press' />
            <field id='fdk:images' set='press' />
         </appearance>
      </form>
   </forms>
</config>

Company Type

When an instance of the 'Company' (fdk:company) type is created and it's metadata edited the following form is displayed.

Fdk-company-template.png

The configuration required to achieve this is shown below.

<config evaluator='node-type' condition='fdk:company'>
   <forms>
      <form>
         <edit-form template='/fdk/templates/2-column-edit-form.ftl' />
         <field-visibility>
            <show id='cm:name' />
            <show id='fdk:email' />
            <show id='fdk:url' />
            <show id='fdk:tel' />
            <show id='fdk:street1' />
            <show id='fdk:street2' />
            <show id='fdk:city' />
            <show id='fdk:county' />
            <show id='fdk:state' />
            <show id='fdk:postCode' />
            <show id='fdk:zip' />
            <show id='fdk:country' />
         </field-visibility>
      </form>
   </forms>
</config>

Aspects

In the 3.4 release a standard out-of-the-box EXIF aspect has been added. The 'fdk:exif' aspect provided by the FDK has therefore been deprecated.

When either the EXIF or dublin core aspects are applied to a cm:content node the FDK assigns their fields to a set and provides a custom set template. The dublin core fields are shown in 2 columns and the EXIF fields are displayed within an accordion control as shown in the screenshot below.

Fdk-dublin-core-exif-aspects.png

The configuration required to achieve this is shown below.

<config evaluator='node-type' condition='cm:content'>
   <forms>
      <form>
         <appearance>
            <set id='dublin-core' appearance='' template='/fdk/templates/custom-set-dublincore.ftl' />
            <set id='exif' appearance='' label-id='fdk.tab.label.exif' template='/fdk/templates/custom-set-exif.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' />
            <field id='exif:dateTimeOriginal' set='exif' />
            <field id='exif:pixelXDimension' set='exif' />
            <field id='exif:pixelYDimension' set='exif' />
            <field id='exif:exposureTime' set='exif' />
            <field id='exif:fNumber' set='exif' />
            <field id='exif:flash' set='exif' />
            <field id='exif:focalLength' set='exif' />
            <field id='exif:isoSpeedRatings' set='exif' />
            <field id='exif:manufacturer' set='exif' />
            <field id='exif:model' set='exif' />
            <field id='exif:software' set='exif' />
            <field id='exif:orientation' set='exif' />
            <field id='exif:xResolution' set='exif' />
            <field id='exif:yResolution' set='exif' />
            <field id='exif:resolutionUnit' set='exif' />
         </appearance>
      </form>
   </forms>
</config>

Left Aligned Labels

By default field labels are rendered above the field they represent. Although there is a lot of evidence from user studies to support this approach as being the most favorable in terms of user experience it's not to everyone's taste. The FDK provides a small CSS file as an example that moves the labels to the left of the field as shown in the screenshot below.

Fdk-left-align-labels.jpg

The configuration required to achieve this is shown below.

<config>
   <forms>
      <dependencies>
         <css src='/fdk/left-aligned-label.css' />
      </dependencies>
   </forms>
</config>

Unit Tests

The 3.4 release of the FDK added an 'FDK Unit Tests' page, it can be accessed via the following URL:

http://<host>:<port>/<app>/page/fdk-unit-tests

for example: http://localhost:8080/share/page/fdk-unit-tests if you are using a default installed Alfresco instance.

The FDK Unit Tests page provides a myriad of pre-configured examples to test the various features and capabilities of the forms engine. The NodeRef of an instance of an fdk:everything node has to be provided after which any link can be clicked to see the corresponding form. Each test uses the Form Console page with a form id from the fdk-unit-tests-config.xml file.

The screenshot below shows the tests available.

Fdk-unit-tests-page.png

XML Schema

The FDK also provides an XML schema describing the XML vocabulary for form configuration. To access the schema you'll need to checkout the source code from SVN. You'll find the schema in the root/projects/fdk/utils folder.

The schema only represents the forms configuration options so you will have to have a separate config file for your forms configuration otherwise the schema will incorrectly report errors against other Alfresco config.

Roadmap

• Improve Form Console
  
• Forms Runtime examples
  
• Form building utilities
  
• Simple Form Builder