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.
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.
Most of the data webscript work is now handled by two Java classes:
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.
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.
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.
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:
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.
New to v4.0 <dependencies> section for defining custom client-side functionality and stylesheets.
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.
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.
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)
Unique template id
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.
Id of the line within the template. Must be unique within this template.
Optional index for ordering the lines when rendering.
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.
Optional evaluator to determine whether this line will be rendered for a node when using the template.
propertyName: 'renderer id',
renderer: function(record, label)
The rendering function should return properly escaped HTML.
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'.
Action config container element
Unique action id
Optionally override the icon name. If not set, the id is used.
The action's i18n message id.
Action parameter elements
Bean id of evaluator that determines whether the action is valid for this node or not.
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
Documents on the browse page
Document on the document details page
Folders on the browse page
Folders on the folder details page
Links to documents on the browse page
Links to documents on the document details page
Links to folders on the browse page
Links to folder on the folder details page
Action group config container element
Unique action group id
Reference to an action defined within the <actions> config area.
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.