by Dave Draper
Introduction
This blog post is going to describe a simple but useful new feature that has been added to Surf. It is available in the latest Alfresco Community nightly builds and in the SVN repository. It is now possible for WebScript iocalization .properties files to include the contents of another file and have it's content merged into the resulting ResourceBundle.
For a long time it has been possible to include 'library' files in WebScript JavaScript controllers and FreeMarker templates but it was not possible to include 'library' localization content. This meant that any localizations performed by the library files would either have to be duplicated in the including WebScripts properties files or added into a 'global' properties files (such as 'slingshot.properties').
By enabling library files to be a combination of FreeMarker, JavaScript and localization files it means that you can create much more rounded library files.
Example Use Case
Currently we render the Share header bar as a Surf Component and are able to 'inject' additional widget models into the page using a hybrid-template approach (where any content is rendered between a standard header and footer). However, there are issues with this in that the Dojo AMD loader ends up importing dynamically generated resources with duplicate paths (this is only a problem in terms of debugging and the number of bytes loaded - the pages will still function). A much more useful approach would be to have a header library file (as indeed we already have: 'share-header.lib.js' that provides methods for creating the header widgets and services which can be included in page specific WebScripts (e.g. 'share-header.get.js').
The problem is that this relies on common properties being defined in the slingshot.properties files. For the header this isn't a major problem as it rarely varies, however in other situations (e.g. the Document Library) we want to import a library but vary the localization keys. This means that we either have to duplicate keys across each page WebScripts (e.g. 'Document Library', 'Shared Files', 'My Files', 'Repository') or put all the keys in the core 'slingshot.properties' file (which will then be loaded on pages even when not required).
A better solution is for the Document Library JavaScript library file to have a partner .properties file that can be imported into each specific WebScript..... and that's exactly what this new capability provides.
Example
To declare an import simply add the key 'surf.include.resources', e.g.
surf.include.resources=org/alfresco/share/header/share-header.lib
...and you define multiple imports by delimiting each file with a comma, e.g.
surf.include.resources=org/alfresco/share/header/share-header.lib,org/alfresco/share/documentlibrary/doc-lib.lib
Note that you should not attempt to define any locale information. The correct locale specific file will be imported based on the locale of the browser (and will gracefully fall-back as you would expect). So in the above example if your browser is set to use the locale 'en_GB' then Surf will first attempt to import the file 'share-header.lib_en_GB.properties' and if it fails to find that file it will fall back first to 'share-header.lib_en.properties' and finally to 'share-header.lib.properties'.
Caveats
There are some important caveats:
- Imports cannot import (e.g. if you import a properties file that contains the key 'surf.include.resources' then those resources won't be imported) - this is a good thing as it prevents circular dependencies
- Imports are processed and cached BEFORE extension modules are applied (this means that an extension can't alter imported properties - however it can still override them)
Summary
It's now possible to include library style properties files in WebScripts. This should hopefully make it easier to create more complete collections of library files that don't rely on global or duplicated localization keys.
