Adding the Aikau Document Library as a Site Page in Share

[ddraper]

Introduction

In previous blog posts I’ve shown examples of how the Aikau version of the Document Library can be used both within Share and in standalone clients. In this blog post I thought it might be useful to provide a more in-depth guide on how to add the Aikau Document Library as a site page in Share, as well as to provide a general status update on progress.

Background

It’s important to understand that the Aikau team is a “Component Team” and not a “Feature Team”. This means that we provide the components (in this case Aikau widgets and services) for other teams to deliver features or products.

At the time of writing there is no feature team driving the replacement of the old YUI2 Document Library with the Aikau version - nor indeed has there ever been. Aikau has always predominantly been about re-use and the Document Library has progressed because other features have required Document Library related widgets.

There are two epics in JIRA that list the current tasks required to achieve feature parity with the YUI2 Document Library: one for general features and one for action support. Reviewing these epics should give an overview of what work remains.

In general the Document Library is quite functional and should be more than adequate for covering a large number of use cases. The following steps and code is available within the following GitHub repository and all of the files described before are linked to the specific files in that repository.

Create the Aikau Document Library Page

The first step is to create the WebScripts for the new page. Create the WebScript descriptor file…

DocLib.get.desc.xml

<webscript>
  <shortname>Document Library Example </shortname>
  <description>This provides an example of building the standard Document Library using the doclib.lib.js library file.</description>
  <family>Aikau</family>
  <url>/DocLib</url>
</webscript>‍‍‍‍‍‍‍‍‍‍‍‍

Now let’s create the template…

DocLib.get.html.ftl

<@processJsonModel/>‍‍

The properties file is slightly more involved…

DocLib.get.properties

surf.include.resources=org/alfresco/share/imports/share-header.lib,org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib‍‍

This file just contains an instruction to import two other properties files:

• org/alfresco/share/imports/share-header.lib 

• org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib

This process is described in more detail in this previous blog post.

The last WebScript file required is the JavaScript controller… this is where most of the code goes:

DocLib.get.js

The first thing is to import the required controller files…

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

Now you need to import the services and widgets that the header uses…

var services = getHeaderServices();
var widgets = getHeaderModel(msg.get('aikau.doclib.title'));
‍‍‍‍‍

The header services need to be combined with the services required by the Document Library. These can be retrieved by calling getDocumentLibraryServices.

services = services.concat(getDocumentLibraryServices());‍

Now use the getDocLib function to create the model for the Document Library. The main data to provide is the site id which is available from a template argument and the name of the folder in which the Document Library files can be found within the site folder (typically “documentLibrary”).

var docLib = getDocLib({
  siteId: page.url.templateArgs.site, 
  containerId: 'documentLibrary'
});
‍‍‍‍‍‍‍‍‍

This model needs to be added to the header model....

widgets.push(docLib);‍‍

Finally we need to call getFooterModel passing in the header and Document Library services and widgets. This is required because the footer model wraps everything else on the page.

model.jsonModel = getFooterModel(services, widgets);‍‍

Make the Document Library a Site Page

In this previous post I describe the process for adding Aikau pages in general - so please refer to that for a slightly more in-depth description of the process.

Create a new Surf Page definition that will provide the title and description of the page as shown when customizing sites.

AikauDocLib.xml

<?xml version='1.0' encoding='UTF-8'?>
<page>
  <title>Aikau Document Library</title>
  <description>The Aikau Document Library</description>
</page>‍‍‍‍‍

Now create an extension module to ensure that the site page is an option when customizing sites.

Aikau-document-library.xml

<extension>
  <modules>
    <module>
      <id>Aikau Document Library Site Page</id>
      <auto-deploy>true</auto-deploy>
      <evaluator type='default.extensibility.evaluator'/>
      <configurations>
        <config evaluator='string-compare' condition='SitePages' replace='false'>
          <pages>
            <page id='AikauDocLib'>dp/ws/DocLib</page>
          </pages>
        </config>
      </configurations>
    </module>
  </modules>
</extension>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Now you need to pull these files together into a single JAR and copy them to the “share/WEB-INF/lib” folder.

Restart Share and go to any site and customize it - you should see the “Aikau Document Library” in the list of available pages:

Drag it into the “Current Site Pages” list and click “OK”

Now you should have a new link for the “Aikau Document Library” (if you have a lot of site pages, try looking under the “More” drop-down menu!). Click on the link and you’ll be taken to your the Aikau Document Library:

What Are The Benefits and Limitations?

One of the main reasons for creating an Aikau version of the Document Library was to make customization much simpler. Through the use of the Aikau model it is significantly easier to make fine-grained changes to the Document Library. Some things you could do for example would be:

• Add custom views 

• Edit existing views (add or remove the metadata that is displayed) 

• Filter the displayed actions or add entirely new actions 

• Render only specific sections of the Document Library (the tree, breadcrumb trail or list for example) 

• Edit the menu options that are displayed

The Aikau version also has a few features that are not included with the original Document Library: 

• Drag-and-drop upload new version 

• Inline document preview 

• Inline commenting 

• Inline content creation

As of Aikau 1.0.68 the Document Library uses a new non-modal upload file design. See screenshot below:

The main limitation is that there is not yet support for all the actions that you would find in the existing Document Library (you can review the missing actions in the previously linked epic).

The other potential limitation is the lack of integration with the forms runtime. This means that when editing properties for custom types the XML forms configuration will not be represented.

Despite these issues the Aikau Document Library should still be useful for many use cases - especially where serious customization of the existing Document Library is required.