Since Alfresco 3.2 introduced the ability to configure the metadata forms used in the Document Library, there have been several good articles published on how to add support for custom document types.
One of the first questions people often ask when they see Share is how they can easily extend the metadata fields that are stored against a document. Whilst this can be done using custom document types, aspects often provide a more agile solution.
So this article should explain how Share can be easily extended to support custom aspects using good practice techniques, specifically
- Ensuring all extended configuration is placed outside of the share webapp, so protecting it from upgrades and redeployments, and
- Using i18n labels for all text strings that appear in the UI, thus allowing translation of the labels.
The example provides a number of files, all of which should be placed below the tomcat/shared/classes directory of your Alfresco installation. If you are not using the Alfresco-bundled version of Tomcat then you may need to create this directory yourself and configure Tomcat’s shared classloader to use it.
First you will need to configure the repository with your custom model definition. In my case I am using a simple knowledge base model that defines a single aspect kb:referencable. The aspect adds a new text property that allows a unique KB reference number to be added to documents.
First, the Spring configuration defined in alfresco/extension/kb-model-context.xml
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<!-- Registration of new models -->
<bean id="extension.kb.dictionaryBootstrap" parent="dictionaryModelBootstrap" depends-on="dictionaryBootstrap">
<property name="models">
<list>
<value>alfresco/extension/kb-model.xml</value>
</list>
</property>
</bean>
<bean id="extension.kb.resourceBundle" class="org.alfresco.i18n.ResourceBundleBootstrapComponent">
<property name="resourceBundles">
<list>
<value>alfresco.messages.knowledgebase</value>
</list>
</property>
</bean>
</beans>
Then, define the model itself in alfresco/extension/kb-model.xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- Definition of Knowledge Base Model -->
<model name="kb:knowledgebase" xmlns="http://www.alfresco.org/model/dictionary/1.0">
<!-- Optional meta-data about the model -->
<description>Knowledge Base Model</description>
<author>Will Abson</author>
<version>1.0</version>
<!-- Imports are required to allow references to definitions in other models -->
<imports>
<!-- Import Alfresco Dictionary Definitions -->
<import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d"/>
<!-- Import Alfresco Content Domain Model Definitions -->
<import uri="http://www.alfresco.org/model/content/1.0" prefix="cm"/>
</imports>
<!-- Introduction of new namespaces defined by this model -->
<namespaces>
<namespace uri="http://www.alfresco.com/model/knowledgebase/1.0" prefix="kb"/>
</namespaces>
<aspects>
<!-- Definition of new Content Aspect: Knowledge Base Document -->
<aspect name="kb:referencable">
<title>Knowledge Base Referencable</title>
<properties>
<property name="kb:documentRef">
<type>d:text</type>
</property>
</properties>
</aspect>
</aspects>
</model>
The last file in our model definition adds some i18n labels for the aspect and property names. Add the following content to the file alfresco/messages/knowledgebase.properties.
# Custom knowledge base messages kb_knowledgebase.property.kb_documentRef.title=KB Reference kb_knowledgebase.aspect.kb_referencable.title=Knowledge Base Referencable aspect.kb_referencable=Knowledge Base Referencable
With the model added the repository should start up without errors and will know about the new aspect. In order to use it, we need to configure Share to show this aspect in the Manage Aspects dialogue and to display the KB Reference field in forms, when a node has the aspect applied.
The file alfresco/web-extension/share-config-custom.xml can be used to do both these things.
<alfresco-config>
<!-- Document Library config section -->
<config evaluator="string-compare" condition="DocumentLibrary">
<!--
Used by the "Manage Aspects" action
For custom aspects, remember to also add the relevant i18n string(s)
cm_myaspect=My Aspect
-->
<aspects>
<!-- Aspects that a user can see -->
<visible>
<aspect name="cm:generalclassifiable" />
<aspect name="cm:complianceable" />
<aspect name="cm:dublincore" />
<aspect name="cm:effectivity" />
<aspect name="cm:summarizable" />
<aspect name="cm:versionable" />
<aspect name="cm:templatable" />
<aspect name="cm:emailed" />
<aspect name="emailserver:aliasable" />
<aspect name="cm:taggable" />
<aspect name="app:inlineeditable" />
<aspect name="kb:referencable" />
</visible>
<!-- Aspects that a user can add. Same as "visible" if left empty -->
<addable>
</addable>
<!-- Aspects that a user can remove. Same as "visible" if left empty -->
<removeable>
</removeable>
</aspects>
</config>
<!-- cm:content type (existing nodes) -->
<config evaluator="node-type" condition="cm:content">
<forms>
<!-- Default form configuration used on the document details and edit metadata pages -->
<form>
<field-visibility>
<show id="kb:documentRef" />
</field-visibility>
</form>
<!-- Document Library pop-up Edit Metadata form -->
<form id="doclib-simple-metadata">
<field-visibility>
<show id="kb:documentRef" />
</field-visibility>
<edit-form template="../documentlibrary/forms/doclib-simple-metadata.ftl" />
</form>
<!-- Document Library Inline Edit form -->
<form id="doclib-inline-edit">
<field-visibility>
<show id="kb:documentRef" />
</field-visibility>
</form>
</forms>
</config>
</alfresco-config>
This configuration will add the KB reference field at the bottom of the main Edit Metadata form, the pop-up edit form used in the document list view and lastly the in-line edit form used for HTML, text and XML content (introduced in Alfresco 3.3).
Note: More advanced control is possible over the placement of the field within the form, but this requires copying over the full form definitions for the cm:content type from the file alfresco/web-framework-config-commons.xml (or alfresco/share-form-config.xml in 3.3 onwards) inside the Share webapp and adding the attribute replace="true" on the <config> element.
Now that you’ve configured Share, you must restart Tomcat so that the changes are picked up. The application should start up and you should be able to add the aspect to some content and see the document reference field appear in forms.
The last thing to do is to add an i18n label for the Knowledge Base aspect in the Manage Aspects dialogue. To do this we need to define a small bit of Spring configuration in the file alfresco/web-extension/custom-slingshot-application-context.xml, which will wire the knowledgebase.properties file we created earlier into Share.
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<!-- Add Knowledge Base messages -->
<bean id="webscripts.kb.resources" class="org.springframework.extensions.surf.util.ResourceBundleBootstrapComponent">
<property name="resourceBundles">
<list>
<value>alfresco.messages.knowledgebase</value>
</list>
</property>
</bean>
</beans>
In versions prior to Alfresco 3.3 (when some changes were made to the Share resource bundle classes) the following configuration must be used instead (note the different class name)
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<!-- Add Knowledge Base messages -->
<bean id="webscripts.kb.resources" class="org.alfresco.i18n.ResourceBundleBootstrapComponent">
<property name="resourceBundles">
<list>
<value>alfresco.messages.knowledgebase</value>
</list>
</property>
</bean>
</beans>
This configuration tells Share to look in the file knowledgebase.properties for aspect labels, in addition to the core message bundles.
With that file added you should be able to restart Tomcat again and see the correct label in the Manage Aspects dialogue. You’ve now fully-customised Alfresco Share to support additional custom aspects.
Update: Thanks to Brian Ochs, who pointed out that the additional message aspect.kb_referencable is also required in knowledgebase.properties.
Update: The configuration files in this tutorial can now be downloaded in ZIP format. To use them directly extract the archive into tomcat/shared/classes and restart the server. Please do not use these files, which are now outdated.
