Customizing Alfresco Share i18n Properties

[ddraper]

Introduction

In previous blog posts I have described how to customize Alfresco Share through the use of Component extensions. This is only one of the new extensibility features that are currently available in the Alfresco Community source (and will be included in Alfresco Enterprise 4.0). In this post I'll start describing the changes we've made to Spring Surf in order to further simplify customization use cases starting with demonstrating how to customize Web Script i18n properties.

Tutorial

This tutorial describes how to override the default i18n properties for the User Dashboard title bar. It will show how to use the SurfBug and the Web Scripts UI to find the Web Scripts that need to be targeted and then demonstrate how to create the necessary extension module configuration and files to achieve the customization.

1. Logon to Alfresco Share and navigate to the user dashboard.

2. Open a new browser window or tab and enable SurfBug (http://localhost:8080/share/page/surfBugStatus - if you're using default port settings on your local machine)

3. Refresh the dashboard page and click on the title to see the information about the Component/Sub-Component that is rendering it

4. Make a note of the 'url' value in the Component details (which should be '/components/title/user-dashboard-title')

5. Open a new browser window or tab at the Web Scripts Home page (http://localhost:8080/share/service/index) and click on 'Browse by Web Script URI'

6. Find and click on '/components/title/user-dashboard-title' to see the information about the Web Script that is rendering the title bar.

7. Click on the link next to 'Id' to see all the information about the Web Script.

8. The key piece of information that we're looking for here is the package that the Web Script belongs in which is 'org.alfresco.components.title' because we're aiming to customize the code defined in that package.

9. Edit your 'blog-demo.xml' (created in the previous blog post tutorials) and add the following module definition:

<module>
    <id>Blog Module (i18n property change)</id>
    <customizations>
        <customization>
            <targetPackageRoot>org.alfresco.components.title</targetPackageRoot>
            <sourcePackageRoot>blog.demo.customization</sourcePackageRoot>
        </customization>
   </customizations>
</module>

10. On the page showing the information about the Web Script scroll down to find the section on the i18n properties file which will show both the fully qualified name of the file along with its contents.

Create a new file called 'user-dashboard-title.get_en.properties' and place it in package 'webscripts.blog.demo.customization' package that we defined as the 'sourcePackageRoot' element in the module configuration. The file should contain the following:

header.dashboard=Customized Title Bar!

There's a couple of important things to note here!

1. The file name is NOT exactly the same... although a Web Script  will broaden the locale of it's search (i.e. from 'en_GB' to 'en' to  the default properties file - extensions will NOT)

2. The source package has been prefixed with 'webscripts.' - this is a requirement of the class loader used to find Web Script files.

11. Re-build the JAR, copy it to 'webapps/share/WEB-INF/lib' (or the equivalent directory for your web server), restart the web server and deploy the new module (hopefully you should be used to this process by now - if not, see the earlier blog posts for more details).

Logon to Alfresco Share you should now see that the title bar now says 'Customized Title Bar!'https://community.alfresco.com/api/core/v3/attachments/12032/data

Background Information

When you create a 'customization' you are creating a mapping from a package to you want to update to a package that you are providing. When any file is processed in that package all mapped extension module packages are searched for a matching file name. Typically a Web Script might be represented by a JavaScript controller, an i18n properties file and a FreeMarker template. They must all be defined in the same package with a similar file name prefix as the Web Script descriptor file to which they are related. This package mapping allows us to target multiple files in a single customization rather than specifying every file individually. It also allows us to broaden our target. For example we could have targeted 'org.alfresco' - but it is important to note that the remainder of the package will be applied to the source (so the extensibility framework would be looking for a matching file in the 'blog.demo.customization.components.title' package).

When you provide an i18n properties file extension the properties in the extension file are merged into the 'base' file (any duplicates are replaced with those from the extension file). If multiple modules extend the same properties file then the last module in the deployment list will 'win'.

It is not necessary to provide an extension file for every base in the Web Script - only those that you wish to extend. For example - if a Web Script has controller, properties and template files you don't need to provide extensions to all 3 if you just wish to override some i18n properties.

It's also possible to provide an extension file to a Web Script that does not have that base file. For example, it is entirely possible to extend a Web Script with a JavaScript controller or i18n properties file even if those files are not in the base.

In the next post I'll demonstrate how to extend a Web Script JavaScript controller.