Share Document Library Extensions in v4.0

You may have heard already about Share v4.0 (codenamed “Swift”) and the excellent work that has been done allowing the Surf components to be extended, customized and overridden. If you haven’t, I highly recommend David Draper’s blog for in-depth information.

This post is the first in a series covering the extensions specifically to the Document Library components within Share.

Before version 4.0, adding and customizing actions and other parts of the Document Library was more complex than we would have liked. Actions, for example, required overrides to at least four webscripts, plus client-side JavaScript and CSS. One of the goals for 4.0 was to give developers, partners and implementors the ability to customize & extend the Share Document Library without having to either write or duplicate large amounts of code. This would also allow the Web QuickStart and Records Management modules to be fully isolated from “core” Share code.

Repository tier changes

A number of changes have been made to the Repository tier (data) webscripts:

In order to preserve existing customizations and third party add-ons, a parallel set of data webscripts were developed rather than replacing the existing ones. The new set of webscripts, imaginatively labelled “documentlibrary-v2″ are used by the Share Document Library now; but are no longer called directly (see later). We still have an evaluator.lib.js, but it’s job is greatly reduced to handling Working Copies and File- and Folder-Links and should no longer need to be overridden. These new webscripts can be found in the remote-api project and have URLs starting with /slingshot/doclib2/.

All node properties & aspects are returned by the data webscripts now. This will make it easier to display custom model properties and also key behaviours off marker aspects.

Custom property decorators are employed to augment properties that by themselves are of little use to a user interface. Such examples include nodeRef properties (tags, categories) and usernames (where we would like to display the full name).

Lucene queries are no longer used for path-based navigation; instead calls are made directly to the FileFolderService (via ScriptNode) where they can take advantage of the recent performance enhancements.

Web tier changes

A more extensive set of changes has been made to the web tier (presentation) webscripts within the share.war:

Config definitions for actions now appear ONCE in Share config, rather than across several component webscripts.

Status indicators are defined via configuration.

Metadata templates can now be defined for easier custom property rendering on the main Document List page.

Actions have been redefined in a much more configurable way and have also been regrouped into type- and view-based groups, rather than type- and state-based.

It is also much easier now to define custom client-side extensions, including a specific API for defining custom renderers and action handlers.

Repository Tier

Document Library Custom Response

A custom response appears within the metadata.custom section of the JSON response. An example of a cleanly installed service is the vtiServer configuration, defined within the slingshot-context.xml file.

The customResponses property defines a map of JSON key to custom response bean within the SlingshotDocLibCustomResponse bean definition.

The VtiServerCustomResponse class (which implements CustomResponse) returns a Serializable object (e.g. LinkedHashMap) that is serialized into the JSON response by the DocLib webscripts.

This extension point is designed to return useful information that is not specific to any node, for example the presence of an optional module; whether a subsystem is active or not, etc.

Property Decorators

The other place the data webscripts may be extended is via the property decorator extension mechanism. These are utilized by the org.alfresco.repo.jscript.ApplicationScriptUtils class and allow properties such as nodeRefs, usernames and dates to be returned in a much more usable state to the web tier. For example, the Share interface displays usernames using First- and Last-name, rather than just the username. By decorating the properties returned in the initial webscript request, further requests are not necessary to obtain the missing data.

The decoratedProperties property defines a map of short-format QName to decorator implementation bean. Each of these decorator beans implements the PropertyDecorator interface and returns a serializable map via the decorate() method. This map is then serialized into the JSON response for each node being returned by the webscript request.

Permissions List

The third place the data webscript response may be extended is via the list of permissions that are returned for each node. These are defined via the userPermissions property on the applicationScriptUtils bean, i.e.

The default set of permissions should not be reduced without fully understanding the impact on actions, indicators and metadata evaluators already in use throughout Share.

Web Tier

In versions of Share previous to v4.0, the client-side JavaScript requested JSON data from the Repository directly via the proxy servlet. From v4.0, there is a new data webscript (at /components/documentlibrary/data/) which requests data from the Repository, processes the response based on a configurable set of evaluators before finally returning JSON data to the browser.

All configuration for, and evaluation of, Document Library status indicators, metadata templates and actions is now on the web tier instead of split between the Repository and the browser.

Web Tier Configuration Overview

The individual action configuration files (e.g. documentlist.get.config.xml, document-details.get.config.xml) have been removed and all actions are now defined within common, easily overridable config sections.

The new or altered areas of configuration in share-documentlibrary-config.xml are:

Section

Description

DocumentLibrary

Updated for v4.0 New <indicators> section for configuring status indicators. New <metadata-templates> for configuring the metadata displayed within the Document Library’s “browse” view.

DocLibCustom

New to v4.0 <dependencies> section for defining custom client-side functionality and stylesheets.

DocLibActions

New to v4.0 <actions> section defining all available actions across the various Document Library view pages. <actionGroups> which define which (and in what order) actions are to appear on the Document Library pages.

Status Indicators

Defined within the DocumentLibrary config section, status indicators are small icons typically used to indicate the presence of a marker aspect, or whether a document is in a particular state, e.g. checked out for editing.

Indicator images by default are referenced by id:

/res/components/documentlibrary/indicators/{id}-16.png

unless the name is overridden by the “icon” attribute.

Tooltip labels are also defaulted by id:

status.{id}

and can be overridden by the “label” attribute.

Configuration

Element

Description

<indicators>

Parent element

<indicator>

Status indicator element.

Attributes

id

Unique indicator id

index

Determines display order of this indicator

icon

Icon filename. If not specified, “id” is used

label

Tooltip i18n label. If not specified, “id” is used.

<evaluator>

Bean id of evaluator that determines the visibility of the image.Evaluator extends org.alfresco.web.evaluator.BaseEvaluator

<labelParam>

Status indicator element.

Attributes

id

Unique indicator id

index

Determines display order of this indicator

icon

Icon filename. If not specified, “id” is used

label

Tooltip i18n label. If not specified, “id” is used.

<override>

Allows this indicator to override (hide) other indicators which would otherwise be visible. The value is the id of another indicator to override.

A note about the labelParam value: refactoring on the client-side (JavaScript code) means that a common helper object is available for each node within the Document Library during the rendering cycle, namely “jsNode“. A full reference for this new resource is published on the Alfresco wiki.

Metadata Templates

The metadata template refers to the section of the document “browse” page under the filename. New functionality in v4.0 allows this area to be customized with node properties and/or by custom rendering functions.

In a clean install, there are two templates defined: the default (fallback) template and one used when rendering working copies. These are both defined within share-documentlibrary-config.xml and can be extended or overridden as required (via share-config-custom.xml)

Configuration

Element

Description

<metadata-templates>

Parent element

<template>

Template element

Attributes

id

Unique template id

<evaluator>

Bean id of evaluator that determines whether the template is to be used for this node or not. Evaluators have no effect on the default template.

Evaluator extends org.alfresco.web.evaluator.BaseEvaluator

<line>

Allows placeholder values within i18n label to be replaced at runtime with node properties. The value refers either to a node property (e.g. cm_description) or a custom JavaScript renderer. To add a label in front of the property, add the label’s i18n messageId after the property value, separated by a space; e.g. {cm_description details.description}

Attributes

id

Id of the line within the template. Must be unique within this template.

index

Optional index for ordering the lines when rendering.

view

If set to “simple” or “detailed” then this line will only be rendered when either the simple or detailed view is toggled on respectively. Leave empty, or omit the attribute for both views.

evaluator

Optional evaluator to determine whether this line will be rendered for a node when using the template.

Custom JavaScript Renderers

A renderer can either be a simple property value, or use a custom JavaScript renderer. To register a custom renderer, fire a Bubbling (global) event, passing-in the renderer id and the rendering function:

Actions

In versions previous to v4.0, the actions configuration was spread throughout a number of webscript XML config files. From v4.0, actions are all now defined globally in the share-documentlibrary-config.xml file, in the “DocLibActions” config section. This means they can be overridden and extended via a share-config-custom.xml file. These customizations can be via AMP, JAR or web-extension folder mechanism, or a mixture of all three.

Actions are also now grouped by view type instead of node “state”.

Configuration

Element

Description

<actions>

Parent element

<action>

Action config container element

Attributes

id

Unique action id

type

Action type. Currently supported are: javascript, link, pagelink

icon

Optionally override the icon name. If not set, the id is used.

label

The action’s i18n message id.

<param>

Action parameter elements

Attributes

name

Parameter name

<evaluator>

Bean id of evaluator that determines whether the action is valid for this node or not.

Evaluator extends org.alfresco.web.evaluator.BaseEvaluator

Attributes

negate

If set to “true” the output of the evaluator is inverted

<permissions>

Permission config container element

<permission>

List of permissions required for the action, as defined in the applicationScriptUtils bean config.

Attributes

allow

If the permission is to specify the action is allowed

deny

If having the permission means the action should be hidden

Note: only one of “allow” or “deny” should be specified and set to “true”

<override>

If this action should override the visibility of other actions, they are specified using this element.

Action Groups

Actions are grouped using the actionGroup elements. The type of node and also the view currently in use determines the actual group used. The group is calculated by the calculateActionGroupId() function in surf-doclist.lib.js and is designed to be overridden if many new and/or altered actions are required (e.g. Records Management).

The action groups defined in a default installation are:

Action Group Id

Default usage

document-browse

Documents on the browse page

document-details

Document on the document details page

folder-browse

Folders on the browse page

folder-details

Folders on the folder details page

document-link-browse

Links to documents on the browse page

document-link-details

Links to documents on the document details page

folder-link-browse

Links to folders on the browse page

folder-link-details

Links to folder on the folder details page

Configuration

Element

Description

<actionGroups>

Parent element

<actionGroup>

Action group config container element

Attributes

id

Unique action group id

<action>

Reference to an action defined within the <actions> config area.

Attributes

id

Reference to action as defined in <actions> config section above.

Other action properties are overridable here, although it is recommended from a maintenance point of view to only override “simple” properties like the icon and label. These make is possible to re-use an action with document-biased icon and label to be used for folders.

Post navigation

15 thoughts on “Share Document Library Extensions in v4.0”

In the ftl-files if you use the directive the correct versions of the css and js files will be choosen in runtime (minified or not). Will this happen as well for the tag in the configuration described last in this article?

At the moment, we don’t automatically add “-min” when not in debug mode for resources configured via the dependencies tag, simply so that we’re consistent across Share (i.e. Forms and Surf Extensibility). We have some interesting internal development going on right now around client-side asset compression though, so hopefully it’s something that will be solved soon (potentially v4.1)

You don’t always have to create a new evaluator, no. Your action might apply to every folder, in which case you need no evaluator at all. If you only want your action to appear when the folder has certain aspects applied, or is of a certain type for example then you will need a new evaluator – but you will only need the spring config, not code. The last case is if you need your action to appear in very special circumstances only, in which case you may also need to write a new evaluator class.

Within the jar file, create a META-INF folder – as long as you include those assets in the dependencies section, or address them using the /res/ servlet they will be picked up there.
You can create subfolders under META-INF so, for example:META-INF/custom/exif.js
can be addressed via

I need to do some customization on “edit Offline”. When we click It download the working copy with the file name (working copy) in our local system. and Same thing when we upload the new version it takes the (working copy) as upload file.

Now, I am trying to customized it, Say when we download It should download the file with file name (current version) in our local system . and same time when we upload the new version it should look for the (version copy) only.

I am unable to figure out which files I need to change for above customization. Please help.

Hi Mike!
I am using alfresco community Edition 4.0 d
Can you just tell me how document edit properties work?
I want to know which action link is called ?
I also want to know which client side js is used and also about the webscript.
If you have any idea please reply as early as possible.