erikwinlof

Add, remove or replace components on Share's Document Details page

Blog Post created by erikwinlof on Nov 9, 2011

Introduction



.


In Alfresco Community 4.0.a we included a lot of customization improvements to Share. One of them was to be able to swap out components on a page. This means that you can:






  • Add new components to a page


  • Remove a components from a page


  • Replace a component on a page




This post will show how you can do this using 1 single config file that you later will be able to deploy and undeploy (without restarting the server) using the module deployment ui in Share. In this blog post we will use Share's 'Document details' page to show these features, but once you have done this tutorial you will be able to switch out components on any page (except the dashboards which instead can be changed using Share's 'Customize dasboard' ui).


.


First lets take a look at the out of the box panels available on the Document Details page in Alfresco Community 4.0.a (the image to the left) and how the panels will look after we have applied the customization in this tutorial (the image to the right).


.




In short we will:


.






  1. Create a custom 'Acme Sample' document panel component


  2. Declare an extension module xml file for Acme which will.



    • Add the new 'Acme Sample' panel component above the 'Actions' panel.


    • Remove the 'Tags' panel component.


    • Replace the 'Permissions' panel with the 'Acme Sample' document panel.




  3. Package your extension as a .jar


  4. Deploy extension on your server




(In other words the 'Acme Sample' document panel will appear 2 times)


.


Note! If you want the full example source code, use this link: acme-test-extension.zip. Don't forget to rename it from .zip to .jar before placing it in TOMCAT_HOME/shared/lib!


Create a custom 'Sample' document panel for Acme



.


Create a minimal document details panel by first creating the following directoy structure /alfresco/site-webscripts/acme/components/document-details/ and inside it create the following files.


sample.get.desc.xml





<webscript>

   <shortname>Acme Test Sample</shortname>

   <description>Acme Test Document sample panel</description>

   <url>/acme/components/document-details/sample</url>

</webscript>




sample.get.html.ftl





<#assign el=args.htmlid?js_string/>

<div class='document-details-panel'>

  <h2 id='${el}-heading' class='thin dark'>${msg('heading')}</h2>

  <div>${msg('text')}</div>

  <script type='text/javascript'>//<![CDATA[

    Alfresco.util.createTwister('${el}-heading', 'DocumentMetadata');

  //]]></script>

</div>




sample.get.properties





heading=Acme Sample

text=This is a demo




Declare an extension module xml



.



Create the following directory structure: /alfresco/site-data/extensions/.

Inside that directory create the following file:


acme-test-extension.xml





<extension>

   <modules>

      <module>

         <id>Acme :: Test - Document Details Page</id>

         <evaluator type='default.extensibility.evaluator'/>

         <components>

            <!-- SWAP COMPONENT CODE GOES HERE -->

         </components>

      </module>

   </modules>

</extension>




When we write the code to swap components we will use 3 elements (<scope>, <region-id> & <source-id>) to identify 'where' our new components shall be added. But instead of diving into a detailed description of how pages, templates & regions work in Share I will just give you an extremely cut down version:


.


Each page (document-details.xml) uses a template (document-details.ftl) in which regions are declared (<@region id='document-actions' scope='template'/> into which one or more webscript components can be inserted.


.


If you didn't understand any of this, don't worry. All you really need is to identify the values for the 3 elements, something that can be done using a Share developer tool called SurfBug, just do the following:


.






  1. Go to http://localhost:8080/share/page/surfBugStatus


  2. Click the 'Enable SurfBug' button


  3. Navigate to the 'Document Details' (you should now see each component being surrounded by a red border)


  4. To identify the region-id, source-id & scope for the 'Actions' panel, simply click on the 'Actions' panel.


  5. You should now see a popup displaying information about the 'Actions' panel, you will find the values you are looking for under the 'Component Details' section.




.



If you haven't got a server running you can see the popup displayed bu SurfBug in the image below:



.



In the sections below I will show you how to use these values to add, remove and replace components on the page.

Add a new custom panel component above the 'Actions' panel.



Place the following code inside the place-holder-comment in the acme-test-extension.xml file mentioned above.



<component>

   <scope>template</scope>

   <region-id>document-actions</region-id>

   <source-id>document-details</source-id>

   <sub-components>

      <sub-component id='acme-sample' index='-1'>

         <evaluations>

            <evaluation id='acme-test-addSample'>

               <url>/acme/components/document-details/sample</url>

            </evaluation>

         </evaluations>

      </sub-component>

   </sub-components>

</component>




As you can we are using the 3 values to identify the region in which to add our sample component.



We then declare a <sub-component> element, you can declare as many as you like and therefore add as many components as you like. Note that we give the <sub-component> a unique id. The cool thing about that is that the id can be referenced from another extension module (which then can remove it). Therefor make sure you namespace your id with a company name.



The <evaluations> & <evaluation> elements are there to make it possible for a <subcomponent> to have multiple outcomes (the outcome being the <url> element pointing to the webscript to use). The outcome depends on which <evaluation> that returned true. In this example we are only using one <evaluation> element and it has no <evaluator> child elements, meaning we are actually not 'evaluating' anything and that the <evaluation> therefor always will 'win' (be the the onw who decides the outcome).



Note that the <url> element is pointing to our Acme 'Sample' panel we created earlier.

Remove the 'Tags' panel component



Place the following code inside the place-holder-comment in the acme-test-extension.xml file mentioned above.



<!-- Remove Tag Panel -->

<component>

   <scope>template</scope>

   <region-id>document-tags</region-id>

   <source-id>document-details</source-id>

   <sub-components>

      <sub-component id='default'>

         <evaluations>

            <evaluation id='acme-test-removeTags'>

               <render>false</render>

            </evaluation>

         </evaluations>

      </sub-component>

   </sub-components>

</component>




If you use SurfBug and this time click on the 'Tags' panel you can see from where the values for our first 3 elements are coming from. More interesting though is that we have set the id of the <sub-component> to 'default'. The reason for this is that we are actually not creating a new <sub-component> here, instead we are referencing the 'Tags' panel component.


.


The reason it is called 'default' is because when it was added to the page it didn't provide an explicit id. The <sub-component> id is also something you can find by using SurfBug, just look at the 'ID' field under the 'Sub-Component Details', the part after the '#' character is the id.


.


This means that what we are doing is to extend the 'default' <sub-component> (the 'Tags' panel) with a new <evaluation> element, and since it has no <evaluator> child elements it will always 'win' and decide the outcome. The outcome in this case though is NOT a <url> element, instead it is <render>false</render> which tells Share that no component at all shall be rendered.


Replace the 'Permissions' panel with the 'Sample' document panel.



Place the following code inside the place-holder-comment in the acme-test-extension.xml file mentioned above.



<!-- Replace Permissions with Sample Panel -->

<component>

   <scope>template</scope>

   <region-id>document-permissions</region-id>

   <source-id>document-details</source-id>

   <sub-components>

      <sub-component id='default'>

         <evaluations>

            <evaluation id='acme-test-replaceWithSample'>

               <url>/acme/components/document-details/sample</url>

            </evaluation>

         </evaluations>

      </sub-component>

   </sub-components>

</component>




In this example we have actually not introduced any new concepts, its just a combination of the previous two examples.



We use the 'default' id to add in a new <evaluation> to  the 'Permissions' panel. Since the <evaluation> has no <evaluator> child elements it will always 'win' and decide the outcome, in this case a <url> element pointing to Acme's 'Sample' panel component.

Package your extension as a .jar



As the last piece of the puzzle lets make sure to package everything up in a jar file so you can share it with your colleagues or easily deploy it on servers. Simply do the following:



  1. Use your terminal/dos window and change into the directory containing the directory structure you have created.



    • Note! it shall only contain the directory 'alfresco'




  2. Type the following command to jar it up:



    • jar cvf acme-test-extension.jar *




Deploy extension on your server



Now you have a nice extension packaged as a jar, so lets go ahead and use it, simply...



  1. Place it in your TOMCAT_HOME/shared/lib


  2. Restart your server


  3. Go to the deplyment ui http://localhost:8080/share/page/modules/deploy and make sure to enable your module by adding it and then click the 'Apply' button.


  4. Go to the document details page and you should now see 2 'Sample' panels but no 'Tags' or 'Permissions' panels.


I hope you enjoyed this blog post. If there was something you didn't understand, don't hesitate to add a comment. Once you get it you will find its a really easy and powerful way of extending your Share installation.



Cheers,



:: Erik

Outcomes