bp-7 share customization best practices

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

Author: alfresco-software

Post on 15-Jan-2015




4 download

Embed Size (px)


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.


2. Best Practices Disclaimer! Weve 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 weve done so far It would be great to get community feedback on these recommendations and ones weve 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. Methodology2. Team Structure3. Project Folder Structure and Build Tools4. Packaging5. Namespaces6. Development Tools and Frameworks7. Documentation8. Testing 11. Use an Iterative Customization Process!Lightweight technologies allow rapid iteration 12. Example: Content Expiration Add-on!Sprint 1 Sprint 2Sprint 3Repository Share dashlet and Share dashlet andcustomisations and web script JSON custom pageHTML web scripttemplate -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., Dont 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 ShareExtras (see Sample Dashlet project)! Pros lightweight, simple! Cons no dependency management, lack of taskstandardization! Apache Maven Used by Spring Surf! Pros Standardized project structures and targets! Cons More complex, can be slow, no public EnterpriseMaven 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 revisioncontrol! 20. Example Ant Build Script (build.xml)! Suitable for most simple Share add-ons Build packages ready for deployment By default builds a JAR-le 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 (requiresyuicompressor-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 containsclient-side assets! Sub-folder webscripts containsweb script resources! Local folder target used for compilation, assembly, etc. Normally not added to revisioncontrol! 23. Rec 3.1: Separate your source codeRec 3.2: Use Ant or Maven to build! 24. Packaging Options!1.Copy into exploded Share WAR2.Create a JAR that includes everything, drop into WEB-INF/lib OR $TOMCAT_HOME/shared lib3.Create an AMP Recommendation: Use JAR approach whenever possible Shameless plug: addons.alfresco.com 25. Packaging: JAR vs. AMP!JAR le format AMP le format Standard le format, based on ZIP format. Same ZIP format, but supports custom No support for metadata yet, but JAR deployment-Eme le mappings and supports it via MANIFEST le. 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 le for Share and another for customisaEons, or separate JARs can be repository used Uninstall by removing the JAR le Uninstall requires a back-up of the original WAR le (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 prexes! 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: Dene 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 ! 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 withcode 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 Dont reinvent thewheel! 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 Whats 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 webscript path! Use alfresco/site-webscripts for your own scripts! Use alfresco/web-extension/site-webscripts if you areoverriding existing scripts! But remember you dont need to override all les! Differently-named from repository web script folders So repository and Share web scripts can co-exist in the same projectstructure! 36. Spring Surf Extensibility! New in 4.0 / Spring Surf 1.0 Define add-on modules for Spring Surf Much more exible 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 denitions will still work! Converted internally to new-style components with a single sub-componentwith ID default See http://blogs.alfresco.com/wp/ddraper/ 37. Extending Alfresco JavaScript!Use the standard pattern and extendAlfresco.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 namespacesif (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 = ...listYAHOO.extendAlfresco.component.TaskList.prototype.r (MyCompany.component.TaskList,enderCellTaskInfo = functionAlfresco.component.TaskList, {Acme_TL_renderCellTaskInfo(elCell, renderCellTaskInfo: functionoRecord, oColumn, oData)Acme_TL_renderCellTaskInfo(elCell,{ oRecord, oColumn, oData)elCell.innerHTML = ; elCell.innerHTML = ;};});Examples from Erik Winlfs 2010 talk More Ways of Customizing Share andRecordsDocumentList component in Share DOD5015.2 Module 41. Rec 6.1: Set up your development environment correctlyRec 6.2: Work with the frameworks Rec 6.3: Understand Share extension pointsRec 6.4: Re-use Alfresco objects and utilsRec 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 HTMLsummaries, with custom Alfresco template seehttp://code.google.com/p/share-extras/wiki/JSDoc! Yahoos YUI Doc is another option -http://developer.yahoo.com/yui/yuidoc/! Web script documentation Use element in web script descriptor todescribe the script itself, plus its parameters and responseformat! Document all args in 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 publishthe lessons learned as a tutorial! Port of SomeCo Developer Guide Examples Code mostly done for 3.3/3.4needs to be cleaned up,posted, docd! 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 Dont forget testing and documentation 51. [email protected]@[email protected] @jeffpotts01!