Extending Alfresco Share 3.3

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