How to add AMD Packages to Share via Extension Modules

Showing results for 
Search instead for 
Did you mean: 

How to add AMD Packages to Share via Extension Modules

Intermediate II
0 10 4,476


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


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:

      <id>Add a Custom Package</id>
        <config evaluator='string-compare' condition='WebFramework' replace='false'>
                <package name='blogs' location='js/lib/blogs'/>

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

Page source showing the additional package


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)

Screenshot showing Share with the HelloWorld widget

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.


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!

Active Member
Hi David,

I tried installing the jar file in webapps/share/WEB-INF/lib and although it works it is not resolving the property labels.   I just see (label.greeting) rather than Hello World.   I am using the pre- release Alfresco 4.2 Enterprise version.   I know its not such a big deal but as I am trying to develop a page with custom widgets I was wondering if the layout of the jar is incorrect.


Intermediate II
Hi Brian,

I uploaded the same JAR that I used when generating the screenshots... so the issue is most likely to be the version of Surf that is in pre-release 4.2.  I'd recommend trying again with the recently 4.2.e Community release.


Active Member
[…] shows an example of adding in a new AMD package into Share which was described in more detail in this previous blog post. The JSON Editor AMD modules are referenced from the […]
Active Member
Hello Dave,

Thanks very much for these posts that really helped me in my missing of upgrading from community 4.2.c to the 5.0.a.

I wonder if is possible to tell surf that look for specific name instead of main.js for each library. I am trying to  include jQuery as a module and it tells me that .../js/jquery/main.js doesn't exist what is true but instead of renaming it to main.js i would like to do something like this

to be translated to

packages: [

    { name: 'jquery', location: 'js/jquery/1.9.1',  main: 'jquery' }


Anyway i just wondering if it is do able otherwise I will rename it to main.js

Thanks in advance!

Kind regards

Carlos Liró
Active Member
Missing: package <name='jquery' location='js/jquery/1.9.1' main='jquery'/> to be translate to...
Intermediate II
@Carlos At the moment Surf doesn't support that, however it's something that we could add relatively easily. Can you raise a JIRA issue against the 'WebScripts and Surf' component (so that it gets assigned to me) and I'll try to get it implemented before the 5.0 enterprise release.
Active Member
Done! enjoy... XD

Thanks in advance once more
Active Member
BTW, probably it has to be this way but it is mandatory the new package module to be locate within js folder otherwise it doesn't work, i.e. <package name='icmr' location='blogs/js'/> instead of  <package name='icmr' location='js/blogs'/>
Intermediate II
No, it's not mandatory to be in that location, however everything is relative to {application-context}/res (which is itself is a configurable setting)
Active Member
[…] I won’t go into any depth on what this configuration does as it has been discussed in this previous blog post. […]