Erik Winlöf's blog

Introduction

Create a custom “Sample” document panel for Acme

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

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>

.

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>

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