New Client Config & Extension Points in Share

Dave Draper @_DaveDraper

!

Background

•  Alfresco Share was not originally intended as a platform

•  Spring Surf did not provide any extension mechanism

•  Difficult to identify use cases

Goals (for 4.0)

•  Ensure that Spring Surf continues to be compatible with previous Alfresco releases (i.e. Avoid branching)

•  Minimize Share code changes •  Provide the ability to easily extend Share

without copying and pasting code •  Provide extensions through simple JAR

deployment

Goals (for next major release)

•  Make customizing client-side JavaScript widgets simpler

•  Convert Share WebScripts to common “boiler-plate” template

•  Move dependency requests into WebScript “.html.ftl” files

•  Remove Share WebScript “.head.ftl” files

Solution Overview

•  Two distinct approaches to extension o  Customization by targeting existing files o  Customization through Component configuration

•  Creation of in-memory output model o  Provides opportunity to amend default output o  Each FreeMarker template gets an output model o  Models can are nested

•  Introduction of Sub-Components o  Solves 1-1 Region to Component mapping problem

File Customization

•  Works with Templates or WebScripts •  Can extend i18n properties, JavaScript

controllers & FreeMarker templates •  FreeMarker extensions depend upon

custom directives – <@region> & <@markup> – Entirely abstract framework – scope for adding

new directives

What Can You Do With This?

•  Modify Surf templates to add, remove, modify Component bindings

•  Change display labels •  Modify the content displayed by updating

the model

Sub-Components

•  A Sub-Component maps to a WebScript •  Only AdvancedComponents support Sub-

Components o  Only Share 4.0 uses AdvancedComponents by default o  Configurable through Surf configuration

•  Legacy configuration conversion o  Components become Sub-Components

•  Support for dynamic evaluation of parameters against request

Sub-Component Evaluations

•  A Sub-Component can have zero or more Evaluations

•  Each Evaluation can use zero or more Evaluators

•  If all Evaluators are successful then Evaluation overrides Sub-Component defaults

•  WebScript URL, properties and index can be overridden

What Can You Do With This?

•  Add, remove and modify the content within a Component

•  Have a Component display different content dynamically based on request information (e.g. The Site being accessed, the current User)

Extensions & Modules •  An “Extension” can contain zero or more “Modules” •  An Extension can be configured within the application

(e.g. Portlet extension) or externally in a JAR (e.g. RM extension)

•  Three deployment modes “auto”, “enable-auto-deploy” and “manual” (manual is default)

•  Default module configuration can be overridden when deployed

•  Modules can be dynamically deployed and removed without server restart.

Benefits

•  Easy to add new coarse grained content to existing Share pages

•  Easy to override i18n properties for WebScripts

•  Scope for future enhancements using in-memory output model (i.e. new FreeMarker directives)

Restrictions (in 4.0)

•  Still difficult to extend JavaScript widgets for fine grained changes

•  Limited use of <@markup> directive in Share

•  Sub-Component extensions only work with WebScripts

•  Limited control over module overrides at deployment

Additional Tooling

•  “SurfBug”: identifies the Spring Surf elements on each page: o  Sub-Components & Component bindings, properties &

evaluation results o  Contributing file paths o  WebScript information o  Customization data (i.e. use of extensibility directives)

Additional Dependency Handling

•  Use <dependencies> element as a child of <customization> element in Module configuration:

<dependencies> <css>/res/demo/dependencies/styles.css</css> <js>/res/demo/dependencies/script.js</js> </dependencies>

Share Configuration Support

•  Available from 4.0.2 •  Use of <configurations> element as a

child of <module> element •  Allows dynamically evaluated Share

configuration changes (i.e. that would typically be found in “share-config.xml”)

•  MUST include all configuration – it is not an augment capability

Demos

Adding New Content (Method 1)

Create some content...

WebScript Template

WebScript Descriptor

Target Area Of Share...

Define new Sub-Component...

Deploy Module...

Result...

Hiding Existing Content (Method 1)

Target Sub-Component to hide...

Result...

Conditional Hide

Create an Evaluator...

Make the Evaluator a Spring Bean...

org.springframework.extensions.surf.spring-surf-extensibility-context.xml

Specify the Evaluator...

Result...

Adding New Content (Method 2)

Target a TemplateInstance...

Define a customization...

Create the customization file...

(in specified package)

Define a Component to bind to new Region...

(re-using the WebScript from the earlier example to provide content)

Result...

Hiding Existing Content (Method 2)

Remove the Region... (Same target, different action)

Other actions are available... § “after” § “modify”

Override i18n Properties

Find the property...

Define a customization...

Create the customization file...

Note that the location of a WebScript customization is at a different path root than for TemplateInstance customizations!

Result...

Override JavaScript Controller

Identify JavaScript model properties...

Define a customization...

Create The Customization File...

Result...

Other Demos (if time allows)

•  Site conditional Flash upload •  User conditional help •  Additional dependencies •  Document Library extension

Other Customizations…

•  Re-order entire pages (add + remove regions)

•  Auto readme (see Blog post) •  PeerBind Chat Service (see David

Webster’s blog) •  Resource Management module •  Portlet module •  ...

Additional Reading

•  Lots more in-depth information and tutorials available at: http://blogs.alfresco.com/wp/ddraper

•  Alfresco Surf Development Forum •  More blogs to come!