Developing Great Dashlets

Will Abson – @wabson

About Me

• Project Lead, Share Extras• Alfresco Developer and previously Solutions Engineer• DevCon 2011 – Customizing Share Best Practices - with

Jeff Potts• Dashlet Challenge Judge 2011 & 2012

In this presentation…

…we’ll take your dashlets

From This

…we’ll take your dashlets

From This To This

What Makes a Great Dashlet?

• Summarise information in meaningful ways• Configurable• Responsive user interface• Rich controls

Event Scheduling by Bertrand Forest

Social Tops Dashlet by Sébastien Le Marchand

JMX Statistics Dashlet by Chris Paul

Now Let’s Get our Hands Dirty!

Agenda

The Basics

• Hello World

Utilising UI Components

• Title Bar Actions• Dashlet Resizers• YUI Buttons• Dom Manipulation• Event Listeners• User Preferences• Popup Notifications

Agenda

Utilising UI Components (ctd.)

• Configuration dialogues

Fetching Data

• Dashlets that access the Alfresco Repository• Dashlets that access third party services

Example Project

Source Code

• Each stage in the walk-through is available in GitHub• Corresponds to a different branch• https://github.com/wabson/great-dashlets

• I will demonstrate using a local repository

Hello World Dashlet for 4.2

• Based on Share Extras ‘Sample Dashlet’• Displays a configurable message to the user• Demonstrates structure of a basic dashlet

• Web-tier web script• Client-side assets• Best practice

• Displays static / semi-dynamic text• We will go further!

Hello World Example 1

https://github.com/wabson/great-dashlets/tree/helloworld1

Title Bar Actions

• New in Alfresco 4.0• Replaces action links previously placed in

dashlet toolbars• e.g. ‘Configure’ action

• Actions may point to a link in the same or a new window/tab or trigger custom YUI or Bubbling events

• To use, create an instance of Alfresco.widget.DashletTitleBarActions

• More info• http://sharextras.org/jsdoc/share/community-4.2.b/symb

ols/Alfresco.widget.DashletTitleBarActions.html

Hello World Example 2

https://github.com/wabson/great-dashlets/tree/helloworld2

Dashlet Resizers

• Allows resizing of user dashlets or site dashlets by Site Managers• Resizing is persistent• Height attribute stored in component configuration

• To use, create an instance of Alfresco.widget.DashletResizer

• Must supply HTML ID and component ID

• More info• http://sharextras.org/jsdoc/share/community-4.2.b/symb

ols/Alfresco.widget.DashletResizer.html

Hello World Example 3

https://github.com/wabson/great-dashlets/tree/helloworld3

Dashlet Client-side Components

• Up until now we have used standard re-usable classes (or widgets)

• Most dashlets will require us to define our own custom dashlet classes to implement the behaviour required

• To do this, extend Alfresco.component.Base to add your own implementation• Implementation should be held in custom client-side JS

files, which we need to include in the page• Once we have done this we can create an instance of

the client-side component on the page

Hello World Example 4

https://github.com/wabson/great-dashlets/tree/helloworld4

Push Button Controls

• YUI2 provides a range of different button types• http://developer.yahoo.com/yui/button/

• Alfresco.util provides a handy function for setting up push buttons• {YAHOO.widget.Button}

Alfresco.util.createYUIButton(p_scope, p_name, p_onclick, p_obj, p_oElement)

• Button element must be declared in HTML• Easier to use this if the standard component markup is

used• But we could use YAHOO.widget.Button() directly

• http://sharextras.org/jsdoc/share/community-4.2.b/symbols/Alfresco.util.html#.createYUIButton

Dom Manipulation

• YAHOO.util.Dom provides a range of static methods for locating and manipulating Dom elements• YAHOO.util.Dom.get()• YAHOO.util.Dom.getAttribute()• YAHOO.util.Dom.addClass()

• Once we have an HTML element in our hands we can• Set its content (innerHTML)• Add sibling and child elements

• Alfresco.util builds on these functions• http://sharextras.org/jsdoc/share/community-4.2.b/symb

ols/Alfresco.util.html

Hello World Example 5

https://github.com/wabson/great-dashlets/tree/helloworld5

Dashlet Toolbars

• Filters are usually implemented using YUI ‘menu’ buttons

• Or could be ‘split’ buttons if clickable too• Like push buttons we create in HTML• Activate the button using

Alfresco.util.createYUIButton• Need to provide a function to handle the click

event• Actions usually implemented as HTML links (with

icons)• Could be a hyperlink to another page or wired to a

function using YAHOO.util.Event.addListener()

Hello World Example 6

https://github.com/wabson/great-dashlets/tree/helloworld6

User Preferences

• Allow us to store user-specific configuration properties

• Properties are stored using JSON in a hierarchical structure, e.g. {com: {someco: {someapp: {foo: “bar”}}}}

• Implemented in Alfresco.service.Preferences

• Dashlets should create a class instance in their constructor

• Provide callback functions when loading and saving data

• http://sharextras.org/jsdoc/share/community-4.2.b/symbols/Alfresco.service.Preferences.html

Hello World Example 7

https://github.com/wabson/great-dashlets/tree/helloworld7

User Notifications and Prompts

• Notifications appear briefly and then fade out

• Prompts require the user to confirm something

• By default a single button is shown• We can provide multiple buttons, e.g. ‘Yes’, ‘No’

• Other functions – get user input, display web scripts, display forms

• Implemented using static methods on Alfresco.util.PopupManager

• http://sharextras.org/jsdoc/share/community-4.2.b/symbols/Alfresco.service.Preferences.html

Hello World Example 8

https://github.com/wabson/great-dashlets/tree/helloworld8

Get Latest Document Dashlet

• Original implementation by Jeff Potts• http://ecmarchitect.com/archives/

2012/05/04/1592• http://ecmarchitect.com/archives/

2012/05/15/1599• Improvements by Rik Taminaars• Further improvements for these examples• A more advanced dashlet

• Fetches data from the repository• Configurable per-instance using a config dialogue

Loading Repository Data

Credit: Jeff Potts

Loading Repository Data

• Data is loaded using a custom repository web script returning JSON data• But you could re-use existing web scripts

• Data loading in web-tier – Alfresco.util.Ajax• See http://sharextras.org/jsdoc/share/community-

4.2.b/symbols/Alfresco.util.Ajax.html• Data loading in client-side component• How do we reload data?

Get Latest Document Example 1

https://github.com/wabson/great-dashlets/tree/getlatestdoc2

Dashlet Configuration Dialogues

• Allows the dashlet to be tailored to different situations

• Configurable by users (user dashlets) or Site Managers (site dashlets)• Same storage mechanism as Dashlet Resizer

• Implement using Alfresco.module.SimpleDialog instance (docs)• Must include client-side files for this class• Must provide a web script to implement the UI• Optionally, we can provide a custom form target

• Most dashlets will use the default modules/dashlet/config/{id} target

Get Latest Document Example 2

https://github.com/wabson/great-dashlets/tree/getlatestdoc2

More Information

https://github.com/wabson/great-dashlets

http://sharextras.org/

http://sharextras.org/jsdoc/share/