User Configurable Dashboards
From AlfrescoWiki
Contents |
[edit] 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.
[edit] Configuring Available Layouts
The available dashboard layouts are configured inside the dashboards/layouts web-client config XML section:
<config evaluator="string-compare" condition="Dashboards">
<!-- Dashboard layouts and available dashlets for the My Alfresco pages -->
<dashboards>
<layouts>
<!-- the "default" layout - will be used for all users initially -->
<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.
[edit] 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">
<!-- Dashboard layouts and available dashlets for the My Alfresco pages -->
<dashboards>
...
<dashlets>
<!-- this is the default dashlet shown in the default layout initially -->
<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.
[edit] 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>
...
<!-- configuration of the default dashlets to display when users login for the first time -->
<!-- if this config is removed, then no dashlets will be shown by default -->
<!-- overides of this config should redefine the entire list, not assume additions to it -->
<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.");
}
}
}
}
[edit] 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:
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="/WEB-INF/alfresco.tld" prefix="a" %> <%@ taglib uri="/WEB-INF/repo.tld" prefix="r" %> <h:outputText style="font-weight:bold" value="Getting Started" /> <f:verbatim><br></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.
[edit] 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:
<%@ taglib uri="/WEB-INF/repo.tld" prefix="r" %> <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:
<%@ taglib uri="/WEB-INF/repo.tld" prefix="r" %> <r:template template="workspace://SpacesStore/e4d1c727-e98b-11da-821a-936824f635fe" />
