How to add AMD Packages to Share via Extension Modules

[ddraper]

Introduction

A comment on a previous post questioned why it was necessary to update the 'surf.xml' configuration file in order to declare a new AMD package. This was an obvious requirement that I had completely overlooked and have now implemented a simple solution to address this for the Alfresco Community 4.2.e and Alfresco Enterprise 4.2 releases.

Understanding the Problem

The package declaration configuration defined in 'surf.xml' is transformed into a simple JavaScript object that is created before the Dojo kernel is loaded (the Dojo kernel provides the AMD loader). By default Alfresco Share will declare the following packages:

• alfresco

• surf

• dojo

• dijit
• dojox

If a 3rd party wants to extend Share by providing a JAR file containing WebScript page definitions that use modules defined in their own package then they would need to get the Admin to update the 'surf.xml' in order for the modules to be resolved.

Dynamic Configuration to the Rescue

Surf supports the capability to dynamically modify configuration on a per-request basis (as described here) but unfortunately the org.springframework.extensions.surf.DojoDependencyHandler class was only using the static configuration. An update to Surf (revision 1323) has fixed this so that it is now possible for extension modules to add additional packages dynamically.

Example

This sample JAR file contains an example of how to declare an extension that adds an additional package. It contains the following structure:

• alfresco/site-data/extensions/extension.xml (you can call it whatever you want!)

• META-INF/js/lib/blogs (this is our package root for widgets)

In 'extension.xml' you'll see the following:

<extension>
  <modules>
    <module>
      <id>Add a Custom Package</id>
      <version>1.0</version>
      <auto-deploy>true</auto-deploy>
      <configurations>
        <config evaluator='string-compare' condition='WebFramework' replace='false'>
          <web-framework>
            <dojo-pages> 
              <packages> 
                <package name='blogs' location='js/lib/blogs'/>
              </packages>
            </dojo-pages>
          </web-framework>
        </config>
      </configurations>
    </module>
  </modules>
</extension>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍Copy the JAR file into the '<tomcat-home>/webapps/share/WEB-INF/lib' directory and restart the server and when you view the source of a page you should see that the additional package element has been added.

The Result

The upshot of all this is that you can use a widget in the 'blogs' package when defining page structures via JSON as the loader will be able to resolve the dependencies. In the sample JAR I've created a page called 'greeting' which can be accessed via the URL https://<host>:<port>/share/page/hdp/ws/greeting and renders the 'blogs/greeting/HelloWorld' widget (modelled on the widget described in this blog post)

There's nothing especially remarkable about this widget beyond the fact that it is loaded from a package defined in a module and the code is all contained within the JAR.

Summary

From Alfresco Community 4.2.e and Alfresco Enterprise 4.2 it will be possible to dynamically add AMD packages through extension modules to avoid the need to update 'surf.xml' and restart the server.

Again, I'm grateful to the Alfresco Community for highlighting this omission and hopefully have reinforced our commitment to respond to the Community needs!