Alfresco Share provides a rich platform for further development, allowing you to tweak and customize to your heart’s content, using only lightweight scripting and templating. But with great power, comes great responsibility, as they say. So this session looks at what it means to customize Share, before discussing how best to go about it, with tips and tricks based on real-world examples.

1. Customizing Share Best Practices!
Will Abson, Senior Solutions Engineer
@wabson!
Jeff Potts, Chief Community Officer!
@jeffpotts01!

2. “Best Practices” Disclaimer!
• We’ve done a lot of Share customization
implementation work
• BUT, things are changing quickly!
• “Best Practice” is more succinct than “things we
really feel strongly about based on all of the work
we’ve done so far”
• It would be great to get community feedback on
these recommendations and ones we’ve missed

3. Customizing Share!
Evolution of Alfresco UI customization
Image: http://en.wikipedia.org/wiki/File:Human_evolution_scheme.svg

4. What Can I Customize?!

5. What Can I Customize?!

6. What Can I Customize?!

7. High Level Architecture!
Web
Scripts
Web
Scripts

8. Share Architecture!

9. Share Architecture!

10. Best Practice Recommendations!
1. Methodology
2. Team Structure
3. Project Folder Structure and Build Tools
4. Packaging
5. Namespaces
6. Development Tools and Frameworks
7. Documentation
8. Testing

11. Use an Iterative Customization Process!
Lightweight technologies allow rapid iteration

12. Example: Content Expiration Add-on!
Sprint 1 Sprint 2 Sprint 3
Repository Share dashlet and Share dashlet and
customisations and web script JSON custom page
HTML web script template
-click-
-click-

13. Rec 1.1: Develop iteratively where possible (e.g.
Sprints)

14. Divide Team by Tier!
• If new repo tier web scripts are needed
1. Agree on a contract (URLs, Responses)!
2. Stub out JSON!
3. Create tests using the agreed to contract and stubs!
4. Work on each tier in parallel!
5. Integrate, test, go-live, repeat!

15. Divide Team by Tier!
• Can be tougher to split out Share tier versus “UI
development” aka YUI expertise
1. Designer creates pages!
2. UI person translates into markup!
3. Share tier developer puts markup in a template!
4. Gradually replace static bits with dynamic
components!

16. Rec 2.1: Divide up the work by Tier

17. Project Structure Recommendations!
• Separate your source from your deployment
• i.e., Donʼt create your project inside the webapp!!
• Choose an appropriate structure!
• Choose a build tool to deploy your code
• Even for simple projects!
• Working right from the start!
• Project structure may be dictated by your build tool!

18. Build Tools!
• Apache Ant
• Used by most Alfresco projects and modules and by Share
Extras (see Sample Dashlet project)!
• Pros – lightweight, simple!
• Cons – no dependency management, lack of task
standardization!
• Apache Maven
• Used by Spring Surf!
• Pros – Standardized project structures and targets!
• Cons – More complex, can be slow, no public Enterprise
Maven repo!

19. Example Ant Project Structure!
• Source folder config
contains classpath
resources
• Source folder source/web
contains client-side assets
• Local folder build used for
compilation, assembly, etc.
• Normally not added to revision
control!

20. Example Ant Build Script (build.xml)!
• Suitable for most simple Share add-ons
• Build packages ready for deployment
• By default builds a JAR-file extension!
• But also supports other formats!
• Support for hot-copying exploded files into a local
webapp for testing
• Optional tasks (can be commented out if not required)
• JS compression using YUI Compressor (requires
yuicompressor-2.4.2.jar and yui-compressor-ant-task-0.5.jar)!
• Web script reloading via HTTP (requires ml-ant-http-1.1.1.jar)!
• Can be customized by adding additional build scripts

21. Example Folder Structure: Sample Dashlet!
http://code.google.com/p/share-extras/wiki/SampleProject

22. Example Maven Project Structure!
• Source folder src/main/
resources contains (most)
classpath resources
• Sub-folder META-INF contains
client-side assets!
• Sub-folder webscripts contains
web script resources!
• Local folder target used for
compilation, assembly, etc.
• Normally not added to revision
control!

23. Rec 3.1: Separate your source code
Rec 3.2: Use Ant or Maven to build!

24. Packaging Options!
1. Copy into exploded Share WAR
2. Create a JAR that includes everything, drop into
WEB-INF/lib OR $TOMCAT_HOME/shared lib
3. Create an AMP
• Recommendation: Use JAR approach whenever
possible
• Shameless plug: addons.alfresco.com

25. Packaging: JAR vs. AMP!
JAR
file
format
AMP
file
format
Standard
file
format,
based
on
ZIP
format.
Same
ZIP
format,
but
supports
custom
No
support
for
metadata
yet,
but
JAR
deployment-­‐Eme
file
mappings
and
supports
it
via
MANIFEST
file.
addiEonal
module
metadata
Deploy
by
copying
into
tomcat/shared/lib
Deploy
directly
into
the
webapp
using
or
similar
or
into
WEB-­‐INF/lib
(Java
Alfresco
Module
Management
Tool
(MMT)
classloading
restricEons)
Same
JAR
can
contain
repository
and
Share
Requires
one
file
for
Share
and
another
for
customisaEons,
or
separate
JARs
can
be
repository
used
Uninstall
by
removing
the
JAR
file
Uninstall
requires
a
back-­‐up
of
the
original
WAR
file
(created
by
MMT
by
default)

26. Rec 4.1: Distribute JARs whenever possible
Rec 4.2: Distribute AMPs elsewhere
Rec 4.3: Copy into WAR for local testing!

27. Namespace Recommendations!
• Used to ensure your identifiers are unique
• Namespaces exist everywhere
• Web scripts use web script package!
• e.g. org/mycompany/share/sample/myscript.get
• Client-side assets use folder path and object namespaces!
• e.g. mycompany/components/sample/sprite.png,
MyCompany.dashlet.HelloWorldDashlet!
• Spring bean IDs use dot notation!
• e.g. mycompany.share.sample.css!
• Content models use URLs and prefixes!
• AMP module IDs use package structure with underscores!
• Do not re-use Alfresco namespaces
• Even if they are not explicit!

28. Example Namespaces: Sample Dashlet!

29. Rec 5.1: Define your own namespaces

30. Development Tools!
• Eclipse used by Alfresco developers (
• Large collection of plug-ins, e.g.!
• Web Developer Tools (JavaScript, CSS, HTML, XML)!
• Freemarker (part of JBoss tools)!
• Spring Surf and SpringSource tools (part of STS)!
• http://code.google.com/p/share-extras/wiki/
DevelopmentEnvironment!
• Alternatives are IntelliJ or <whatever you like!>!
• Spring Surf tools
• Web scripts index!
• JavaScript (Rhino) debugger!
• SurfBug tool – new in 4.0!
• http://blogs.alfresco.com/wp/ddraper/2011/08/31/surfbug/!

31. Development Tools!
• Browser plug-ins
• Firebug for Firefox!
• Chrome JavaScript debugger!
• Share components for
development
• Node Browser!
• JavaScript Console – now with
code completion!!
• More Information
• http://blogs.alfresco.com/wp/
kevinr/2010/04/07/developer-
tips-for-alfresco-share-33/!

32. Development Settings!
• Turn on Share development settings
• Caching, JS debug mode, logging!
• See comments in share-config-custom.xml.sample
• Deploy Share and Alfresco in separate Tomcat
containers for testing
• Massive time-saver!
• Must set different port numbers!!
Rec: Two Tomcats

33. Development Frameworks – Donʼt reinvent the
wheel!
• Server-side frameworks
• Spring Framework!
• Spring Surf!
• Spring Web Scripts!
• Share extension points!
• Dashlets, Admin Console Components!
• Document Library and Data List actions!
• Client-side frameworks
• YUI 2.9.0 (from 4.0, previously 2.8.1)!
• JQuery 1.5.2 (from 4.0)!
• Alfresco client-side JavaScript!

34. Rec: Mashup/re-use Whatʼs Already There!

35. Spring Web Scripts!
• Share web scripts must be placed on the classpath
• Core configuration defines multiple container folders
for web scripts
• Like the repository, folders can override each other based on web
script path!
• Use alfresco/site-webscripts for your own scripts!
• Use alfresco/web-extension/site-webscripts if you are
overriding existing scripts!
• But remember you donʼt need to override all files!
• Differently-named from repository web script folders
• So repository and Share web scripts can co-exist in the same project
structure!

36. Spring Surf Extensibility!
• New in 4.0 / Spring Surf 1.0
• Define add-on modules for Spring Surf
• Much more flexible than old method of overriding web scripts!
• Dynamically enable/disable and update modules!
• Add, extend or remove page components
• Implementation via sub-components
• Breaking down of Surf page components!
• Old component definitions will still work!
• Converted internally to new-style components with a single sub-component
with ID default
• See http://blogs.alfresco.com/wp/ddraper/

37. Extending Alfresco JavaScript!
Use the standard pattern and extend
Alfresco.component.Base
(function()
{
...
Alfresco.dashlet.SiteTags = function SiteTags_constructor(htmlId)
{
return Alfresco.dashlet.SiteTags.superclass.constructor.call(this,
"Alfresco.dashlet.SiteTags", htmlId, ["button"]);
};
YAHOO.extend(Alfresco.dashlet.SiteTags, Alfresco.component.Base,
{
options:
{
...
},
onReady: function SiteTags_onReady()
{
...
// This is where the action happens
},
...
}
}

38. Extending Alfresco JavaScript!
• Use Alfresco utility classes and methods
• Alfresco.util.Ajax for loading data!
• Alfresco.util.Anim for fading and resizing!
• Alfresco.module.SimpleDialog for modal dialogs!
• Other useful methods!
• Alfresco.util.encodeHTML() and Alfresco.util.decodeHTML()
• Alfresco.util.createYUIButton()
• Alfresco.util.parseJSON()
• Full docs at http://sharextras.org/jsdoc/

39. Extending Alfresco JavaScript!
• Declare your own custom
JS namespaces
if (typeof MyCompany == "undefined" || !MyCompany)
{
var MyCompany = {};
}
if (typeof MyCompany.dashlet == "undefined" || !
MyCompany.dashlet)
{
MyCompany.dashlet = {};
}

40. Extending Alfresco JavaScript!
• Override client-side JS methods using object prototype OR
(better) using YAHOO.extend(), YAHOO.lang.augmentProto()
and YAHOO.lang.augmentObject()
// Override "icon" column in My Tasks MyCompany.component.TaskList = ...
list YAHOO.extend
Alfresco.component.TaskList.prototype.r (MyCompany.component.TaskList,
enderCellTaskInfo = function Alfresco.component.TaskList, {
Acme_TL_renderCellTaskInfo(elCell, renderCellTaskInfo: function
oRecord, oColumn, oData) Acme_TL_renderCellTaskInfo(elCell,
{ oRecord, oColumn, oData)
elCell.innerHTML = <custom code {
goes here>; elCell.innerHTML = <custom code
}; goes here>;
};
});
Examples from Erik Winlöf’s 2010 talk More Ways of Customizing Share and
RecordsDocumentList component in Share DOD5015.2 Module

41. Rec 6.1: Set up your development environment
correctly
Rec 6.2: Work with the frameworks
Rec 6.3: Understand Share extension points
Rec 6.4: Re-use Alfresco objects and utils
Rec 6.5: Minimize code duplication!

42. Documentation Recommendations!
• Client-side documentation
• Use JSDoc annotations within comments!
• JsDoc Toolkit is used by Share Extras to generate HTML
summaries, with custom ʻAlfrescoʼ template – see
http://code.google.com/p/share-extras/wiki/JSDoc!
• Yahooʼs YUI Doc is another option -
http://developer.yahoo.com/yui/yuidoc/!
• Web script documentation
• Use <description> element in web script descriptor to
describe the script itself, plus itʼs parameters and response
format!
• Document all args in <url> element!

43. Example JSDoc comments: Sample Dashlet!

44. Rec 7.1: Document all web scripts and client-side code!

45. Testing Recommendations!
• Have a repeatable approach, right from the start
• A framework is provided for testing both Presentation
and Repository web scripts
• Different test harness classes used for each!
• Testing may be interactive (when developing) or
automated (unit tests)
• Interactive testing avoids the need to do time-consuming build-
deploy cycles!
• Unit tests can use helper methods to test correctness of their output
– and is recommended for all data web scripts!
• Note: Java unit tests required!
• http://wiki.alfresco.com/wiki/3.0_Web_Scripts_Testing

46. Testing Recommendations!
• Test your whole application as well as components
• Selenium used by Alfresco QA team!

47. Rec 8.1: Unit test your data web scripts
Rec 8.2: Test your whole application !

48. Other interesting examples!
• Share Extras
• JavaScript Console!
• CSV/JSON bulk load of users!
• Google dashlets!
• +34 other useful examples!
• FME Alfresco Extensions
• Dashlet Challenge 2011 Submissions (~12)
• See wiki for complete list of all submissions and links!
• Records Management Module
• Web Quick Start Share customizations

49. Help Wanted / Gauge Interest!
• Metaversant Five Star Ratings Widget
• Might refactor using new extensibility features and publish
the lessons learned as a tutorial!
• Port of SomeCo Developer Guide Examples
• Code mostly done for 3.3/3.4—needs to be cleaned up,
posted, docʼd!
• Needs to be refactored for 4.0!
• Collaboratively-authored Share Developer Guide
on wiki or under Creative Commons?
• Share Extras 4.0 Plans

50. Conclusions!
• Customization opens up new possibilities, but
• Set up your environment
• Understand the frameworks
• Use an appropriate project structure
• Consider which packaging format is best for you
• Don’t forget testing and documentation

51. will.abson@alfresco.com
@wabson
jeff.potts@alfresco.com
@jeffpotts01!