1

Alfresco Forms Part 2: Deep Dive

Gavin CornwellServices Team Lead, Alfresco

twitter: @gcornwell

2

Agenda

• Architecture• Form Service• Form UI Component• Forms Runtime

• Demo (Customization)• Debugging• Q & A

3

Architecture

4

Form Service Overview

5

Form Service – Java API

• Item• Kind• Id

• Form object returned

public Form getForm(Item item);

public Form getForm(Item item, List<String> fields);

public Form getForm(Item item, List<String> fields, List<String> forcedFields);

public Object saveForm(Item item, FormData data);

6

Form Service – FormProcessor

• Matched by Item Kind• FilteredFormProcessor• Node, Type, Workflow & Task implementations

public Form generate(Item item, List<String> fields, List<String> forcedFields);

public Object persist(Item item, FormData data);

public boolean isApplicable(Item item);

public boolean isActive();

7

Form Service – Form Filter

• Similar to Servlet Filters• Recommended way to customise• Each FormProcessor has a FilterRegistry• Filter is called for every item

• Do conditional checks in your filter• Examples in RM

8

Form Service – Form Filter

public void beforeGenerate(ItemType item, List<String> fields, List<String> forcedFields, Form form);

public void afterGenerate(ItemType item, List<String> fields, List<String> forcedFields, Form form);

public void beforePersist(ItemType item, FormData data);

public void afterPersist(ItemType item, FormData data, PersistType persistedObject);

public boolean isActive();

9

REST API /api/formdefinitions Request

• POST /api/formdefinitions• Returns form definition• JSON passed in• JSON response

• POST /api/formprocessor• Persists form data• JSON or multipart/form-data passed in• Response matches request type

• Examples of JSON will be seen in the demo

10

Form UI Component Overview

11

Form UI Component – Web Script

Java backed UI Web Script as of 3.4

<@region id=“metadata" scope="template” protected=true />

<component> <region-id>metadata</region-id> <url>/components/form</url> <properties> <itemKind>node</itemKind> <itemId>{nodeRef}</itemId> <mode>edit</mode> <submitType>json</submitType> </properties></component>

12

Form UI Component Options

• itemKind• itemId• formId• mode• destination• redirect• submitType

• json• multipart (default)• urlencoded

• method• submissionUrl• showSubmitButton• showCancelButton• showResetButton• showCaption

13

Form UI Component Event Sequence

1. Asks ConfigService for list of fields for item

2. Sends list of fields (if any) to FormService

3. FormService response “combined” with configuration for item

4. “form” model is set (demo will show example)

5. FreeMarker template is rendered• Custom template used if configured• FTL for each control is #included• Forms Runtime initialisation code generated

14

Form UI Component FreeMarker

<#if form.xxxTemplate?? && form.mode == ”xxx"> <#include "${form.xxxTemplate}" /><#else> <#if formUI == "true"> <@formLib.renderFormsRuntime formId=formId /> </#if> <@formLib.renderFormContainer formId=formId> <#list form.structure as item> <#if item.kind == "set"> <@formLib.renderSet set=item /> <#else> <@formLib.renderField field=form.fields[item.id] /> </#if> </#list> </@></#if>

15

Forms Runtime JavaScript Library

• YUI Based• Manages form validation

• Register validation handlers• Dynamically adjusts the submit button state

• Handles form submission• POSTing data as JSON• AJAX submission• Callbacks for custom processing before & after submission

• Can be used standalone

16

Form Generation

17

Form Persistence

18

Customisation (Demo)

• Configure custom type• Create a custom form control (YUI Slider)• Create a custom form template (tabbed form)• Implement a Form Filter

• afterGenerate• beforePersist

• Debugging Tips• Forms Development Kit (FDK)

19

Debugging

• Log4J settings• org.alfresco.repo.forms=debug• org.alfresco.web.config.forms=debug• org.alfresco.web.scripts.forms=debug

• Forms Development Kit (FDK)• Form Console (/<app>/fdk/form-console)• Debug control & template (dumps model)

• Cntrl, Cntrl, Shift, Shift• Eclipse

• FormUIGet for UI• FilteredFormProcessor for server

• Spring Surf Developer Tools

20

Roadmap

• Reduce the volume of configuration required• Repeating field and group support• Upload support• Improve association support• Improve error handling (validation feedback)• Dependent field support• Form level validation• More controls

21

Q & A

22

Learn Morewiki.alfresco.com/wiki/Formsblogs.alfresco.com/wp/gavinc/

23

Appendix – Demo Config<config evaluator="node-type" condition="devcon:session"> <forms> <form> <field-visibility> <show id="devcon:code" /> <show id="cm:name" /> <show id="devcon:abstract" /> <show id="devcon:presenter" /> <show id="devcon:duration” /> <show id="daysAway" /> <show id="devcon:when" /> <show id="devcon:level" /> <show id="devcon:prerequisites" /> <show id="devcon:approved" /> <show id="devcon:rating" /> </field-visibility> <edit-form template="/devcon/tab-edit-form.ftl" /> <appearance> <set id="" label="Details" /> <set id="time" label="Time" /> <set id="feedback" label-id="set.label.feedback" /> <field id="devcon:approved" set="feedback" /> <field id="devcon:rating" set="feedback"> <control template="/devcon/progress.ftl" /> </field> <field id="devcon:when" set="time" /> <field id="devcon:duration" set="time" /> <field id="daysAway" set="time" /> </appearance> </form> </forms></config>

24

Working Example

• The working example will be made available in the next few weeks on my blog at http://blogs.alfresco.com/wp/gavinc

• In the meantime have a look at the FDK for more examples