This quick tutorial shows how much easier it is to package up custom extensions to Alfresco Share in version 3.3.
The features for handling the new single package deployment and simpler more compact configuration are part of the SpringSurf web framework recently contributed to SpringSource by Alfresco engineering.
Most of these issues have been solved with SpringSurf:
Loading of Surf configuration files directly from a JAR
Referencing web-assets packaged within a JAR or the class path via a simple Resource servlet URL
Combining multiple Surf config elements - pages, templates, component into a single file
It might not sound like much, but these changes make a big difference to reducing the complexity of developing and packaging Share extensions.
The tiny JAR files related to this tutorial - it's worth having them open to examine while reading the rest of the article:
Dashlets are small portlet like units of functionality available in either the User or Site dashboards (or both). An example might be a summary of user tasks, site activities or documents recently added to a site. Custom dashlets are one of the easiest items to add to Alfresco Share
Each dashlet is generated by a single Share WebScript component. The needs to be marked as a member of the 'site-dashlet' family. The 'family' of a WebScript is like a simple tagging or categorisation mechanism - applications can use the Surf APIs to retrieve the IDs of all WebScripts within a named family, which is exactly what Alfresco Share does to generate the list of dashlets available to the user on the Configure Dashboard page.
So, no further configuration of Share is required other than to make sure it is found by the web-app on initialisation.
To mark a dashlet as available in the User dashboard, use the 'user-dashlet' family. The mark as dashlet as available for both dashboard types, use the 'dashlet' family. Of course a site dashlet written expecting specific context information such as the current site id will not work in the user dashboard context so care should be taken when applying the correct family category.
This example shows how to package up a Tag Cloud dashlet that was previously built for use as a demonstration of how to incrementally develop a dashlet for Alfresco Share 3.2 at the recently held Alfresco Meetup user conferences. This article won't go into the detail of the dashlet code itself - but it does make an excellent example of several key concepts and features that are important to understand if you want to build rich, Ajax enabled components for Alfresco Share. It demonstrates:
The artifacts that make up a WebScript component
Passing values from the JSON response into the WebScript FreeMarker template for rendering the dashlet response
Performing an Ajax call via the Surf proxy back to the Alfresco server to perform live refresh of the Tag Cloud
Retrieving labels from the WebScript I18N message bundle
Linking to other Share pages (the Search results page when clicking on a tag)
Making the dashlet resizable
SpringSurf features a number of 'persisters' which iterate the configured classpath and JAR locations for all the various page, component and template files that are available. This means to make WebScript components, pages and other objects available to Share, they simply need to be located under one of those configured paths. The JAR file structure required is as follows:
site-tags.get.* <- the WebScript artifacts for the dashlet component
Your WebScript components can live in any folder structure you require under alfresco/site-webscripts - that is one of the paths automatically searched by Share.
Note that it is possible to override the default SpringSurf persister configuration if you want to add your own classpath/JAR path search locations. This is exactly what Share itself does to to add the Alfresco specific paths in addition to the common SpringSurf locations.
The web assets required for your components now live under META-INF - this is effectively the root of all URLs that are processed by the Resource servlet. For example:
You should find that relative paths to images etc. in CSS classes work also, for example in the Tag Cloud dashlet CSS the file <CODE>images/refresh.png</CODE> is referenced thus:
No references to any other web-app are required!
Deploying the Dashlet
In a default Alfresco installation the included TomCat bundle is already configured to pickup extensions of classes and JARs added to $TOMCAT_HOME$/shared/classes and $TOMCAT_HOME$/shared/lib respectively. So it is a simply matter of dropping the JAR into the lib folder and then restarting the app-server. Note that a plain install of TomCat 6 will need to be tweaked to find classes and jars in those locations - ensure this line is present in $TOMCAT_HOME/conf/catalina.properties
If you create a new Share site (or navigate to an existing one), click the Customize Dashboard button on the toolbar and then click the Add Dashlets button you should see the Tag Cloud dashlet listed! That's it. If you want to play with the tag cloud itself you'll need to add some documents to the site and tag them.
Share Page Extensions
Additional custom pages with associated templates and components can be added to Share, it is a little more complex than adding a dashlet, but less so with Share 3.3. This article does not go into great detail on the structure of Share pages or specific SpringSurf concepts here, however more information on concepts like pages, templates and component binding can be found on the Alfresco Developer Wiki http://wiki.alfresco.com/wiki/Surf and http://wiki.alfresco.com/wiki/Surf_Platform_-_Developers_Guide
Page Extension Example
This example is a simple Share page extension that again introduces a number of concepts that should be understood before developing Share pages. The example demonstrates adding a new Site page called Site Profile. The Site Profile page configuration identifies the template used to render it and the template itself supplies the mark up and the location of the 'regions' that bind to the components within it. Templates are generally small, lightweight and responsible only for providing the markup for the component areas - generally just a few nested DIVs and SPANs - it's the WebScript components bound to the regions that really do the work. The template is as follows:
Note the @region tags - these define the component bindings. The complete page is designed to look like most other Share pages - with the 'global' scoped header and footer regions already defined in Share. The interesting parts are the 'title' and 'sitedetails' regions. Previously to Share 3.3 each of these template or page specific components would require another configuration file - but with SpringSurf these components can be defined as part of the page and template configuration files to reduce complexity further.
The 'sitedetails' page component is defined within the page definition thus:
<!-- in SpringSurf page scoped component config can now be embedded directly
into the page config - no more additional xml files required -->
<!-- a custom page component packaged with this example -->
It binds the 'sitedetails' region id to the WebScript with a URL of /components/sitedetails - we register our WebScript with the same URL. Here is the WebScript descriptor for our sitedetails component in sitedetails.get.desc.xml
<shortname>Example Site Details</shortname>
<description>Example Site Details Share extension component</description>
Packaging the Page Extension
As noted above, to make your configuration objects available to Share, they simply need to be located under one of its configured search paths. The JAR file structure required is as follows:
sitedetails.get.* <- the WebScript artifacts for the Site Details page component
In addition to the alfresco/site-webscripts folder mentioned in the previous example, we have added an alfresco/site-data folder - this is on the search path to lookup pages, template and component definition files. Again you can use any structure you like under this folder, the page and template definition files here have been placed into separate folders but that is not essential.
Deploying the Page Extension
Place the JAR file into the $TOMCAT_HOME/shared/lib location as mentioned above as start the server. Then either create or navigate to an existing Share site. To access the new page, modify the url in the browser as follows:
Obviously ensuring the your-server and your-site-id elements are correct. You should see a new page appear containing details on the current site with the Surf logo at the bottom!
This quick example of repackaging and light refactoring of a dashlet and a simple page extension into single 'drop-in' JAR files show some of the improvements in Share 3.3 now possible thanks to SpringSurf. The combination of the two examples also introduce most of the concepts and frameworks required to developer rich Alfresco Share pages and Ajax enabled components.