User Configurable Dashboards

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Note: The dashboard described here is the Alfresco Explorer Dashboard and not the Alfresco Share Dashboard.

Web Client CustomizationWeb Scripts

Table of Contents

• 1 Introduction


• 2 Configuring Available Layouts


• 3 Configuring Available Components


• 4 Initially Displayed Components


• 5 Writing Dashboard Components
  
  
  
  • 5.1 Example FreeMarker Dashlet
  
  

Introduction

From Alfresco 1.4 the 'My Alfresco' area of the web-client UI is known as the Dashboard. It is a configurable area where a user can select from various pre-configured layouts and construct their own page from a list of pre-configured components. A consultant can configure, remove and add new JSP layouts and make them available to users. Developers and consultants can write new components and make them available for selection by users when they are configuring their pages.

Configuring Available Layouts

The available dashboard layouts are configured inside the dashboards/layouts web-client config XML section:

   <config evaluator='string-compare' condition='Dashboards'>
      <dashboards>
         <layouts>
            <layout id='default' columns='1' column-length='5' image='/images/icons/layout_single_column.gif'
                  label-id='layout_single_label' description-id='layout_single_desc'
                  jsp='/jsp/dashboards/layouts/single-column.jsp' />
            <layout id='narrow-right-2column' columns='2' column-length='4' image='/images/icons/layout_narrow_right_2column.gif'
                  label-id='layout_narrow_right_label' description-id='layout_narrow_right_desc'
                  jsp='/jsp/dashboards/layouts/narrow-right-2column.jsp' />
            ...
         </layouts>
         ...
      </dashboards>
   </config>

Each layout element has several mandatory attributes:

id :An ID string to uniquely identify the layout. Note that there must be one layout with the ID of default, this layout will be used by default before any configuration by the user has occured.

columns :The number of columns the layout supports.

column-length: The maximum number of components supported per column.

image :The 32x32 pixel image to display as the hint icon for the layout. This image is shown in the Dashboard Configuration Wizard when the user is selecting a layout for their dashboard.

jsp :The JSP page to be used as the layout. See the existing layout JSPs for examples on how to construct or modify existing layouts.

label OR label-id :The label text or label I18N message ID for the layout. This label is shown next to the layout image in the Dashboard Configuration Wizard.

description OR description-id :The description text or description I18N message ID for the layout. This description text is shown when the user selects a layout in the Dashboard Configuration Wizard.

Configuring Available Components

The components that can be selected for display within a layout column known as dashlets. The available dashlets are configured inside the dashboards/dashlets web-client config XML section:

   <config evaluator='string-compare' condition='Dashboards'>
      <dashboards>
         ...
         <dashlets>
            <dashlet id='getting-started' label-id='dashlet_gettingstarted_label'
                  description-id='dashlet_gettingstarted_desc'
                  jsp='/jsp/dashboards/dashlets/getting-started.jsp' allow-narrow='false' />
            ...
         </dashlets>
      </dashboards>
   </config>

Each dashlet element has several mandatory attributes:

id :An ID string to uniquely identify the dashlet. Note that the system is expecting a dashlet with the ID of getting-started as this will be shown by default in all users dashboards.

jsp :The JSP page to be used for the dashlet implementation. See the Writing Dashboard Components section below for more information on writing new dashlets.

label OR label-id :The label text or label I18N message ID for the dashlet. This label is shown in the list of available components presented to the user in the Dashboard Configuration Wizard.

description OR description-id :The description text or description I18N message ID for the layout. This description text is shown in the list of available components presented to the user in the Dashboard Configuration Wizard.

Initially Displayed Components

By default two components are displayed for all users. They are the getting-started and tasks-dodo dashlets. In Alfresco 2.1 this is configurable can be overriden in the usual way:

      <dashboards>
         ...


         <default-dashlets>
            <dashlet id='getting-started' />
            <dashlet id='tasks-todo' />
         </default-dashlets>
         ...
      </dashboards>

Override the default-dashlets section to change the dashboard as seen by users when they first access the system.

Thanks to the improved JavaScript API in Alfresco 2.1, it is now also possible for a capable admin user to modify the dashboard configuration for users in the system via JavaScript code. For example, an admin user could execute the following script to reset all personal user dashboard preferences back to the default:

var people = search.luceneSearch('TYPE:cm\\:person');
for each (p in people)
{
   logger.log('Found user: ' + p.properties.userName);
   if (p.hasAspect('app:configurable'))
   {
      var config = p.childAssocs['app:configurations'][0];
      var prefs = config.childrenByXPath('app:preferences');
      if (prefs.length == 1)
      {
         var preferences = prefs[0];
         if (preferences.properties['app:dashboard'] != null)
         {
            preferences.properties['app:dashboard'] = null;
            preferences.save();
            logger.log(' preferences found and cleared.');
         }
      }
   }
} 

Note this script will fail if you have more than 1000 users in your system, as the lucene search will return at most 1000 entries!

Writing Dashboard Components

Each dashlet component consists of a JSP fragment itself containing JSF UI components. Dashlets are like any other JSP in the web-client except a few rules and restrictions should be followed when constructing them:

• The dashlet JSP is already inside the <f:view> and <h:form> tags, therefore the dashlet should not include those tags itself.
  
• The JSP is 'included' within the dashboard container and layout JSPs as a JSF 'sub-view' - therefore only JSF components can be used within the page - no plain HTML text is allowed. Any HTML you need can be enclosed within the <f:verbatim> JSF tag.
  

A very simple example of a dashlet JSP page might be as follows:

<h:outputText style='font-weight:bold' value='Getting Started' />
<f:verbatim>
</f:verbatim>
<h:graphicImage value='/images/logo/AlfrescoLogo32.gif' width='32' height='32' />

A dashlet can contain any JSF components as appropriate and call any registered JSF managed beans as usual for a page.

Example FreeMarker Dashlet

Dashlet components can contain any selection of JSF components, including the Template component. This means it is possible to use the results of a FreeMarker template as the dashlet contents. A very simple example dashlet page:

<r:template template='/alfresco/templates/my_docs.ftl' />

The example above loads the template from the classpath. To display a template stored in the repo, copy the NodeRef of the template file and create the page as follows, paste your NodeRef value into the 'template' attribute in the example:

<r:template template='workspace://SpacesStore/e4d1c727-e98b-11da-821a-936824f635fe' />