Aikau 1.0.63 - Support for versioned library imports

[ddraper]

Introduction

This blog post describes how you can now safely import Aikau library files into WebScript controllers when you have multiple versions of Aikau available in your application. PLEASE NOTE: This information only applies if you're using Alfresco 5.1 or 5.0.3 onwards.

Background

In the Aikau 1.0.63 release we have completed the final stage of fixing AKU-411. This bug was raised because there was no reliable way of knowing which version of an Aikau library file would be imported into a WebScript JavaScript controller.

Although Alfresco Share will only ship with a single version of Aikau (included as a JAR file in the WEB-INF/lib folder) additional JARs might be added when applying AMP files (such as Records Management). This meant that there would be duplicate versions of library files available on the classpath to be imported and as a result you could not guarantee which version would be loaded.

We made some changes in the Alfresco 5.0.3 service pack to remedy this problem (also available in Alfresco 5.1) and have now updated Aikau to take advantages of these capabilities.

At the time of writing there is only a single library file shipped with Aikau which can be used for building Document Libraries within a page - but in the future we hope to provide many more library files to address a variety of common use cases.

A New Way to Import Library Files

Previously you would have needed to imported the library file as follows:

<import resource='classpath:alfresco/site-webscripts/org/alfresco/aikau/webscript/libs/doclib/doclib.lib.js'>‍

But you can now import the file as follows:

<import resource='classpath:alfresco/site-webscripts/org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib.js'>‍

The {aikauVersion} token will automatically be swapped out for the version of Aikau that is being used by Surf. By default the most recent version of Aikau available will always be used, however it is possible to select and use an older version from the Module Deployment page (found at /share/page/modules/deploy - see screenshot below)

If you use the {aikauVersion} token then you are effectively stating that you always want to use the same version of the library file that is shipped with the currently used version. However, it is still entirely possible to use a specific version, e.g.

<import resource='classpath:alfresco/site-webscripts/org/alfresco/aikau/1.0.63/libs/doclib/doclib.lib.js'>‍

However, this does mean that you need to ensure that the version specified is available.

This means that we are now able to make incremental improvements and fixes to the Document Library import file, it also means that it now makes sense for us to start providing more files that can be imported.

How To Use The Document Library Import

The doclib.lib.js file has been written with re-use in mind. It provides a number of different functions that can be called giving you the choice of building an entire Document Library or just fragments of the Document Library (such as the list, the toolbar, the tree, etc) and all the functions take a configuration object so you can control how the Document Library will be built.

So for example if you wanted to build a full Document Library for company home you could use the following in your WebScript controller:

<import resource='classpath:alfresco/site-webscripts/org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib.js'>

model.jsonModel = {
  services: getDocumentLibraryServices(),
  widgets: [
    getDocLib({
      rootNode: “alfresco://company/home”,
    })
  ]
};‍‍‍‍‍‍‍‍‍‍

There are a variety of other options that you can provide when calling the function, for example:

• idPrefix - (string) A prefix for the IDs of all the widgets created

• siteId - (string) the site shortName attribute of the site to build a Document Library for

• containerId - (string) the name of the folder in which the Document Library content resides within the site (typically this would be “documentLibrary”

• rawData - (boolean) whether or not to make XHR requests directly to the Alfresco Repository and bypass the Alfresco Share web-tier

• rootNode - (string) A nodeRef to root the Document Library

• rootLabel - (string) The label for the root of the Document Library as shown in the breadcrumb trail and in the navigation tree

• useHash - (boolean) Whether or not to update the browser URL hash with Document Library state

• getUserPreferences - (boolean) indicates whether or not the user preferences should be retrieved from the Alfresco Repository

• docLibPreferences - (object) custom preferences for the Document Library (sortField, sortAscending, showFolders, hideBreadcrumbTrail, showSidebar).

The functions that you can call include:

• getDocLib (builds the whole Document Library calling the following functions as appropriate)

• getDocLibFilters

• getDocLibTree

• getDocLibTags

• getDocLibCategories

• getDocLibToolbar

• getDocLibBreadcrumbTrail

• getDocLibList

• getDocLibCreateContentMenu

• getDocLibSelectedItemActions

• getDocLibSortOptions

• getDocLibConfigMenu

Localization Properties Importing

As well as providing an import for the Document Library model and additional properties import is provided for localization purposes. For the background on importing properties files you should read this related blog post.

These imports support the {aikauVersion} token in exactly the same way. Previously you would have imported the file as follows:

surf.include.resources=org/alfresco/aikau/webscript/libs/doclib/doclib.lib‍

But now you can do so using the token:

surf.include.resources=org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib‍