Adding Custom Aspect Support in Alfresco Share

cancel
Showing results for 
Search instead for 
Did you mean: 

Adding Custom Aspect Support in Alfresco Share

wabson
Active Member II
0 61 35.1K
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.
61 Comments
blog_commenter
Active Member
Hi Will,



Re Mary's problem May 17th, 2010 at 11:29 pm, i experienced the same and it seems that a line feed is required for the last property in knowledgebase.properties. The label appeared correctly after the addition.



This is a very helpful tutorial though, many thanks.
blog_commenter
Active Member
Hi, Will --



  Would you add the code needed to wire your new aspect into the Alfesco Explorer interface, please?  I tried to patch one together, but I'm not having much luck.



  I'm trying to use your cool example in Alfresco 4.0d, but Alfresco reports:



2012-04-23 01:45:59,483  ERROR [ui.common.Utils] [http-9090-1] Failed to create content due to error: 03230079 The aspect is invalid: {http://www.alfresco.com/model/knowledgebase/1.0}knowledgebase

org.alfresco.service.cmr.dictionary.InvalidAspectException: 03230079 The aspect is invalid: {http://www.alfresco.com/model/knowledgebase/1.0}knowledgebase



... without really explaining what it doesn't like -- or, more precisely, I don't know how to interpret these error messages.  What's the best way to validate an aspect's structure?



  Thanks for your help!



Don
blog_commenter
Active Member
Hi Will,



Great tutorial! I'm having problems adding the created aspect to the required folders in Alfresco Share. When I click Manage Aspects, select the desired aspect then Save, a message pops up saying 'Could not update aspects'. Any help would be much appreciated!
wabson
Active Member II
@Don - I won't be adding instructions for Alfresco Explorer here as the post is specifically about Share, but I would recommend you check out this page - http://wiki.alfresco.com/wiki/Data_Dictionary_Guide.



@Siona - it's likely that there's a problem with your Alfresco server or your custom model. Try posting to the Content Modelling forum - https://forums.alfresco.com/en/viewforum.php?f=5.
blog_commenter
Active Member
It's cool I got it sorted! Thanks for the reply and tutorial again Smiley Happy
blog_commenter
Active Member
I would like to add aspects on Alfresco 4.0.2

Can I use the instructions below or is there an other method required in this other version ?
wabson
Active Member II
The method should be unchanged for Alfresco 4, provided that you follow the 3.3-compatible steps.
blog_commenter
Active Member
Hi Will,

Really, a lot thanks for Your Post.

I'm working about share-config-custom.xml for workarround aspect inyection inside advanced-search.

Best regards from Spain ,

Frank
wabson
Active Member II
Glad you found it useful, thanks!
nwali
Established Member

Great post!

I am currently using Alfresco Community 5.0.d and All-in-one sdk, so I could not find the documents (kb-model and knowledge one's) as mentioned in your blog so could you let me know the instructions or blog for adding custom aspects in alfresco 5.0.d.

Thanks!

ddraper
Intermediate II

Nikhil Wali‌ You're better off asking questions like this in the main discussions thread (Alfresco ECM ) as more people are likely to see and respond to your question. This is a very old blog post and people are unlikely to spot this question, and therefore you're less likely to get a reply!