Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
Table of Contents
Introduction
The majority of UI actions in the Alfresco Web-Client are now configured in web-client config XML files. Groups of actions can be defined, each action can be reused in multiple groups and the action groups themselves reused across multiple pages. Previously all actions were defined directly in the JSP files using individual <r:actionLink /> components. This resulted in a lot of code duplication for the same action definition between pages and also meant that core web-client files had to be modified when developing a new module or to change an existing action. This configuration now means that a consultant is no longer needed to modify core Alfresco JSP files (e.g. browse.jsp) to add or modify a UI action definition.
Action Configuration Files
The web-client ships with a default action config file:
web-client/config/alfresco/web-client-config-actions.xml
This file contains the basic definitions of most Alfresco UI actions. It also contains the definitions of the Action Groups that are used for the Browse Screen, Document Details and Space Details screens. Action Groups define an ordered list of actions that are displayed together, either in a serial list (e.g. as a strip of icons) or grouped together in a drop-down menu component. This file is the best source of examples for many different styles of UI actions.
The web-client also ships with an additional action config file:
web-client/config/alfresco/web-client-config-forum-actions.xml
The file defines the actions for the Forums module that is part of the default web-client install. It is an excellent example of how to override existing actions, define additional actions and how to override the actions displayed in an existing action group.
When adding your own actions, you should add Action config blocks to the custom web-client config file (as detailed in the Web Client Configuration Guide).
Action Definition Configuration
Each UI action definition is defined once in an <action> element with a unique ID attribute. It can be referenced and reused by any number of action groups using this ID.
An action definition represents a single UI action widget. It is equivalent to a single <r:actionLink /> JSF component and as such several of the config elements define attributes that will be familiar to users of this component.
The various configuration elements define; the component, the user permissions required to execute the action, the resulting action to perform (e.g. a JSF ActionListener method or a JavaScript onclick event handler) and a few display attributes such as CSS style and CSS class.
An important concept to understand when configuring actions is the notion of the actionContext object. This is the Node object context for the action. This object can be referenced in JSF value binding expressions within config in the same way that <r:actionlink /> components may refer to the current row object in a datalist with the original mechanism for defining actions. See the examples below and the Action Group config below for more information on using this object.
Action Definition Config Elements
An example action definition:
<action id='edit_doc_http'>
<permissions>
<permission allow='true'>Write</permission>
</permissions>
<evaluator>org.alfresco.web.action.evaluator.EditDocHttpEvaluator</evaluator>
<label-id>edit</label-id>
<image>/images/icons/edit_icon.gif</image>
<action-listener>#{CheckinCheckoutBean.editFile}</action-listener>
<params>
<param name='id'>#{actionContext.id}</param>
</params>
</action>
The example is a simple Edit action from the web-client general browsing screen. The action checks for the the existence of the WRITE permission on the context object for the action and display the Edit icon. It also has a evaluator class which is custom logic used to decide whether the action should be displayed to the current user (see below for more info on evaluator classes). When clicked the action calls the #{CheckinCheckoutBean.editFile} JSF action listener bean method. Note that a parameter is defined (using the actionContext object mentioned above) which is passed to any JSF actionListeners on the UIActionLink component.
The set of available configuration sub-elements are defined below:
- action : The parent element defines a single action definition. The mandatory id attribute defines the unique ID by which the action is referenced for use in action group elements (see below). Defining another action with the same ID as an existing action effectively overrides the original action definition. The All other elements must be contained with the action element.
- permissions : Contains 1 or more permission elements.
- permission : Contained with the permissions element. Defines the permission values that must be checked against the current Node action context to allow the action to be displayed to the current user. The allow attribute defines whether the permission check is ALLOW or DENY. For example:
<permissions>
<permission allow='true'>Write</permission>
<permission allow='false'>AddChildren</permission>
</permissions>
- evaluator : An optional custom class implementing the org.alfresco.web.action.ActionEvaluator interface. A class implementing this interface can implement custom Java code as a condition against allowing the action to be displayed for the current user. For example:
<evaluator>org.alfresco.web.action.evaluator.CancelCheckoutDocEvaluator</evaluator>
- Example class implementation:
/**
* UI Action Evaluator - Cancel checkout document.
*/
public class CancelCheckoutDocEvaluator implements ActionEvaluator
{
public boolean evaluate(Node node)
{
return (node.hasPermission(PermissionService.CANCEL_CHECK_OUT) &&
node.hasAspect(ContentModel.ASPECT_WORKING_COPY));
}
}
- From the 2.2 release onwards evaluators can also be used for objects other than Node (org.alfresco.web.bean.repository.Node). A new method (shown below) has been added to the ActionEvaluator interface.
public boolean evaluate(Object obj);
- To keep implementations of the ActionEvaluator simple and succinct, a new base class (org.alfresco.web.action.evaluator.BaseActionEvaluator) has been added that provides a default implementation of both methods. This is now used by all action evaluators in the org.alfresco.web.action.evaluator package. An example of the new evaluate method can be found in org.alfresco.web.action.evaluator.GroupActionEvaluator.
- label : Textual label for the action link. This value will also be used as the icon tooltip if none is defined.
- label-id : I18N message Id for the textual label for the action link - this should generally be used in preference to the label element to allow for I18N language translation.
- tooltip : Textual tooltip for the action link.
- tooltip-id : I18N message Id for the tooltip for the action link - this should generally be used in preference to the label element to allow for I18N language translation.
- show-link : A presentation attribute. Valid values are true or false. If set true the action will be show an icon and a textual link, if set false the action will only show an icon with the label as the tooltip for the icon image.
- style : A presentation attribute. The CSS style to apply to the action.
- style-class : A presentation attribute. The CSS class to apply to the action.
- image : The icon image to display.
- action-listener : The JSF action listener method to call upon user selection of the action.
- action : The JSF action navigation outcome to execute upon user selection of the action.
- script : The Alfresco JavaScript file to execute - specified by either Path or full Node reference, for example:
<script>/Company Home/Data Dictionary/Scripts/myjavascript.js</script>
- When executed the script has no default context (i.e. the usual 'document' and 'space' objects will not be defined) so any required String arguments such as IDs to nodes should be passed to the script via the 'params' arguments (see below). For example:
<script>/Company Home/Data Dictionary/Scripts/myjavascript.js</script>
<params>
<param name='dummy'>dummy1</param>
<param name='noderef'>#{actionContext.nodeRef}</param>
</params>
- The parameters will be available in the 'args' JavaScript array accessible in the root of the script context. So you could then execute code such as:
var nodeRef = args['noderef']; var node = search.findNode(nodeRef);within your action script to get the context node for your action.
- It is quite common to want to return to the previous page after the execution of a script action. An easy way to achieve this is to add the following at the end of your script:
var goBack = '<script>history.back();</script>';
goBack;
- Note that this approach will not refresh the page the user initiated the action from, so if your script modifies that page in some way (eg. renames, moves or deletes a document) some confusion may ensue. To resolve that you might instead choose to use code such as:
var goBack = '<script>location.href = '/alfresco/navigate/browse/workspace/SpacesStore/' + nodeParent.id + '';</script>';
goBack;
- Remember that the output of a script is returned as the response to the browser upon completion of execution, therefore any output (including client-side JavaScript) will be display or executed by the browser. See this forum article for more discussion on the subject: http://forums.alfresco.com/viewtopic.php?t=4654; additional information is available in this forum article: http://forums.alfresco.com/viewtopic.php?p=31571
For more samples please see JavascriptReturn
A more complete example would be:
<config>
<actions>
<action id='custom-action-my-script'>
<permissions>
<permission allow='true'>Write</permission>
</permissions>
<label>My Custom UI Action</label>
<tooltip>Runs the specified JavaScript</tooltip>
<show-link>true</show-link>
<style>padding:4px</style>
<style-class>inlineAction</style-class>
<image>/images/icons/CheckIn_icon.gif</image>
<script>/Company Home/Data Dictionary/Scripts/my_script.js</script>
<params>
<param name='id'>#{actionContext.id}</param>
</params>
</action>
<action-group id='browse_actions_menu'>
<action idref='custom-action-my-script' />
<action idref='custom-action-my-script' />
</action-group>
</actions>
</config>
- href : The HREF to navigate to upon user selection of the action.
- target : The associated HREF target.
- onclick : The JavaScript onclick handler to execute upon user selection of the action.
- params : Contains 1 or more param elements.
- param : Contained with the params element. Defines the <f
aram /> tags to be generated as children of the action component. Each param element has a mandatory name attribute as the name of the parameter and the mandatory value of the element contains the value to passed as the parameter. Parameters are available from the UIActionLink component passed to the JSF action-listener method upon user selection of the action. Parameters are also passed directly as href/script URL arguments - only string arguments such as a Node ID as usable as script URL arguments.
Action Group Configuration
An Action Group is a named list of actions that can be referenced on a JSP page by an <r:actions /> JSF component. An Action Group is defined in the config as an 'actions' element, that lists a set of actions that reference specific action definitions as defined above, or define a new action 'inline' rather than referencing an existing definition. This feature can be used to create a unique action that is not reusable between action group definitions.
The action group config can also override or set display attributes for the group of actions to provide a consistent look-and-feel for a group of actions when displayed.
Action Group Config Elements
An example action group definition:
<action-group id='my_document_actions'>
<style-class>inlineAction</style-class>
<action idref='edit_doc_http' />
<action idref='checkin_doc' />
<action id='checkout_doc'>
<permissions>
<permission allow='true'>CheckOut</permission>
</permissions>
<evaluator>org.alfresco.web.action.evaluator.CheckoutDocEvaluator</evaluator>
<label-id>checkout</label-id>
<image>/images/icons/CheckOut_icon.gif</image>
<action-listener>#{CheckinCheckoutBean.setupContentAction}</action-listener>
<action>checkoutFile</action>
</action>
<action idref='edit_doc_webdav' hide='true' />
</action-group>
This example defines a group of actions with the id of my_document_actions. The group defines a display attribute which will override the style-class display attribute set on any of the actions. Then follows two action elements which reference existing definitions of actions by id - the Spring inspired idref attribute is used to reference the existing definitions. Finally an action is defined directly 'inline'. It is acceptable for the inline action ID to conflict with an existing action definition ID as it will always take precedence over any existing action definition with the same ID. Inline actions should generally only be used for cases where the action is totally specific to the group and never has a case for re-use by other action groups.
The set of configuration sub elements are defined below:
- action-group : The parent element defines a single action group. The mandatory id attribute defines the ID by which a JSF <r:actions /> component can reference a group. Defining another action-group element with the same ID as an existing action group effectively overrides the original group definiton. All other elements must be contained with the action-group element.
- show-link : A presentation attribute. Overrides any similarly named attribute set on grouped action definitions.
- style : A presentation attribute. Overrides any similarly named attribute set on grouped action definitions.
- style-class : A presentation attribute. Overrides any similarly named attribute set on grouped action definitions.
- action : References or defines and an action definition for the group. The order of these attributes defines the order of the actions for display. Action elements can must either use one of an idref attribute to reference an existing action definition as defined above, or an id attribute to define an 'inline' action specific to this action group definition. Existing actions can also be hidden by using the hide attribute in conjunction with idref.
Type Based Action Configuration
In Alfresco 2.1 we added support to configure groups of action by node type. This means it is possible to add new actions or hide actions for a specific folder or document type. The usual config evaluator+condition syntax is used. For example this config hides the Cut and Copy actions from WCM WebProject folder type in the web-client UI:
<config evaluator='node-type' condition='wca:webfolder'>
<actions>
<action-group id='space_browse'>
<show-link>false</show-link>
<action idref='cut_node' hide='true' />
<action idref='copy_node' hide='true' />
</action-group>
</actions>
</config>
Note that only 'type' conditions are supported, aspects are not supported as a condition for action group config.
Actions JSF Component
To build a JSP page that displays a list of actions, the <r:actions /> JSF component should be used. This component will display a group of actions referenced by group ID. In this example the action group called my_document_actions is referenced (as defined in the example config above) and the showLink component attribute is set to false to display a list of icons with no textual links:
<r:actions value='my_document_actions' context='#{BrowseBean.document}' showLink='false' />
An example that uses vertical rendering to display the actions as a vertical list of links and icons:
<r:actions value='my_document_actions' context='#{BrowseBean.document}' verticalSpacing='3' />
Note that the mandatory context attribute binds to a Node instance which provides the actionContext object for the action definitions.
