extending alfresco share 3.3
DESCRIPTION
Masterclass session held at Alfresco's offices, November 2010, presented by Will AbsonTRANSCRIPT
Masterclass: Extending AlfrescoShareWill Abson, Senior Solutions Engineer
Twitter: @wabson
Photo: Wikipedia - http://en.wikipedia.org/wiki/File:1910Ford-T.jpg
Share Basics
26/11/2010
● Provides a collaborative content management
application
● Fully web-based, using latest standards
● Built using best-of-breed components
● Spring Framework
● Mozilla Rhino JavaScript engine
● FreeMarker templating
● Web Scripts and Surf (now part of Spring too!)
● YUI Framework
● Scriptable, templatable, light-weight
Share Basics
26/11/2010
Share is a platform!
Why Build on Share?
26/11/2010
● Seamless access to repository APIs
● Authentication
● Content Services
● User Preferences
● UI capabilities utilising YUI
● Rich interactive forms, e.g. auto-complete
● Dialogues and pop-ups
● Access to external APIs
● Public data accessible OOTB
● Other mechanisms possible using custom end-points
Alternatives
26/11/2010
● Use Spring Surf and Web Scripts
● Use another framework
● Build from scratch
What’s a Share Extension?
26/11/2010
● Anything utilising a general Share extension point
● Scriptable, templatable
● No Java involved!
● Easily deployable (JARs/AMPs)
Extension Examples
26/11/2010
● Change the look and feel
● Custom Themes
● Set up templates
● Site Presets, Forms, Search (new in 3.4)
● Add your own capabilities
● Custom Dashlets
● Document Library Actions
● New UI components
● New page definitions
● Share header (new in 3.4)
What can we do with a Dashlet?
26/11/2010
● Display something on a dashboard
● User Dashboards
● Site Dashboards
● Access the Alfresco Repository
● Content Services
● Collaboration Services
● User Preferences
● Your own API?
● Access external data
● Store configuration
● Allows a dashlet to be customised
● Lots of cool stuff using JavaScript/YUI!
Types of Dashlet
26/11/2010
● Static Dashlets
● e.g. Hello World
● Dynamic Dashlets
● May utilise Repository RESTful API
• Either existing Alfresco APIs
• Or add your own
● Or Third Party APIs
Web Scripts 101
26/11/2010
● Unite the worlds of Content and the Web
● Very different from legacy ECM
● Provide RESTful access to the Repository
• Content objects as Resources
• Representations of objects as HTML, Atom, JSON, etc.
• Small uniform interface for access (GET, PUT, POST, DELETE)
● What are they?
● Basically a service bound to a URI
● Responds to HTTP methods such as GET, PUT, etc.
● Heavily used across the Repository and Share
● http://wiki.alfresco.com/wiki/Web_Scripts
Web Scripts 101
26/11/2010
“With Web Scripts, you can either build your own
RESTful interface using light-weight scripting
technologies such as JavaScript and Freemarker,
allowing you to arbitrarily map any content in the
Repository to resources on the web, or you can use pre-
built out-of-the-box Web Scripts that already encapsulate
many of the mappings.”
Types of Web Script
26/11/2010
● Data Web Scripts
● Basically a repository API
● Machine-readable data, e.g. JSON, Atom (XML)
● Read and write access
● Presentation Web Scripts
● Used to generate some UI (HTML)
● May be used as dashlet or a portlet
● Could be a page component (Spring Surf)
● Usually interact with Data Web Scripts
Web Script Implementations
26/11/2010
● Core components
● An XML description document – describes the URI(s) plus some
metadata
● An optional controller script – business logic in JavaScript
● One or more Freemarker response templates
● Additional components (optional)
● Configuration parameters specified as XML
● Externalised i18n strings – presentation web scripts only
What is a Dashlet?
26/11/2010
● A web-tier web script
● Declared explicitly as a dashlet
● User Dashlet, Site Dashlet or both
● Returns a HTML response
● Can have supporting resources
● Other web scripts
● Client-side resources (JavaScript, CSS, images)
Types of Dashlet
26/11/2010
● User Dashlets (user-dashlet family)
● Available on any user dashboard
● Usually independent of site content, or cross-site view
• e.g. Alfresco Network, My Sites, My Tasks
● Site Dashlets (site-dashlet family)
● Available on any site dashboard
● Typically concerned with content within a site
• e.g. Site Wiki
● Combined Dashlets (dashlet family)
● Available on both user and site dashboards
● Usually external data or static
Before We Dive In
26/11/2010
● Firefox with plug-ins
● Firebug – general helper
● JSONView – view JSON data in the browser
● Alfresco / Share 3.3
● With development settings turned on -
http://blogs.alfresco.com/wp/kevinr/2010/04/07/developer-tips-
for-alfresco-share-33/
● Web scripts „index‟ page and JavaScript debugger
• /share/service/index
• /share/service/api/javascript/debugger
● IDE such as Eclipse with syntax highlighting, code
completion, SCM, build tools, etc.
Hello, World!
26/11/2010
● The simplest type of dashlet
● Just a single web script
● Static in nature
● We don‟t need to worry about data
Project Structure
26/11/2010
● Class path resources in config
● Web-tier scripts in config/alfresco/site-webscripts
● Use sub-packages below site-webscripts folder
• e.g. com/mycompany/components/dashlets
• Do not use org/alfresco namespace
● Client-side resources in source/web
● Same as Alfresco standard source layout
● Easy deployment and packaging using Ant
Code Walk-Through
26/11/2010
● Web script org/alfresco/components/dashlets/hello-world.get
Data, Data, Everywhere
26/11/2010
● Let‟s look beyond static dashlets
● Data loading tactics
● Web-tier logic – load on page render only
● Client-side JavaScript logic – can be reloaded at any time
• May require a proxy to get around XSS restrictions
● Data formats
● JSON – easy to use, fast, flexible. Used by Share.
● XML/Atom – flexible, widely supported
● HTML – quick, non flexible
Twitter Feed Dashlet
26/11/2010
● Generic Dashlet (User or Site dashboards)
● Displays last 20 tweets of a specific user
● Loads data from Twitter JSON API● GET http://twitter.com/statuses/user_timeline/{user}.json
● Data loading performed by a second HTML web script
● Dashlet web script just acts as a container
● Client-side JavaScript loads the data web script via XHR
• Allows refreshing of data
● Configuration dialogue UI to set Twitter username
● Yet another web script!
● Glue it all together using client-side JavaScript
● Deploy as a JAR
Twitter Feed Dashlet
26/11/2010
Code Walk-Through
26/11/2010
● Client-side JS components/dashlets/twitter-user-timeline.js
● Dashlet Web script org/alfresco/components/dashlets/twitter-user-
timeline.get
● Dashlet Data Web script org/alfresco/components/dashlets/twitter-user-timeline-
list.get
● Config Dialogue Web script org/alfresco/modules/dashlets/config-twitter-user-
timeline.get
Tag Cloud Dashlet
26/11/2010
● Site Dashlet
● Displays dynamic data
● Tags associated with the current site, as a tag cloud
● Loads data from repository via existing RESTful API● GET /alfresco/service/api/tagscopes/site/{site}/tags
● GET /alfresco/service/api/tagscopes/site/{site}/{container}/tags
● Business logic could be implemented entirely in the web
tier
● But better using client-side JavaScript
● Allows „refreshing‟ of data
● Deploy as a JAR
Tag Cloud Dashlet
26/11/2010
Client-side JS Module Pattern
26/11/2010
(function()
{
...
Alfresco.dashlet.SiteTags = function SiteTags_constructor(htmlId)
{
return Alfresco.dashlet.SiteTags.superclass.constructor.call(this,
"Alfresco.dashlet.SiteTags", htmlId);
};
YAHOO.extend(Alfresco.dashlet.SiteTags, Alfresco.component.Base,
{
options:
{
...
},
onReady: function SiteTags_onReady()
{
...
// This is where the action happens
},
...
}
}
Project Structure
26/11/2010
● Class path resources in config
● Web-tier scripts in config/alfresco/site-webscripts
● Use sub-packages below site-webscripts and webscripts folders
• e.g. com/mycompany/components/dashlets
• Do not use org/alfresco namespace
● Client-side resources in source/web
● Use sub-folders below web folder
• e.g. mycompany/components/dashlets
Code Walk-Through
26/11/2010
● Web script org/alfresco/components/dashlets/site-tags.get
● Client-side JS components/dashlets/site-tags.js
Adding Repository Web Scripts
26/11/2010
● If you have Alfresco and Share running in the same container these
can also be deployed within your JAR file
Project Structure (Final)
26/11/2010
● Class path resources in config
● Web-tier scripts in config/alfresco/site-webscripts
● Repository-tier scripts in config/alfresco/templates/webscripts
● Use sub-packages below site-webscripts and webscripts folders
• e.g. com/mycompany/components/dashlets
• Do not use org/alfresco namespace
● Client-side resources in source/web
● Use sub-folders below web folder
• e.g. mycompany/components/dashlets
● Same as Alfresco standard source layout
● Easy deployment and packaging using Ant
Dashlets Summary
26/11/2010
● Dashlets can be very simple
● Start simple, built it up
● Dashlets provide a very powerful platform for extending Share
● Though not suitable for all customisations
● Need to consider development across multiple tiers
● Repository tier – data web scripts
● Web-tier – user interface
● Client-side – JavaScript running in the browser
● Light-weight technologies
● Spring
● JavaScript
● FreeMarker
Custom Document Library Action
26/11/2010
● Custom action to back up a selected document
● Based on the JavaScript API Cookbook example
● Client-side JavaScript used to call repository web script
● No user interaction
● Ties into the Document Library actions framework
● Deploy as a JAR
● Configuration also needed
Document Library Action Components
26/11/2010
● Client-side
● Client-side JavaScript action
● Action CSS
● Web-tier
● Web-tier configuration
• Document List component
• Document Details component
● i18n messages and Spring configuration
● Repository-tier (optional)
● Repository-tier data web script
Project Structure
26/11/2010
● Class path resources in config
● Repository-tier script in config/alfresco/templates/webscripts
● Use sub-packages below site-webscripts and webscripts folders
• e.g. com/mycompany/components/dashlets
• Do not use org/alfresco namespace
● i18n messages in config/alfresco/messages
● Spring configuration in config/org/springframework/extensions/surf
● Client-side resources in source/web
● Use sub-folders below web folder
• e.g. mycompany/components/dashlets
Code Walk-Through
26/11/2010
● Spring Configuration org/springframework/extensions/surf/slingshot-custom-
backup-action-context.xml
● Message Bundle alfresco/messages/slingshot-custom-backup-action.properties
● Repository Web script org/alfresco/slingshot/documentlibrary/action/backup.pos
t
Custom Red Theme
26/11/2010
● Custom Theme for Alfresco Share
● Provides custom CSS plus (optional) images
● Allow selection of theme in Admin Console
● Deploy as an AMP (not a JAR)
Custom Red Theme
26/11/2010
Custom Theme Walk-Through
26/11/2010
● Changing the title bar colour/background
● Changing the site navigation bar
● Changing the hyperlink colour
● Changing the default logos
● YUI Controls
● YUI Tree controls
● YUI Buttons
● YUI Menus
Code Walk-Through
26/11/2010
More Information
26/11/2010
● Share Extras project - http://code.google.com/p/share-
extras/
● YUI 2
● http://developer.yahoo.com/yui/2/
● http://yuilibrary.com/projects/yui2/
● Alfresco DOD 5015.2 module for further examples
● Alfresco Developer Conference 2010 Presentations
● Quickly Customising Share
● Advanced Share Customisation
● Using Forms in Share