Through this post I hope to provide a useful insight into key aspects of creating a custom dashlet for Alfresco’s Share web application, using the Surf framework and communicating with Alfresco’s content repository.

Dashlets can be created without Alfresco content repository access e.g. pulling in a feed from an external RSS feed like BBC News. However the Todo-list Ixxus created communicates between the Share UI, Surf webscripts and Alfresco webscripts over HTTP, with the list items being stored as content nodes in the Alfresco repository.

Setting up the dashlet component

Just like any other alfresco webscript, we need to start with the xml description file.

Create folder in the following location (relative to your setup) AlfrescoRoot/webapps/share/custom/WEB-INF/classes/alfresco/site- webscripts/org/alfresco/components/dashlets and add the following xml file called todolist.get.desc.xml.

<webscript>
   <shortname>To-Do List</shortname>
   <description>To-Do List</description>
   <family>user-dashlet</family>
   <url>/todo/todolist</url>
</webscript>

More details on creating simple dashlets can be found in the slides accompanying the Optaros Surf Code Camp.

Along side the desc file we need to have the freemarker template to render the html of the dashlet itself (todolist.get.html.ftl), the javascript backing the template (todolist.get.js) and an optional “head” ftl that allows any CSS and JS files specific to the dashlet to be added to the <head> of the share homepage.

For our todo-list we added a custom CSS file and JS file along with CSS and JS for the YUI calendar component. Our todolist.get.head.ftl looks like this:

<!-- Individual YUI CSS files --> 
<link rel="stylesheet" type="text/css" href="${page.url.context}/yui/calendar/assets/skins/default/calendar.css"> 
<!-- Individual YUI JS files --> 
<script type="text/javascript" src="${page.url.context}/yui/calendar/calendar.js"></script> 
<!-- Todo List Assets -->
<link rel="stylesheet" type="text/css" href="${page.url.context}/components/dashlets/todo-list.css"/>
<script type="text/javascript" src="${page.url.context}/components/dashlets/todo-list.js"></script>

You could also have inline CSS and JS code in this template if needed.

Refresh your webscripts by going to http://yourhost:8080/share/service/index and clicking the Refresh Web Scripts button.

Then go to the Share dashboard and click “Customize Dashboard”, your new dashlet should appear in the list after clicking the “Add Dashlets” button.

Retrieving remote JSON data from Alfresco

For our todo-list dashlet we need to make a few remote calls to alfresco to retrieve data.

For this we use the remote variable and connectors in the JS webscript backing our template.

var connector = remote.connect("alfresco");
var data = connector.get("/todo");

On the Alfresco side we need a webscript with a corresponding url “/todo” that can return the data we need. In our case we have a webscript that returns us a JSON string containing an array of tasks and categories.

NOTE: To get JSON from Alfresco to Surf remember to escape the data in the (alfresco app) JSON ftl using the following:

<#escape x as jsonUtils.encodeJSONString(x)>
    <#-- JSON inside here e.g. -->
    {    
        “tasks”:
        [
            { “description”: “task one…” },
            { “description”: “task two” }
        ]
    }
</#escape>

Once we have our response JSON we create a JSON object from the data returned and can then access our “tasks” and “categories” values, e.g.

// create json object from data
var results = eval('(' + data + ')');

// store tasks on model object for use in rendering template
model.tasks = results["tasks"];

In this example the “tasks” property will be available as a root variable in the associated freemarker template, in this instance an array, which we can iterate through using the list directive.

<#list tasks as task>
    <p>${task.description}</p>
</#list>

Sample Dashlet

Ixxus recently released a Todo-list dashlet to the Alfresco Content Community.