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!