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