How to modify dashlets to auto-refresh?

Question

Is there a simple way to modify a dashlet to automatically re-load itself periodically?

I am particularly thinking of the "My Tasks" dashlet - we are using pooled review workflows, so tasks may come and go all the time as they are created and then are claimed.

It may be frustrating for users to keep clicking on tasks that turn out to have already been claimed - or having to remember to keep re-loading their Dashboard page. I'd prefer the dashlet to refresh on a timed interval so it's always reasonably up to date.

Answer 1

In order to do this you will need to add a new capability to the client-side class Alfresco.dashlet.MyTasks (docs, source) found in the file components/dashlets/my-tasks.get.js. First you will need to add a new method to the prototype extension specified as the second parameter in the YAHOO.lang.augmentObject() call, e.g.

      ...
      }, // end of last OOTB function - add a comment here

      // begin changes
      reloadData: function MyTasks_onReady()
      {
         this.widgets.alfrescoDataTable.loadDataTable(
            this.options.filters[this.widgets.filterMenuButton.value]
         );
      }
      // end changes
   });
})();

It's not the ideal development environment, you can modify the JS file directly in the Share webapp, although you will also need to update the corresponding -min.js file.

Once you've done this, check that it works by running the following line in your browser's JavaScript console

Alfresco.util.ComponentManager.findFirst("Alfresco.dashlet.MyTasks").reloadData();

If that works, then you can wire up your new method to a title bar action (see my DevCon presentation for more background info), in the dashlet web script. The method depends on whether you are using v4.2 or a previous version, but if it is the latter then you need to add some code to the dashlet's Freemarker file my-tasks.get.html.ftl (under WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/dashlets).

In that file you should see some JavaScript code inside a <script> tag, this sets up an instance of the client-side class and some utility classes, the contents of which you can replace with the following, to add your custom title bar action.

(function()
{
   var dashlet = new Alfresco.dashlet.MyTasks("${jsid}").setOptions(
   {
      hiddenTaskTypes: [<#list hiddenTaskTypes as type>"${type}"<#if type_has_next>, </#if></#list>],
      maxItems: ${maxItems!"50"},
      filters:
      {<#list filters as filter>
         "${filter.type?js_string}": "${filter.parameters?js_string}"<#if filter_has_next>,</#if>
      </#list>}
   }).setMessages(${messages});
   new Alfresco.widget.DashletResizer("${id}", "${instance.object.id}");
   var refreshDashletEvent = new YAHOO.util.CustomEvent("onDashletRefresh");
   refreshDashletEvent.subscribe(dashlet.reloadData, dashlet, true);
   new Alfresco.widget.DashletTitleBarActions("${args.htmlid}").setOptions(
   {
      actions:
      [
         {
            cssClass: "refresh",
            eventOnClick: refreshDashletEvent,
            tooltip: "${msg("dashlet.refresh.tooltip")?js_string}"
         },
         {
            cssClass: "help",
            bubbleOnClick:
            {
               message: "${msg("dashlet.help")?js_string}"
            },
            tooltip: "${msg("dashlet.help.tooltip")?js_string}"
         }
      ]
   });
})();

You will need to add some styles for the class name specified, in the dashlet's CSS file my-tasks.css, such as the following

.my-tasks .titleBarActions .refresh
{
    display: none;
    background-image: url('refresh-icon.png');
}

The icon file (here is one you could re-use) must be in the same directory as the CSS file.

Lastly you'll need to define the label dashlet.refresh.tooltop used for the title bar action's tooltip. You can do this in the dashlet web script's .properties file.

For a similar example, check out the source of my Train Times dashlet, which features a refresh title bar action.

In some ways it's actually easier to define your own dashlets than it is to extend the Alfresco-supplied ones, but if you have the option of using 4.2.x, the new method allows you to extend the existing components without duplicating any code, which obviously makes upgrades much easier.