How To Hide Content On An Existing Alfresco Share Page

[ddraper]

Introduction

In my last blog I introduced some of the new extensibility features that are now available in the latest Alfresco Community source code and will later appear in Alfresco Enterprise 4.0. I demonstrated how to create and deploy an extension module that added some extra content to a user dashboard page in Alfresco Share. In this blog I'm going to demonstrate how to use an extension module to hide some extra content in an Alfresco Share page.

Tutorial

Our previous module added content to the title bar on the user dashboard, let's take the opposite tack and write a module to completely hide it.  If we were targeting a different Component we'd use SurfBug to identify the title bar region-id, source-id and scope properties (see the previous post for a refresher on how to do this) but as we're modifying the same Component we can just copy the configuration from the 'blog-demo.xml' file that you previously created.

Add another <module> entry into the <modules> element - as follows:

<module>
    <id>Blog Module (Hide Title)</id>
        <components>
            <component>
                 <region-id>title</region-id>
                 <source-id>user/{userid}/dashboard</source-id>
                 <scope>page</scope>
                 <sub-components>
                     <sub-component id='default'>
                         <evaluations>
                             <evaluation id='guaranteedToHide'>
                                 <render>false</render>
                             </evaluation>
                         </evaluations>
                     </sub-component>
                 </sub-components>
             </component>
     </components>
 </module>

Then follow these steps (they should be familiar from the previous tutorial):

1. Re-build your JAR file,
2. Copy it into the 'webapps/share/WEB-INF/lib directory'
3. Restart the server
4. Open http://localhost:8081/share/page/modules/deploy​ in a web browser
5. If you still have 'Blog Module (New Content)' deployed, undeploy it by selecting it and clicking the 'Remove' button
6. Deploy 'Blog Module (Hide Title)' by selecting it and clicking the 'Add' button
7. Click 'Apply Changes' to save your module deployments
8. Logon to Alfresco Share and you should see that the title bar is no longer displayed.

It probably seems like that's a lot of XML to achieve a fairly simple task, but we're really only just scratching the surface of what is possible. Let's explore some of the elements of this configuration more closely...

Parametrized source-id mapping

Every Alfresco Share user gets their own dashboard page (which enables them to customize the layout to suit their own needs) but each user dashboard is generated from a single preset.  In the previous blog we targeted only the Admin user dashboard by extending the title region on the 'user/admin/dashboard' template, but here we're targeting all user dashboards by specifying the source template 'user/{userid}/dashboard'.

Extending Existing Sub-Components

When the dashboard pages were first created the concept of Sub-Components in Spring Surf did not exist and consequently if you search through the existing dashboard configuration files you won't find any mention of Sub-Components.  Spring Surf automatically converts these 'legacy' Components into the new extensible Components containing a single Sub-Component with the ID 'default'.

This allows us to add new content to these legacy Components (as we did in the last blog) or customize the original content without effecting any new content. In this instance by specifying a Sub-Component with an ID of 'default' we are not adding new content but changing the behaviour of the original content. Multiple modules can extend the same Component which is why the deployment order of modules can be important.

I'll be exploring Sub-Components in greater detail in a later blog.

Sub-Component Evaluations

Every Sub-Component can optionally have zero or more evaluations. Each evaluation acts like an AND-gate to a series of evaluators where an evaluation is considered successful if no evaluators fail. If an evaluation contains no evaluators then it is still considered to have evaluated successfully because nothing has failed.

The purpose of an evaluation is to change the behaviour of a Sub-Component in one of three ways:

1. Change the Web Script that renders the content by specifying a new URL
2. Change the default properties (and/or provide new properties) that are passed to the Web Script
3. Control whether or not the Sub-Component is actually rendered.

In this example we're simply overriding the default behaviour of the Sub-Component to prevent it from rendering by setting the <render> element to have a value of false (this defaults to true) if not defined.

I'll be exploring evaluations and evaluators in greater detail in a later blogs, but the purpose of this tutorial is to provide an introduction into customizing existing content.

Some Additional Notes

It would have been possible to add the <sub-component> elements (and its children) into the module created in the previous blog as single module can update multiple Components and Sub-Component.  Adding the 'hide' configuration as a separate module allows us to deploy and undeploy both independently. If you deploy both modules you'll see that it's the new content is still rendered despite the the title bar being hidden. It is not necessary to restart the web server between module deployment changes - providing you remember to click the 'Apply Changes' button the updates will be shown the next time you refresh the Alfresco Share page.