bp-7 share customization best practices

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

Upload: alfresco-software

Post on 15-Jan-2015

5.709 views

Category:

Technology


4 download

DESCRIPTION

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.

TRANSCRIPT

Page 1: BP-7 Share Customization Best Practices

Customizing Share Best Practices!Will Abson, Senior Solutions Engineer

@wabson!Jeff Potts, Chief Community Officer!

@jeffpotts01!

Page 2: BP-7 Share Customization Best Practices

“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

Page 3: BP-7 Share Customization Best Practices

Customizing Share!

Evolution of Alfresco UI customization

Image: http://en.wikipedia.org/wiki/File:Human_evolution_scheme.svg

Page 4: BP-7 Share Customization Best Practices

What Can I Customize?!

Page 5: BP-7 Share Customization Best Practices

What Can I Customize?!

Page 6: BP-7 Share Customization Best Practices

What Can I Customize?!

Page 7: BP-7 Share Customization Best Practices

High Level Architecture!

Web  Scripts  

Web  Scripts  

Page 8: BP-7 Share Customization Best Practices

Share Architecture!

Page 9: BP-7 Share Customization Best Practices

Share Architecture!

Page 10: BP-7 Share Customization Best Practices

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

Page 11: BP-7 Share Customization Best Practices

Use an Iterative Customization Process!

Lightweight technologies allow rapid iteration

Page 12: BP-7 Share Customization Best Practices

Example: Content Expiration Add-on!

Sprint 1 Repository customisations and HTML web script

Sprint 2 Share dashlet and web script JSON template

Sprint 3 Share dashlet and custom page

-click-

-click-

Page 13: BP-7 Share Customization Best Practices

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

Page 14: BP-7 Share Customization Best Practices

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!

Page 15: BP-7 Share Customization Best Practices

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!

Page 16: BP-7 Share Customization Best Practices

Rec 2.1: Divide up the work by Tier

Page 17: BP-7 Share Customization Best Practices

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!

Page 18: BP-7 Share Customization Best Practices

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!

Page 19: BP-7 Share Customization Best Practices

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!

Page 20: BP-7 Share Customization Best Practices

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

Page 21: BP-7 Share Customization Best Practices

Example Folder Structure: Sample Dashlet!

http://code.google.com/p/share-extras/wiki/SampleProject

Page 22: BP-7 Share Customization Best Practices

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!

Page 23: BP-7 Share Customization Best Practices

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

Page 24: BP-7 Share Customization Best Practices

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

Page 25: BP-7 Share Customization Best Practices

Packaging: JAR vs. AMP!

JAR  file  format   AMP  file  format  

Standard  file  format,  based  on  ZIP  format.  No  support  for  metadata  yet,  but  JAR  supports  it  via  MANIFEST  file.  

Same  ZIP  format,  but  supports  custom  deployment-­‐Eme  file  mappings  and  addiEonal  module  metadata  

Deploy  by  copying  into  tomcat/shared/lib  or  similar  or  into  WEB-­‐INF/lib  (Java  classloading  restricEons)  

Deploy  directly  into  the  webapp  using  Alfresco  Module  Management  Tool  (MMT)  

Same  JAR  can  contain  repository  and  Share  customisaEons,  or  separate  JARs  can  be  used  

Requires  one  file  for  Share  and  another  for  repository  

Uninstall  by  removing  the  JAR  file   Uninstall  requires  a  back-­‐up  of  the  original  WAR  file  (created  by  MMT  by  default)  

Page 26: BP-7 Share Customization Best Practices

Rec 4.1: Distribute JARs whenever possible Rec 4.2: Distribute AMPs elsewhere

Rec 4.3: Copy into WAR for local testing!

Page 27: BP-7 Share Customization Best Practices

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!

Page 28: BP-7 Share Customization Best Practices

Example Namespaces: Sample Dashlet!

Page 29: BP-7 Share Customization Best Practices

Rec 5.1: Define your own namespaces

Page 30: BP-7 Share Customization Best Practices

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/!

Page 31: BP-7 Share Customization Best Practices

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/!

Page 32: BP-7 Share Customization Best Practices

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

Page 33: BP-7 Share Customization Best Practices

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!

Page 34: BP-7 Share Customization Best Practices

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

Page 35: BP-7 Share Customization Best Practices

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!

Page 36: BP-7 Share Customization Best Practices

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/

Page 37: BP-7 Share Customization Best Practices

Extending Alfresco JavaScript!

(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 }, ... } }

Use the standard pattern and extend Alfresco.component.Base

Page 38: BP-7 Share Customization Best Practices

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/

Page 39: BP-7 Share Customization Best Practices

Extending Alfresco JavaScript!

if (typeof MyCompany == "undefined" || !MyCompany) {

var MyCompany = {}; }

if (typeof MyCompany.dashlet == "undefined" || !MyCompany.dashlet)

{

MyCompany.dashlet = {}; }

• Declare your own custom JS namespaces

Page 40: BP-7 Share Customization Best Practices

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 list

Alfresco.component.TaskList.prototype.renderCellTaskInfo = function Acme_TL_renderCellTaskInfo(elCell, oRecord, oColumn, oData)

{

elCell.innerHTML = <custom code goes here>;

};

MyCompany.component.TaskList = ...

YAHOO.extend(MyCompany.component.TaskList, Alfresco.component.TaskList, {

renderCellTaskInfo: function Acme_TL_renderCellTaskInfo(elCell, oRecord, oColumn, oData)

{

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

Page 41: BP-7 Share Customization Best Practices

Rec 6.1: Set up your development environment correctly

Rec 6.2: Work with the frameworksRec 6.3: Understand Share extension points

Rec 6.4: Re-use Alfresco objects and utilsRec 6.5: Minimize code duplication!

Page 42: BP-7 Share Customization Best Practices

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!

Page 43: BP-7 Share Customization Best Practices

Example JSDoc comments: Sample Dashlet!

Page 44: BP-7 Share Customization Best Practices

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

Page 45: BP-7 Share Customization Best Practices

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

Page 46: BP-7 Share Customization Best Practices

Testing Recommendations!

•  Test your whole application as well as components •  Selenium used by Alfresco QA team!

Page 47: BP-7 Share Customization Best Practices

Rec 8.1: Unit test your data web scriptsRec 8.2: Test your whole application!

Page 48: BP-7 Share Customization Best Practices

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

Page 49: BP-7 Share Customization Best Practices

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

Page 50: BP-7 Share Customization Best Practices

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

Page 51: BP-7 Share Customization Best Practices

[email protected]@wabson

[email protected]@jeffpotts01!