How To Hide Content On An Existing Alfresco Share Page
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):
- Re-build your JAR file,
- Copy it into the “webapps/share/WEB-INF/lib directory“
- Restart the server
- Open http://localhost:8081/share/page/modules/deploy in a web browser
- If you still have “Blog Module (New Content)” deployed, undeploy it by selecting it and clicking the “Remove” button
- Deploy “Blog Module (Hide Title)” by selecting it and clicking the “Add” button
- Click “Apply Changes” to save your module deployments
- 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:
- Change the Web Script that renders the content by specifying a new URL
- Change the default properties (and/or provide new properties) that are passed to the Web Script
- 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.
October 9th, 2011 at 3:50 am
David — your explanations are very clear. Thanks for spending the time in writing these.
The use of the term ‘module’ here seems confusing since aren’t these something totally different than the AMP type of module?
Seems like a different name would be better.
I’m assuming that these jar files are basically the same structure as the jar files used previously for dashlet extensions — is that right?
Or are these a ‘special’ kind of jar file since only they show up on the module deployment page.
There are so many ways to override Alfresco standard behavior. The order of evaluations is something I’d like to understand better.
Standard war files vs. files in the Shared extension/web extension folders vs. AMP moudle files versus Jar files vs. these module jar files files.
Jar files in the lib directory in the war area and jar files in the lib directory under Shared, etc.
The up-down buttons on the module deployment page seem to control the order of evaluation of module jars. if there are conflicting directives, does the last one applied win? — — like the example here, if one module deployed declared as false and another one as , which one is used, the one lower in the deployed module list?
Here you’re deploying to the webapps/share/WEB-INF/lib directory. Where should we deploy to avoid having the file lost on upgrades?
If we put it under the lib directory in shared, won’t it be applied to all surf-based applications in webapps?
It seems like we’d want to be able to put it under the shared directory (outside webapps) but somehow specify that this jar file is really intended to affect only the Share surf application.
October 10th, 2011 at 8:05 am
Thanks for the comments George, your feedback is much appreciated…
One of the challenges of making these changes was that they were to the Spring Surf framework rather than to Alfresco, so I could just say that module is not an overloaded term in Spring Surf
. Whilst these extensions don’t have to be deployed as an AMP there is no reason why they couldn’t be (this would be a way of avoiding changes lost on upgrades), and whilst the term “module” is overloaded we felt that this was really still the best way of describing was it was providing.
I suppose that the variety of ways in which you can extend Alfresco could be considered a benefit, but you’re right that it can be confusing. The extension configuration that I’m describing in these blogs is the definition of a new Spring Surf object (like Page, TemplateInstance, Component, Theme, etc) and can exist anywhere that Spring Surf is configured to look for objects which includes all the locations you’ve mentioned.
This is also true for the WebScript and FreeMarker content provided in JAR files – the package/page location simply has to be somewhere that Spring Surf is configured to look for them – the rules of which are all configurable through the Spring bean definitions/configuration.
In terms of deployment order, the rules are that modules will be processed in the order deployed but there are subtleties within these rules… for example whilst new CSS import statements can be added by modules in the order they are deployed, CSS rules state that it’s the last CSS statement rather than the first that wins.
Multiple modules can override the same Sub-Components WebScript URL but it’s the *last* module that will win… however, if multiple modules are attempting to reference the same but the first module removes that the then the first module will “win” (because the others cannot reference something that no longer exists!)
However, the modules are processed in the order that they’re deployed.
If you place a JAR in the “shared” lib directory then those extension will be available to all Spring Surf applications running on that server… however, a extension configuration alone has no effect until it is deployed on an application basis. So you actually have to manually deploy the extension modules (or be running both applications in auto deployment mode) for this to have an effect (this is because Spring Surf actually another object type to control deployed modules).
October 12th, 2011 at 5:21 am
[...] http://blogs.alfresco.com/wp/ddraper/2011/07/27/how-to-hide-content-on-an-existing-alfresco-share-pa... [...]