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:

  1. 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/.
  2. 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.
  3. 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).
  4. 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:

  1. Config definitions for actions now appear ONCE in Share config, rather than across several component webscripts.
  2. Status indicators are defined via configuration.
  3. Metadata templates can now be defined for easier custom property rendering on the main Document List page.
  4. 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

Most of the data webscript work is now handled by two Java classes:

   org.alfresco.repo.jscript.SlingshotDocLibCustomResponse
   org.alfresco.repo.jscript.ApplicationScriptUtils

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.

<bean id="slingshotDocLibCustomResponse"
      parent="baseJavaScriptExtension"
      class="org.alfresco.repo.jscript.SlingshotDocLibCustomResponse">
   <property name="extensionName">
      <value>slingshotDocLib</value>
   </property>
   <property name="customResponses">
      <map>
         <entry key="vtiServer">
            <ref bean="doclibCustomVtiServer"/>
         </entry>
      </map>
   </property>
</bean>

The bean for returning the vtiServer configuration is defined as:

<bean id="doclibCustomVtiServer" class="org.alfresco.repo.jscript.app.VtiServerCustomResponse">
   <property name="port">
      <value>${vti.server.external.port}</value>
   </property>
   <property name="host">
      <value>${vti.server.external.host}</value>
   </property>
   <property name="sysAdminParams">
      <ref bean="sysAdminParams" />
   </property>
</bean>

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.

<bean id="applicationScriptUtils" parent="baseJavaScriptExtension" class="org.alfresco.repo.jscript.ApplicationScriptUtils">
   <property name="decoratedProperties">
      <map>
         <entry key="cm:creator">
            <ref bean="usernamePropertyDecorator"/>
         </entry>
         <entry key="cm:modifier">
            <ref bean="usernamePropertyDecorator"/>
         </entry>
         ...

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.

<property name="userPermissions">
   <list>
       <value>CancelCheckOut</value>
       <value>ChangePermissions</value>
       <value>CreateChildren</value>
       <value>Delete</value>
       <value>Write</value>
   </list>
</property>

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.

Also new to v4.0 is the slingshot-documentlibrary-context.xml file containing all bean definitions for web tier evaluators. Please see the Alfresco wiki for a full reference of the out-of-the-box evaluators.

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.

Status Indicators

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.

Example Configuration

<indicator id="google-docs-locked" index="10">
   <evaluator>evaluator.doclib.indicator.googleDocsLocked</evaluator>
   <labelParam index="0">{jsNode.properties.owner.displayName}</labelParam>
   <labelParam index="1">{jsNode.properties.owner.userName}</labelParam>
   <override>locked</override>
</indicator>

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)

Metadata

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.

Example Configuration

<template id="isPhoto">
   <evaluator>evaluator.doclib.metadata.hasExif</evaluator>
   <line index="10" id="date" view="detailed">{date}{size}</line>
   <line index="20" id="exposure" evaluator="evaluator.doclib.metadata.hasExposure">
      {exposure exif.label.exposure}
   </line>
   <line index="30" id="description" view="detailed">{description}</line>
   <line index="40" id="social" view="detailed">{social}</line>
</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:

if (Alfresco.DocumentList)
{
   YAHOO.Bubbling.fire("registerRenderer",
   {
      propertyName: "renderer id",
      renderer: function(record, label)
      {
         return "...";
      }
   });
}

The rendering function should return properly escaped HTML.

 

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”.

Actions

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.

Example Configurations

<!-- Inline edit -->
<action id="document-inline-edit" type="pagelink" label="actions.document.inline-edit">
   <param name="page">inline-edit?nodeRef={node.nodeRef}</param>
   <permissions>
      <permission allow="true">Write</permission>
   </permissions>
   <evaluator>evaluator.doclib.action.inlineEdit</evaluator>
</action>
<!-- Checkin from Google Docs -->
<action id="document-checkin-from-googledocs" type="javascript" label="actions.document.checkin-google">
   <param name="function">onActionCheckinFromGoogleDocs</param>
   <evaluator>evaluator.doclib.action.googleDocsCheckIn</evaluator>
   <override>document-checkout-to-googledocs</override>
</action>
<!-- View in Explorer client -->
<action id="view-in-explorer" type="link" label="actions.folder.explorer-view">
   <param name="href">{explorerViewUrl}</param>
   <param name="target">_blank</param>
   <evaluator>evaluator.doclib.action.viewInExplorer</evaluator>
</action>

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.

Example Configuration

<actionGroup id="folder-browse">
   <action index="100" id="folder-view-details" />
   <action index="110" id="document-edit-properties" icon="folder-edit-properties" label="actions.folder.edit-metadata" />
</actionGroup>

Custom Client Extensions

The DocLibCustom config section is where dependencies on custom client-side assets can be defined. These are defined in exactly the same way as for custom Forms dependencies.

Configuration

Element Description
<dependencies> Parent element
<css> Stylesheet dependencies element

Attributes
src Path to the css file, relative to the /res servlet.
<js> JavaScript dependencies element

Attributes
src Path to the js file, relative to the /res servlet.

Example Configuration

<dependencies>
   <css src="/custom/my-customization.css" />
   <js src="/custom/my-customization.js" />
</dependencies>

Future Articles

I’ll be publishing some override and extension examples as well as covering client-side template and action extensions.

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

  1. Erik Billerby

    Hi,

    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?

    Thanks for a nice blog post.
    /Erik

    Reply
  2. Erik Billerby

    Hmm, my comment got obfuscate, (we are talking metalevel here since I’m dicussing an obfuscating library ;)

    I’m refering to the “script directive in freemarker using the “at”-character.

    Thanks.
    /Erik

    Reply
  3. mikeh Post author

    Hi Erik

    Sorry for the over-eager comment obfuscation!

    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)

    Thanks for your comments!
    Mike

    Reply
  4. pluss19x

    Hello is there a way to extend the info banner? As it’s done with the working copy indicator : “This document is locked by you for offline editing.”

    Reply
    1. mikeh Post author

      Hello – and apologies that I did not see your comment until now (we have very active spam management on here)

      The next version of Community will indeed have this feature (4.0.e) via a “banner” element within the “metadata-template” config section.

      Reply
  5. Silverio

    Hi Mike,

    if i have to create a new action on Share 4, I always create a new evaluator? Practically my action creates a simple test file in a folder.

    Reply
    1. mikeh Post author

      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.

      Thanks,
      Mike

      Reply
  6. Silverio

    HI mike,

    thanks for the reply, I guessed something like that.

    I wrote an action to help you learn the new system Alfresco 4 that should only create an empty file into a folder. I arrived at the configuration of share-config-custom.xml.

    onActionSimpleRepoAction
    create-file
    message.create-file.success
    message.create-file.failure

    And ‘an action that does not even use the client-side javascript, so you say that here I have not put any evaluator? I can also delete the javascript?

    Reply
  7. Rudyanto

    Hi Mike,

    In Document Library Item List, default Alfresco Installation will show the following metadata: Modified On, Modified By, Version, Size, Description and Tags.

    Could you tell how to add one more metadata eg. Author to show up? Which xml files should I reconfigure?

    Best Regards,
    Rudyanto

    Reply
    1. mikeh Post author

      That’s the Metadata Template example above. It’s all configurable in share-config-custom.xml. Post what you’ve tried to the forums and I’ll try to help you there.

      Thanks,
      Mike

      Reply
  8. mrksjs

    hey!

    thanks for the examples. i am having trouble with running it.

    in which folder do i need to put the exposure script ‘exif.js’
    the example say the dependency should look like this. also docs.alfresco.

    but where is it? whats the absolute (full) path for this file??

    thanks for your help

    Reply
    1. Mike Hatfield Post author

      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


      <config evaluator="string-compare" condition="DocLibCustom">
      <dependencies>
      <js src="/custom/exif.js" />
      </dependencies>
      </config>

      Thanks,
      Mike

      Reply
  9. navtan

    Hi Mike,

    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.

    Reply
  10. rutaveej

    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.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>