Why? Cause custom constraints are only possible for properties – not for associations. Too bad as I had the constraint nearly implemented. *sigh* I would really appreciate it if Alfresco could implement this functionality also for associations. And by the way – could also a built-in constraint for subfolder-selections be integrated? This would make my work-around unnecessary.

However, while the custom constraint thing didn’t work, I managed to implement a comparable functionality to the built-in category browsing for my custom categories: I implemented a Behavior that creates respectively removes links in the linked to custom category folder. This allows to browse for documents by browsing the custom-category folders. And this is easily possible from within share through the new Repository Link. :) Stay tuned – a tutorial will soon be published on this blog.

PS: Is there someone else having a similar use-case than I have? How do or would you solve it?

Problem Description

Often, properties need to be protected from duplicate values due to misspelling or ambiguity. A common solution is to let users select from a predefined list which can easily be done in Alfresco using the list constraint. However, somtimes you also need the flexibility to define the options during runtime which means that you either need a combobox (opposed to a drop-down list) or a way to implement dynamic lists which are populated during runtime and obtain their values from a runtime configurable source. While comboboxes are not supported at all by Alfresco Jean Barmash proposes a good solution for dynamic lists based on a Lucene search.

However, sometimes a flat list just doesn’t meet the requirements as you might need to be able to select your values from a hierarchical structure. While you would be able to use the built-in category functionality of Alfresco this would not allow you to assign properties a specific kind of category respectively restrict the selectable values.

An example for such a need (which will also be used as an example for this tutorial) is an aspect that defines the place where a document is physically filed (for instance to define that your fire insurance policy is filed in the accountancy office in the suspension files of Ms. Brown’s desk within the folder insurances: Accountancy Office / Desk Ms. Brown / Suspension Files / Folder Insurances).

Proposed Solution

The solution described in this tutorial uses a folder structure to define custom categories and a custom control template to render a UI element which restricts the selection of the value(s) to this structure. The value itself is thereby an association to the selected folder(s).

This solution offers a comparable functionality to the built-in categories of Alfresco. However, it does not offer the possibility to browse through the categories so far. This would need scripts that automatically create links within the associated folders and is not covered within this tutorial. Advantages of this solution opposed to the built-in categories are:

• Categories can be defined for specific types or aspects.
• More than one category property can be defined which is restricted to a specific kind of category.
• Single and multiple value selection is possible.
• Custom categories can be directly managed from within share (using the share repository document library of Alfresco 3.2 EE / 3.3 CE).
• Categories can easily be moved with an immediate effect on the associated documents. In our example you could for instance move a (physical) folder to another room and represent that change by also moving the folder within Alfresco. All documents within this folder will automatically represent this change.

Please note: Within this tutorial, the restriction of values to a specific kind of category is reached only by restricting the UI. However, this restriction can be cross checked server-side and configured directly within the content model using a custom constraint.

Tutorial

The following tutorial will show the main steps, code snippets and screenshots to implement a custom aspect for defining the place of physically filed documents. It is assumed that you have first experiences in defining a custom data model. Thus these steps will be explained rather quickly. However, feel free to ask questions in the comments if there is something that you do not understand.

Please mind that I’m not a native speaker and that I’m using a customized Alfresco 3.3 CE with the german language pack (unfortunately still of version 3.2 CE). Thus the screenshots might look a little bit odd to you. Anyhow, I’m pretty sure they will support your comprehension. Thank you for your understanding.

Creating the Custom Category Folder Structure

This is probably the most simple step of this tutorial. Create a main folder which will hold all custom categories of your company. I chose to create a folder called Company Categories within the root folder of the repository (Company Home).

Now create a folder for the filing places structure (called Ablageort in the screenshot) within this folder and herein in turn one folder for each filing place you have.

Adding the Filed Aspect

Will Abson describes how to add a custom aspect and enable it in share in this blog post. Following is the definition of the filed aspect as it is defined in the something-model.xml (kb-model.xml in Will Abson’s blog post):

<!-- Filed Aspect -->
<aspect name="cl:filed">
   <title>Filed</title>
   <associations>
      <association name="cl:place">
         <title>Place</title>
         <source>
            <mandatory>false</mandatory>
            <many>true</many>
         </source>
         <target>
            <class>cm:folder</class>
            <mandatory>false</mandatory>
            <many>false</many>
         </target>
      </association>
   </associations>
</aspect>

As you can see, we define the filing place as an association to one folder. For other custom categories you might want to allow the selection of multiple values. Therefore you need to change the <many> tag of the association’s <target> definition to true.

Defining a Custom Control Template

Now that we have an aspect allowing us to reference a folder as a filing place we need a custom control template which renders us a UI element for selecting the specific place from out filing places structure. Unfortunately, the association picker Alfresco uses per default for selecting an association does not allow to restrict the selection of an association’s target. It would rather allow to select any folder and would further start the process of selection in the repository root folder. Thus, we have to implement this functionality ourselves.

The freemarker template used for rendering the association UI element is alfresco/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/form/controls/association.ftl. This template uses the JavaScript ObjectFinder which is indirectly referenced through the picker.inc.ftl template from the common subfolder. The ObjectFinder itself is defined in alfresco/tomcat/webapps/share/components/object-finder/object-finder.js.

In order to customize how the association picker is rendered we would have to either duplicate or overwrite these files, whereas both would be quite ugly solutions. However, we can apply a trick to inject our customization during runtime. This solution leaves us with duplicating and adjusting only one file: association.ftl. For convenience I upoaded the adjusted file: category_association.ftl. This file needs to be placed in alfresco/tomcat/shared/alfresco/web-extension/site-webscripts/. Following I will describe the adjustments I made:

Render only folders starting with the custom categorie’s root folder

In order to skip the rendering of folders above the one holding our specific custom categories we need to tell the object picker to start within this folder and further to forget all folders which are above. The first can easily be done by setting the corresponding option:

<#if field.control.params.startWithinSelectedCategory?exists>
   <#if field.value != "">
parentNodeRef: "${field.value}",
   <#else>
parentNodeRef: "${field.control.params.parentNodeRef}",
   </#if>
<#else>
parentNodeRef: "${field.control.params.parentNodeRef}",
</#if>
parentNodeRef: "${field.control.params.parentNodeRef}",
</#if>

The nested if-statements thereby allows to configure whether to start within a previously selected category folder or not. This is done by setting the startWithinSelectedCategory option. The category’s root folder is configured in the parentNodeRef property. More on configuring the UI widget later.

In order to tell the object picker to forget about the parent folders we need to change the json-object delivered by the server-side WebScript. This can be done in the onParentDetails function which we therefore replace with a custom version which in turn passes a tailored version of the json-object to the original function:

<#if field.control.params.numberOfHiddenLayers?exists>
// place a custom function before the execution of the onParentDetails-function
Alfresco.ObjectFinder.prototype.onParentDetailsOriginal = Alfresco.ObjectFinder.prototype.onParentDetails;
Alfresco.ObjectFinder.prototype.onParentDetails = function(layer, args)
{
   // cut the last x parent elements
   var counter = 0;
   cut = function(node)
   {
      if (node.parent)
      {
         cut(node.parent);
         if (counter < ${field.control.params.numberOfHiddenLayers})
         {
            delete node.parent;
            counter = counter + 1;
         }
      }
   }
   cut(args[1]);
   // call the original function with the modified args-parameter
   this.onParentDetailsOriginal(layer, args);
};
</#if>

The numberOfHiddenLayers parameter needs to be configured and should always represent the number of folders above the category’s root folder.

Display the full path of the custom category

In some cases you want to display the full path of the selected value(s). In our example this means to show “Accountancy Office / Desk Ms. Brown / Suspension Files / Folder Insurances” instead of just “Folder Insurances” (which would be the default behaviour). Therefore, we again inject a custom method – this time the name of the selected item(s) is temporarily replaced with the full path, the original render method called and the item(s) renamed again:

<#if field.control.params.showFullPath?exists>
// place a custom function before the execution of the onRenderCurrentValue-function
Alfresco.ObjectFinder.prototype.onRenderCurrentValueOriginal = Alfresco.ObjectFinder.prototype.onRenderCurrentValue;
Alfresco.ObjectFinder.prototype.onRenderCurrentValue = function(layer, args)
{
   // temporarily replace the names with the fully qualified names
   var items = this.currentValueMeta;
   var nameMap = new Array();
   for (var i = 0, ii = items.length; i < ii; i++)
   {
      var item = items[i];
      var name = item.name;
      // add path to name except the last x path elements
      var pathElements = (item.displayPath + "/" + name).split("/");
      // we need to remove two more elements than configured:
      // 1st: the leading slash from item.displayPath leads to an empty element in the array
      // 2nd: we do not want to show the category name inside the path
      pathElements.splice(0,${field.control.params.numberOfHiddenLayers} + 2);
      item.name = pathElements.join(" / ");
      // save original name later restore
      nameMap[item.name] = name;
   }
   // call the original function to render the names
   this.onRenderCurrentValueOriginal(layer, args);
   // reset the names
   for (var i = 0, ii = items.length; i < ii; i++)
   {
      items[i].name = nameMap[items[i].name]
   }
}
</#if>

Other adjustments

For Version 3.3 CE I needed to check whether the field really exists as otherwise an exception would have been thrown:

<#if field.endpointType?exists>
...
</#if>

The reason for this is that Alfresco 3.3 renders the property as soon as a property with a custom control template is defined for a form. It does not check whether the property exists on this document (meaning whether for instance the filed aspect is set for this document or not). However, I did not encounter this behaviour on Alfresco 3.2 CE.

Last we need to adjust the path to the original picker.inc.ftl template as our custom template resides in a different place:

<#include "org/alfresco/components/form/controls/common/picker.inc.ftl" />

Configuring Share to use the Custom Control Template

Having a custom control template we can now tell share to use this for displaying and selecting custom categories. This is generally done in the share-config-custom.xml file as described in Will Abson’s blog post. The difference is that we define to use our custom control template for rendering the according UI element:

<field id="cl:place" label-id="label.cl_place" >
   <control template="/category_association.ftl" >
      <control-param name="parentNodeRef">workspace://SpacesStore/c98ddef6-1cc8-489d-aab6-5aab2f889e61</control-param>
      <control-param name="numberOfHiddenLayers">2</control-param>
      <control-param name="startWithinSelectedCategory" />
      <control-param name="showFullPath" />
   </control>
</field>

The control parameters are (compare paragraph Defining the Custom Control Template):

• parentNodeRef: Defines the root folder of the specific category.
• numberOfHiddenLayers: Defines the depth of the root folder and thus the number of folders or layers that need to be suppressed.
• startWithinSelectedCategory: If set, the UI element will start browsing the custom categories within the previously selected category (in case a value is already set).
• showFullPath: If set, the UI element will show the full path of the custom category.

The URL of the custom category’s root folder is the Alfresco Node Reference which is linked on the folder’s details page in Alfresco Explorer respectively the last part of the URL (after ?nodeRef=) of the folder’s detail page in Alfresco Share.

Conclusion

Defining a custom control template and injecting custom methods into the object finder seems to be a suitable solution for the described problem. However, sometimes a combobox might be the better solution and hopefully Alfresco will support this some day. What do you think? Do you have any other idea how this could be solved? Please let me know!

Hope you will return soon!

Cheers
Chris

PS: How do you like the logo and the design in general?