Today Jeff Potts, Alfresco’s Chief Community Officer, writes on Social Content that the Alfresco AVM (Alternative Versioning Model) will no longer be supported from Alfresco 5. The AVM was an alternative repository implementation in Alfresco to support Web Content Management use cases. It was designed as some sort of version control system with support for repository virtualization. It was originally designed by Kevin Cochrane who left Alfresco in 2008 to work for Day Software. 

I am must say that I am very happy with Alfresco’s decision to get rid of the AVM store. The whole idea behind the virtualization was interesting, but having to work with two repositories always caused a lot of problems. The solution was also too complex for most end users. At Incentro we support a couple of publishers who use Alfresco and publishing to the internet is only one of their channels. For these customers we always had to write custom actions to copy content from one repository to the other using the CrossRepositoryCopyService. End users, including non-technical authors, had to execute a copy action and then they where forced to navigate to the Web Project in order to deploy the content to a web server.

Starting from Alfresco 4.0 you can deploy directly from the DM (Document Management) repository to a web server. I haven’t tried it yet, but you might even be able to add a publishing channel to do the job.

This post is a follow-up to jQuery DataTables and Spring Web Scripts that focused on writing a back-end service using light weight scripting techniques. In this post we will replace the JavaScript controller with a controller written in Java. This post is just an example. In most cases you can and should use the JavaScript API. It is recommended to read the previous post before you continue.

Download the sample code

You can download the sample code here. The download contains an Eclipse project as a separate archive file. It requires Eclipse and the Alfresco SDK. You can also use a different editor if you want. The client-side code is also added in the ROOT folder. Add the ROOT folder to the webapps folder of your Alfresco Tomcat distribution and download and add the jQuery DataTables libraries to setup the client.

Import the project

To import the project start Eclipse, select File, Import and then Archive File. Select the archive file simple-search-eclipse.zip and click Finish to import the project. Once the project is imported make sure that you add the project SDK Embedded from the Alfresco SDK.

To do this download the SDK, unpack the files and then in Eclipse select File, Import, then choose Existing Projects into Workspace. In the Import dialog select the samples folder in the Alfresco SDK as root folder, select the SDK Embedded project and click Finish to import the project.

To add the SDK embedded project to the Eclipse project select Project in the menu bar, then Properties and select the Java Build Path. Click Add in the Projects tab to add the project.

What we need to do

In order to use a Java class as the controller for a Web Script, we need to write the Java source file and bind the class to our Web Script using a Spring bean declaration. The Spring bean declaration is an XML configuration file that configures the link between the Web Script and the Java class. 

We also need the Web Script descriptor file simplesearch.get.desc.xml and the view simplesearch.get.json.ftl. The file simplesearch.get.js is no longer needed. It contains the JavaScript controller that will be replaced with the Java class. We start with writing the Java code.

Add the Java class

In the source directory of your project create the following package:

com.someco.alfresco.web.scripts.bean

And add a class SimpleSearch.java as a subclass of:

org.springframework.extensions.webscripts.DeclarativeWebScript

You will end up with the following class definition:

package com.someco.alfresco.web.scripts.bean;

public class SimpleSearch extends DeclarativeWebScript {

}

In order to use Alfresco’s public services we add the ServiceRegistry. This registry provides access to all of Alfresco’s public services like the SearchService or the NodeService. You can also add the different services you need, but since we are required to provide the ServiceRegistry to a method later, we simply add the registry and use that to retrieve the services we need.

package com.someco.alfresco.web.scripts.bean;

public class SimpleSearch extends DeclarativeWebScript {

  protected ServiceRegistry serviceRegistry;

  @Override
  protected Map executeImpl(WebScriptRequest req,
    Status status) {

    return null;
  }

  public ServiceRegistry getServiceRegistry() {
    return serviceRegistry;
  }

  public void setServiceRegistry(ServiceRegistry serviceRegistry) {
    this.serviceRegistry = serviceRegistry;
  }

}

Tip: in Eclipse you can use Source, Generate Getters and Setters… to add the getter and setter methods for the serviceRegistry variable.

We start with setting the required parameters. Add the following lines to the executeImpl method:

String searchTerms = req.getParameter("sSearch");

String displayStartArg = req.getParameter("iDisplayStart");
int displayStart = 0;
try {
  displayStart = new Integer(displayStartArg);
} catch (NumberFormatException e) {
}

String displayLengthArg = req.getParameter("iDisplayLength");
int displayLength = 10;
try {
  displayLength = new Integer(displayLengthArg);
} catch (NumberFormatException e) {
}

return null;

Now that we have the required parameters, we can execute a search if the user provided a search term:

// we will use it to add the TemplateNode items
List list = new ArrayList();

int totalRecords = 0;

ResultSet results = null;

if (searchTerms != null && searchTerms.length() > 0) {

  try {
    // create the query statement
    StringBuilder query = new StringBuilder();
    query.append("TYPE:\"");
    query.append(ContentModel.TYPE_CONTENT);
    query.append("\" AND TEXT:\"");
    query.append(searchTerms);
    query.append("\"");

    // define search parameters
    SearchParameters parameters = new SearchParameters();
    parameters.addStore(Repository.getStoreRef());
    parameters.setLanguage(SearchService.LANGUAGE_LUCENE);
    parameters.setQuery(query.toString());

    // execute the query
    results = serviceRegistry.getSearchService().query(parameters);

    totalRecords = results.length();

    // get the number of items to retrieve for the current page
    int totalPageItems = Math.min(displayLength, totalRecords
        - displayStart);

    // add the nodes to the list for our model
    for (int i = 0; i < totalPageItems; i++) {
      NodeRef node = results.getNodeRef(i + displayStart);

      // the Freemarker model requires TemplateNode objects
      list.add(new TemplateNode(node, serviceRegistry, null));
    }

  } finally {
    // make sure that we close our result set to
    // avoid memory leaks
    if (results != null) {
      results.close();
    }
  }

}

And finally we build the model that will be passed to the view, our Freemarker template:

Map model = new HashMap(7, 1.0f);
model.put("iTotalRecords", totalRecords);
model.put("aaData", list);

return model;

The final Java class looks like this:

package com.someco.alfresco.web.scripts.bean;

public class SimpleSearch extends DeclarativeWebScript {

  protected ServiceRegistry serviceRegistry;

  @Override
  protected Map executeImpl(WebScriptRequest req,
      Status status) {

    String searchTerms = req.getParameter("sSearch");

    String displayStartArg = req.getParameter("iDisplayStart");
    int displayStart = 0;
    try {
      displayStart = new Integer(displayStartArg);
    } catch (NumberFormatException e) {
    }

    String displayLengthArg = req.getParameter("iDisplayLength");
    int displayLength = 10;
    try {
      displayLength = new Integer(displayLengthArg);
    } catch (NumberFormatException e) {
    }

    List list = new ArrayList();

    int totalRecords = 0;

    ResultSet results = null;

    if (searchTerms != null && searchTerms.length() > 0) {

      try {
        StringBuilder query = new StringBuilder();
        query.append("TYPE:\"");
        query.append(ContentModel.TYPE_CONTENT);
        query.append("\" AND TEXT:\"");
        query.append(searchTerms);
        query.append("\"");

        SearchParameters parameters = new SearchParameters();
        parameters.addStore(Repository.getStoreRef());
        parameters.setLanguage(SearchService.LANGUAGE_LUCENE);
        parameters.setQuery(query.toString());

        results = serviceRegistry.getSearchService().query(parameters);
        totalRecords = results.length();

        int totalPageItems = Math.min(displayLength, totalRecords
            - displayStart);

        for (int i = 0; i < totalPageItems; i++) {
          NodeRef node = results.getNodeRef(i + displayStart);
          list.add(new TemplateNode(node, serviceRegistry, null));
        }

      } finally {
        if (results != null) {
          results.close();
        }
      }

    }

    Map model = new HashMap(7, 1.0f);
    model.put("iTotalRecords", totalRecords);
    model.put("aaData", list);

    return model;
  }

  public ServiceRegistry getServiceRegistry() {
    return serviceRegistry;
  }

  public void setServiceRegistry(ServiceRegistry serviceRegistry) {
    this.serviceRegistry = serviceRegistry;
  }

}

I did not add all the import statements. In Eclipse you can organize imports using Source and then Organize Imports (Ctrl+Shift+O).

Add the Spring bean declaration

You can read more about the Spring bean declaration for a Java backed Web Script at Alfresco’s Wiki. Create a file called web-scripts-application-context.xml in the folder config/extension and add the following lines:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN 2.0//EN' 
  'http://www.springframework.org/dtd/spring-beans-2.0.dtd'>
<beans>
  <bean id="webscript.com.someco.samples.simplesearch.get" 
    class="com.someco.alfresco.web.scripts.bean.SimpleSearch"
    parent="webscript">
    <property name="ServiceRegistry" ref="ServiceRegistry" />
  </bean>
</beans>

What is important here is that the bean id follows the pattern below:

id="webscript.[packageId].[serviceId].[httpMethod]"

The packageId is the folder where the web script descriptor is located, the serviceId is the name of the service and the method is for example get or post. Also make sure that you set the parent bean to webscript.

Add the descriptor

Finally we need to add the descriptor and the view to the project. These files are the same files as we used for the previous Spring Web Scripts post with the JavaScript controller. First create the following folder in the project:

config/extension/templates/webscripts/com/someco/samples

Next create a file simplesearch.get.desc.xml and add the following lines to the file:

<webscript>
  <shortname>Simple Search</shortname>
  <description>Simple Search Example</description>
  <url>com/someco/simplesearch</url>
  <authentication>user</authentication>
  <format default="json">argument</format>	
</webscript>

Add the view

Then create a file simplesearch.get.json.ftl and add the following Freemarker code:

<#escape x as jsonUtils.encodeJSONString(x)>
{
  "iTotalRecords": ${iTotalRecords}, 
  "iTotalDisplayRecords": ${iTotalRecords},
  "aaData": [
  <#list aaData as child>
    [
    "${child.name}",
    "${child.properties["cm:title"]!""}",
    "${child.properties["cm:author"]!child.properties["cm:creator"]}",
    "${child.properties["cm:modified"]?string("yyyy-MM-dd")}"
    ]<#if child_has_next>,</#if></#list>
  ] 
}
</#escape>

The last two files are no different from the descriptor and the view from the previous post about Spring Web Scripts. We are now ready to deploy the code.

Deployment

To be able to deploy this code check the build.properties file to make sure that the properties refer to your Alfresco distribution and to the Alfresco SDK. Then return to Eclpse, select Window and then Show View and select Ant. In the Ant View click the plus sign and add the build.xml from the Simplesearch project. Click deploy to deploy the code and restart Alfresco.

The Ant build tool writes the Java library simplesearch.jar to the WEB-INF/lib directory and the Web Script files to WEB-INF/classes/alfresco/extension. Make sure to remove the previous Spring Web Script to avoid a naming conflict.

Login to Alfresco and navigate to the Web Script maintenance page to check if the Simple Search service is a registered Web Script:

http://localhost:8080/alfresco/service/

Reload the client page

When you reload the same client HTML file simplesearch.html as we used for the previous post located in the ROOT project, you should see the same result:

The main difference is that we did not add sorting to our server-side code.

Add sorting

You can add sorting by adding the parameters for sorting to the class file like we did for the page length and skipcount. To map the column number to a property in Alfresco you can add a static Map.

In order to sort you need to provide a search parameter with the name of the field and a boolean value for ascending order (true) or descending order (false). The field name must be provided in the so called Clark notation preceded by an at sign (@):

@{http://www.alfresco.org/model/content/1.0}name

The following code snippet shows how you can add the sort order to the list of search parameters:

parameters.addSort("@" + ContentModel.PROP_NAME.toString(), true);

Conclusion

In this post I returned to Spring Web Scripts to show how you can replace a JavaScript controller with a Java based controller. In most cases you should be fine writing the controller using JavaScript, but in cases where you need to execute a task that is not easily done using JavaScript, you can use Java.

Read the previous tutorials

Read the related three posts jQuery DataTables and Spring Web Scripts, jQuery DataTables, CMIS and Alfresco and jQuery DataTables and Alfresco.

Share Extras provides a collection of easy-to-install add-ons for Alfresco Share 3.3 and 3.4, providing dashlets, document actions and more.

Alfresco kicked off their fiscal year with a meeting last week in Orlando. About 100 Alfresco employees and 50 partners attended two days of Alfresco-led talks on business and technical topics.

This tutorial, the third covering jQuery DataTables and Alfresco, focuses on writing your own back-end services. After working with Alfresco’s OpenSearch interface and CMIS services, we will create a Web Script enabling the user to search for content and display the results in a table. You can find references to the other two related posts at the end of this tutorial.

Download the sample code

You can download the sample code here.

Goals

The goal of this tutorial is to demonstrate how easy it is to write your own services using Spring Web Scripts. A Web Script is a service bound to a URI which responds to HTTP methods such as GET or POST.

Spring Web Scripts

Spring Web Scripts is part of the Spring Surf extension project and provides an implementation of the Model View Controller (MVC) pattern, a well known design pattern used by web developers to design user interfaces. 

In this pattern the model represents the non-visual objects that contain the information we want to show, the view contains the presentation of this information in the user interface and the controller handles all the changes we make to the information. With Web Scripts you can implement this pattern using light weight scripting technologies like JavaScript for the controller and Freemarker for the view. You can also implement the controller using Java.

The Web Script Framework was originally developed by Alfresco, but it was donated to Spring Source because developing web frameworks is not Alfresco’s core business.

Create the Web Script

We will start with writing the backend service. To create a Web Script you first decide what URI to use for your service and what parameters are required in order to execute the behaviour that sits behind the URI. As an example we create a service that can be accessed using the following URI:

http://localhost:8080/service/com/someco/simplesearch

This service requires no parameters, but it will only return results when the user provides a search parameter. Two additional parameters are used for the page size and the skip count.

We can specify our service using a descriptor file like this:

<webscript>
  <shortname>Simple Search</shortname> 
  <description>Simple Search Example</description>
  <url>/com/someco/simplesearch</url>
  <authentication>user</authentication>
</webscript>

This script will simply forward any parameters to the controller. It is recommended to specify the required and optional parameters using a URI Template, but for now we will leave it this way.

Save this file as simplesearch.get.desc.xml in the following directory of your Alfresco distribution:

tomcat/shared/classes/alfresco/templates/webscripts/com/someco/sample

Add the controller

Now that we defined our service, we can write the controller. Create a file simplesearch.get.js in the same folder where we saved the descriptor file and add the following lines:

var iDisplayLength = 10;
var iDisplayStart = 0;

if (args.iDisplayLength != undefined && args.iDisplayLength.length > 0) 
{
  iDisplayLength = Number(args.iDisplayLength);
}

if (args.iDisplayStart != undefined && args.iDisplayStart.length > 0) 
{
  iDisplayStart = Number(args.iDisplayStart);
}

var nodes = new Array();

if (args.sSearch != undefined && args.sSearch.length > 0) 
{
  var result = search.luceneSearch("TYPE:\"cm:content\" AND TEXT:\"" + args.sSearch + "\"");

  var iTotalRecords = result.length;
 
  var totalPageItems = Math.min(iDisplayLength, iTotalRecords - iDisplayStart);

  for (i = 0; i < totalPageItems; i++){
    nodes.push(result[iDisplayStart+i]);
  }
}

model.aaData = nodes;
model.iTotalRecords = iTotalRecords;

This script basically checks the request parameters for the number of items to return per page and where to start (the skipcount) and if there is a search term provided it executes a search for content items that contain the search terms.

To implement paging raises an issue with Alfresco. Alfresco’s JavaScript Search Service supports paging, but it will not return the total number of items. Alfresco uses Lucene and Lucene does not provide a count function either.

So to support paging the total number of records is first retrieved and then the number of items to actually retrieve are calculated using the iDisplayLength, the iTotalRecords and iDisplayStart variables. The items are then retrieved from the result set and added to an Array:

var result = search.luceneSearch("TYPE:\"cm:content\" AND TEXT:\"" + args.sSearch + "\"");

var iTotalRecords = result.length;
 
var totalPageItems = Math.min(iDisplayLength, iTotalRecords - iDisplayStart);

for (i = 0; i < totalPageItems; i++){
  nodes.push(result[iDisplayStart+i]);
}

Finally the array containing the nodes and the total number of items are added to the model:

model.aaData = nodes;
model.iTotalRecords = iTotalRecords;

This model is passed to the view in order to create the response.

Add the view

Since we write our own service we can allow our service to return a data format that is fully supported by jQuery DataTables. First create a file called simplesearch.get.json.ftl. Open this file and add the following lines:

<#escape x as jsonUtils.encodeJSONString(x)>
{
  "sSearch": "${sSearch!""}", 
  "iTotalRecords": ${iTotalRecords}, 
  "iTotalDisplayRecords": ${iTotalRecords},
  "aaData": [
  <#list aaData as child>
	[
	"${child.name}",
	"${child.properties["cm:creator"]}",
	"${child.properties["cm:created"]?string("yyyy-MM-dd")}"
	]<#if child_has_next>,</#if></#list>
  ] 
}
</#escape>

This template will create a response like this:

{
  "iTotalRecords": 2, 
  "iTotalDisplayRecords": 2,
  "aaData": [
    ["example test script.js","System","2011-03-17"],	
    ["create-test-content.js","admin","2011-03-20"]
  ] 
}

Reload the Web Scripts Registry

Before we can use this new service we need to reload the Web Scripts Registry in Alfresco. Login to Alfresco as administrator and then go to the following URL:

http://localhost:8080/alfresco/service/

At the bottom of this page you should see a button with the text Refresh Web Scripts. Click this button to refresh. Once Alfresco is finished you should see a message that maintenance is completed. In addition you should see that Alfresco added a Web Script to the Web Script Registry:

Reset Web Scripts Registry; registered 381 Web Scripts. Previously, there were 380.

You can browse to the page for the web Script using Browse by Web Script Package and then by clicking the com/someco/sample package. You should see a page simlar to this:

By clicking the link behind the id Alfresco will return a page with all the details for the Web Script including the descriptor and the code for the controller and the view.

We can now test our Web Script by visiting the following URL:

http://localhost:8080/alfresco/service/com/someco/simplesearch

This request should return a JSON Array.

Debugging Web Scripts

You can change some settings in the log4.properties file to enable debugging for the JavaScript controller. Open the file in a text editor (it is located in the WEB-INF/classes directory of the Alfresco web application) and look for the following lines:

# Web Framework
log4j.logger.org.springframework.extensions.webscripts=info
log4j.logger.org.springframework.extensions.webscripts.ScriptLogger=warn
log4j.logger.org.springframework.extensions.webscripts.ScriptDebugger=off

You can set the first two lines to debug and the debugger to on. When you add log statements to the controller code, the statements will be written to the log file. For example:

logger.log("Total records: " + iTotalRecords);

When you use the script debugger, Alfresco will open a debugger once you execute a Web Script. The debugger allows you to step through the code at run-time and it enables access to all the objects loaded by the script.

Create the client page

The final step is to create the client page. I used the same ROOT folder in the webapps folder for my Alfresco distribution as I used for the other two posts about DataTables and Alfresco. Create a file simplesearch.html in the ROOT folder. This folder should also contain the jQuery DataTables libraries. See the post jQuery DataTables and Alfresco for more details. Next add the following lines to the file:

<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>jQuery DataTables Simple Search</title>
    <style type="text/css" title="currentStyle">
      @import "media/css/demo_page.css";
      @import "media/css/demo_table.css";
    </style>
    <script type="text/javascript" src="media/js/jquery.js"></script>
    <script type="text/javascript" src="media/js/jquery.dataTables.js"></script>
    <script type="text/javascript" src="media/js/jquery.setFilteringDelay.js"></script>			
    <script type="text/javascript" charset="utf-8">
      $(document).ready(function() {
        $('#example').dataTable( {
          "bServerSide": true,
          "bPaginate": true,
          "sPaginationType": "full_numbers",
          "sAjaxSource": "http://localhost:8080/alfresco/s/com/someco/simplesearch",
          "fnInitComplete": function(){this.fnSetFilteringDelay(500)},
          "fnServerData": function ( sSource, aoData, fnCallback ) {
            $.getJSON( sSource, aoData, function (json) { 
              fnCallback(json);
            } );
          },
          "bFilter": true,
          "bSort": false,
          "bInfo": true
        } );
      } );
    </script>
  </head>
  <body id="dt_example">
    <div id="container">
      <div id="dynamic">
        <table cellpadding="0" cellspacing="0" border="0" class="display" id="example">
          <thead>
            <tr>
              <th width="60%">Name</th>
              <th width="20%">Creator</th>
              <th width="20%">Modified</th>
            </tr>
          </thead>
        <tbody>
          <tr>
            <td colspan="7" class="dataTables_empty">Loading data from server</td>
          </tr>
        </tbody>
      </table>
    </div>
  </body>
</html>

Since our service returns a JSON Array that is compatible with the data format that DataTables uses, there is no need to post process the response to create the JSON Array like we had to do in the previous posts. If you load this page in your web browser you should see a similar response page:

Update the view

We can now update the view, for example to add the actual name of the author as a replacement for the creator. Since the information is already available in the model, the only thing you need to do is to revisit the Freemarker template that creates the JSON reponse:

<#escape x as jsonUtils.encodeJSONString(x)>
{
  "sSearch": "${sSearch!""}", 
  "iTotalRecords": ${iTotalRecords}, 
  "iTotalDisplayRecords": ${iTotalRecords},
  "aaData": [
  <#list aaData as child>
	[
	"${child.name}",
	"${child.properties["cm:author"]!${child.properties["cm:creator"]}",
	"${child.properties["cm:created"]?string("yyyy-MM-dd")}"
	]<#if child_has_next>,</#if></#list>
  ] 
}
</#escape>

When you only update the view, there is no need to refresh the Web Scripts Registry. Simply refreshing the page should update our table with proper author names.

Add a column

To add a column we need to add a field to the view simplesearch.get.json.ftl and a column to the table in simplesearch.html. First add the following line to the Freemarker template right under the name property:

"${child.properties["cm:title"]!""}",

Next add the following table heading to the table definition in the HTML file:

<thead>
  <tr>
    <th width="30%">Name</th>
    <th width="30%">Title</th>
    <th width="20%">Creator</th>
    <th width="20%">Modified</th>
  </tr>
</thead>

Refresh the page and you should see the column added to the table:

Add sorting

Now when you set the bSort parameter in the table inizialization code to true and reload the client page, you can see that there are a couple of parameters added to the request including a parameter called iSortCol_0 that provides the column number for the first field to sort by (0). When you click the author column for example the value for the iSortCol_0 request parameter will be 1.

In addition to the sort column parameter, the request will also contain a parameter sSortDir_0 containing the sort direction.

Our JavaScript controller will receive the parameter, but since we did not add sorting to our query, the order in which the results appear will not change. To do this we need to update the controller code.

We receive the column position and not a field name, so we first add an Array with a mapping of the column numbers and the corresponding field name. Add the following at the top of the controller script:

var sortColumns = new Array();
sortColumns[0] = "@{http://www.alfresco.org/model/content/1.0}name"; 
sortColumns[1] = "@{http://www.alfresco.org/model/content/1.0}title";
sortColumns[2] = "@{http://www.alfresco.org/model/content/1.0}author";
sortColumns[3] = "@{http://www.alfresco.org/model/content/1.0}modified";

We then add the declaration for the parameters required for sorting. Add the declarations for example right under the declaration for iTotalRecords:

var sortColumn = sortColumns[0];
var sortAscending = true;

We can then set the parameters for the sorting column and the sorting direction:

if (args.iSortCol_0 != undefined && args.iSortCol_0.length > 0 && args.iSortCol_0 <= sortColumns.length) 
{
  sortColumn = sortColumns[args.iSortCol_0];
}

if (args.sSortDir_0 != undefined && args.sSortDir_0.length > 0) 
{
  if (args.sSortDir_0 == "desc")
  {
    sortAscending = false;
  }
}

We now have all the information needed to execute a query that sorts. To do this we use the query method of the JavaScript Search API. It provides extensible configuration options using a query definition. Replace the line:

var result = search.luceneSearch("TYPE:\"cm:content\" AND TEXT:\"" + args.sSearch + "\"");

With the query using the query definition:

var def =
{
  query: "TYPE:\"cm:content\" AND TEXT:\"" + args.sSearch + "\"",
  sort: [{column: sortColumn, ascending: sortAscending}]
};

var result = search.query(def);

Since the controller is updated we need to refresh the Web Scripts Registry to make the changes active. After refreshing the Web Scripts Registry you should be able to click the table headings to change the sorting column and sorting order:

Conclusion

In this post I returned to the jQuery DataTables and Alfresco to show how you can write your own back-end Spring Web Script to populate a DataTable. Web Scripts provide a simple MVC model to develop services using light-weight scripting techniques.

Read the previous tutorials

Read the related two posts jQuery DataTables, CMIS and Alfresco and jQuery DataTables and Alfresco. They cover jQuery DataTables with CMIS services and Alfresco’s OpenSearch keyword search as a back-end service.

Updates

• March 30, 2011: changed package name to conform to upcoming post about Java based Web Script.

This is a follow up to the post jQuery DataTables and Alfresco. In this tutorial we replace the OpenSearch service with a CMIS back-end service to retrieve content items from an Alfresco repository and populate a jQuery DataTable. 

Download the sample code

You can download the sample code here. The example code also provides an Alfresco JavaScript that can be used to create some content items. To do this you need to add the script to the Scripts space in the Data Dictionary and run the script using a Run Action.

About CMIS

CMIS (Content Management Interoperability Services) is SQL for content repositories. It allows access to different content management systems using an open standard maintained by OASIS. OASIS is an important consortium that develops and promotes open standards.

CMIS enables developers to create, update or delete documents or folders and to search for documents or folders using a vendor independent language. It is a very promising standard, especially since all major vendors of Enterprise Content Management software adopted the standard including Microsoft, Oracle, EMC Corporation (Documentum), IBM, SAP, Alfresco and Open Text. Alfresco was the first to provide full support for the standard.

For these examples we will use the Restful Atompub binding that uses XML as a data format. There is also an OASIS Subcommittee working on a browser binding to make it even easier to use CMIS in browser based applications. This binding will use JSON as a data format in stead of XML.

Prerequisites

This tutorial is a continuation of jQuery DataTables and Alfresco.

It might help to familiarize yourself with CMIS. For developers I can recommend the excellent CMIS introduction by Jeff Potts.

Create the file

The first step is to set up a basic HTML file for the client-side table. We will start with a simple table listing the name of the documents returned by the CMIS service. Create a file cmissearch.html in the ROOT folder that we used in the previous tutorial about DataTables and Alfresco:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>jQuery DataTables and Alfresco CMIS Example</title>
    <style type="text/css" title="currentStyle">
      @import "media/css/demo_page.css";
      @import "media/css/demo_table.css";
    </style>
    <script type="text/javascript" src="media/js/jquery.js"></script>
    <script type="text/javascript" src="media/js/jquery.dataTables.js"></script>
    <script type="text/javascript" src="media/js/jquery.setFilteringDelay.js"></script>	
    <script type="text/javascript" src="media/js/jquery.base64.js"></script>
    <script type="text/javascript">
      <!-- here we will write our client-side JavaScript -->
    </script>
  </head>
  <body id="dt_example">
    <div id="container">
      <h1>jQuery DataTables and Alfresco CMIS Example</h1>
      <div id="dynamic">
        <table class="display" id="example">
	  <thead>
	    <tr>
	      <th width="30%">Name</th>
	    </tr>
	  </thead>
	  <tbody>
            <tr>
	      <td colspan="5" class="dataTables_empty">Loading data from server</td>
	    </tr>
	  </tbody>
	</table>
      </div>
    </div>
  </body>
</html>

As you might have noticed I added a new jQuery plug-in called jquery.base64.js. We need this plug-in to encode the username and password that we need to authenticate against the CMIS service. You can find it here.

Add the template

The next step is to add a template for the CMIS request. This is a bit of a hack, but it works. This approach was inspired by this post by developer Ben Nadel. Add the following script tag to the header of the HTML file:

<script id="cmis-template" type="application/cmis-template">
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <cmis:query xmlns:cmis="http://docs.oasis-open.org/ns/cmis/core/200908/">
    <cmis:statement>SELECT cmis:name 
	  FROM cmis:document 
	  WHERE CONTAINS('${sSearch}') 
	  ORDER BY cmis:name</cmis:statement>
    <cmis:maxItems>${iDisplayLength}</cmis:maxItems>
    <cmis:skipCount>${iDisplayStart}</cmis:skipCount>
  </cmis:query>
</script>

I am going to use this template to prepare my requests to the server. It contains a query request that searches for text in content items and orders the result by name.

Initialize the DataTable

We will now setup the basic implementation of the client-side JavaScript. This part is only slightly different from the approach in the previous post about DataTables:

function fnGetJSONData( sSource, aoData, fnCallback ) {
   /* this function will execute the keyword search */
}
	
$(document).ready(function() {
  $('#example').dataTable( {
    "bServerSide": true,
    "sAjaxSource": "/alfresco/s/cmis/queries",
    "bSort": false,
    "bPaginate": true,
    "sPaginationType": "full_numbers",
    "fnInitComplete": function(){this.fnSetFilteringDelay(500)},
    "fnServerData": fnGetJSONData
  } );
} );

Implement the callback function

The final part is the implementation of the callback function. Here is the code:

function fnGetJSONData( sSource, aoData, fnCallback ) {

  var params = {};
  for ( var i=0 ; i var cmisTemplate = $( "#cmis-template" );
			
    var requestBody = cmisTemplate.html().replace('${sSearch}', params["sSearch"])
      .replace('${iDisplayStart}', params["iDisplayStart"])
      .replace('${iDisplayLength}', params["iDisplayLength"]);
			
    $.ajax( {
      "dataType": 'xml',
      "type": "POST", 
      "url": sSource, 
      "contentType" : "application/cmisquery+xml",
      "beforeSend" : function(req) {
        req.setRequestHeader("Authorization", "Basic " + $.base64Encode("admin:admin"));
      },
      "processData" : false,
      "data" : $.trim( requestBody ),
      "success": function (data,textStatus,xmlHttpRequest) {
				
        var jData = $( data );	

        var json = {"sEcho": params["sEcho"],"aaData" : []};
        json.iTotalRecords = jData.find("[nodeName='opensearch:totalResults']").text();
        json.iTotalDisplayRecords = json.iTotalRecords;
					
        var items = jData.find("entry").each(function(){
          json.aaData.push([
            $(this).find("title").text(),
          ]);
        });
           
        fnCallback(json);
      },
      error: function(){
        console.log( "ERROR", arguments );
      }
    } );					
  }
}

Even this part is not that different from what we did in the previous post. I have highlighted the major differences. 

The first step is to prepare the request body. In order to execute a CMIS query request, I created the template with id cmis-template. It contains a couple of interpolations. By using a global replace we can fill the template with our search properties:

var requestBody = cmisTemplate.html().replace('${sSearch}', params["sSearch"])
  .replace('${iDisplayStart}', params["iDisplayStart"])
  .replace('${iDisplayLength}', params["iDisplayLength"]);

The next step is the call to the backend. There are a couple of differences from the function used for the Open Search client. We need to post our data to the back-end server with a specific content type (application/cmisquery+xml) for CMIS and the service requires authentication. For now we will simply add a request header with a basic authentication:

"beforeSend" : function(req) {
  req.setRequestHeader("Authorization", "Basic " + $.base64Encode("admin:admin"));
},

When posting data we need to add the request to the request body. By setting the processData parameter to false, we can prevent the request method to process our request data. Otherwise it will try to convert our request body into request parameters.

I also applied the trim function to the request body to remove leading and trailing whitespace:

"data" : $.trim( requestBody ),

This is all we need to do in order to execute the request to the server.

In order to populate the table, we need to convert the XML response into a JSON array. This part is quite similar to the OpenSearch examples of the previous post about DataTables. We add the skipcount and the total number of records returned by the search and then iterate over the entries of the Atom feed to add a title for each content item retrieved by the query request:

var json = {"sEcho": params["sEcho"],"aaData" : []};
json.iTotalRecords = jData.find("[nodeName='opensearch:totalResults']").text();
json.iTotalDisplayRecords = json.iTotalRecords;
					
var items = jData.find("entry").each(function(){
  json.aaData.push([
    $(this).find("title").text(),
  ]);
});

Now if we test this client page the result should be similar to this:

Add columns

Once this is done we can easily extend our table to provide additional information. To add the name, the author and the modified date, for example, you only need to add the parameters to the JSON array:

var items = jData.find("entry").each(function(){
  json.aaData.push([
    $(this).find("*[propertyDefinitionId='cmis:name']").find("[nodeName='cmis:value']").text(),
    $(this).find("title").text(),
    $(this).find("author").text(),
    $(this).find("updated").text()
  ]);
});

And the columns to the table:

<thead>
  <tr>
    <th width="30%">Name</th>
    <th width="30%">Title</th>
    <th width="20%">Author</th>
    <th width="20%">Updated</th>
  </tr>
</thead>

A tool like Firebug can be helpful here to analyze the response from the server to figure out how to retrieve the values from the XML returned by the CMIS service.

When you reload the page and execute a search you will now see a page similar to this:

Retrieving aspects

This table does not display the values for the title and author that we entered as author and title in Alfresco. They are the name and created properties in stead. In order to show the desired author and title, we need to extend our query to retrieve the author and title that are part of the so called cm:titled and cm:author aspects.

Aspects are an important content modeling concept in Alfresco. They provide a more dynamic way to add metadata properties to documents and folders. For Alfresco developers it is a best practice to use aspects to create a content model. Even when you need content types it is recommended to create aspects for logical chunks of metadata and add them to a type definition as mandatory aspects. Aspects provide much more flexibility and make your content model easier to maintain. Aspects however are not recognized by CMIS as a concept, although that might change in a future version.

To add the properties from the aspects that contain the author and title information we need to add two joins to our query:

SELECT d.*, t.*, a.* 
  FROM cmis:document AS d 
  JOIN cm:titled AS t ON d.cmis:objectId = t.cmis:objectId 
  JOIN cm:author AS a ON d.cmis:objectId = a.cmis:objectId 
  WHERE CONTAINS(d,'${sSearch}') 
  ORDER BY d.cmis:name

Note: when you add aspects to your query using JOIN the search will only return folders or documents that have these aspects applied.

Additionally you can use IN_FOLDER() to match the immediate children of a folder or IN_TREE to match any object beneath the folder:

SELECT d.*, t.*, a.*
  FROM cmis:document AS d 
  JOIN cm:titled AS t ON d.cmis:objectId = t.cmis:objectId 
  JOIN cm:author AS a ON d.cmis:objectId = a.cmis:objectId 
  WHERE IN_FOLDER(d, 'workspace://SpacesStore/40312a4b-7767-4586-a58b-18d050ffe0ca')
  AND CONTAINS(d,'${sSearch}')
  ORDER BY d.cmis:name

To match docments that follow the file name pattern *.txt you can add a LIKE predicate to the WHERE clause for the cmis:name property:

SELECT d.*, t.*, a.*
  FROM cmis:document AS d 
  JOIN cm:titled AS t ON d.cmis:objectId = t.cmis:objectId 
  JOIN cm:author AS a ON d.cmis:objectId = a.cmis:objectId 
  WHERE IN_FOLDER(d, 'workspace://SpacesStore/40312a4b-7767-4586-a58b-18d050ffe0ca') 
  AND CONTAINS(d,'${sSearch}')
  AND d.cmis:name LIKE '%.txt'
  ORDER BY d.cmis:name

Once we added the aspects, we can retrieve the actual values for the author and the title using the following code:

var items = jData.find("entry").each(function(){
  json.aaData.push([
    $(this).find("*[propertyDefinitionId='cmis:name']").find("[nodeName='cmis:value']").text(),
    $(this).find("*[propertyDefinitionId='cm:title']").find("[nodeName='cmis:value']").text(),
    $(this).find("*[propertyDefinitionId='cm:author']").find("[nodeName='cmis:value']").text(),
    $(this).find("updated").text()
  ]);
});

When we reload this page we will see the actual author and title properties:

Add some formatting

Finally we will add some formatting to our table by adding an icon to the name column and by formatting the date. In order to format the date I added a custom jQuery UI library with only the core component and the jQuery UI Datepicker. The datepicker contains a date parser and formatter that is able to process a date in ISO8601 format as used by the Atom publishing protocol. Add the jQuery UI library to the header of the page:

<script type="text/javascript" src="media/js/jquery-ui-1.8.11.custom.min.js"></script>

I added the reference to the icon to the JSON array:

var items = jData.find("entry").each(function(){
  json.aaData.push([
    $(this).find("[nodeName='alf:icon']").text(),
    $(this).find("*[propertyDefinitionId='cmis:name']").find("[nodeName='cmis:value']").text(),
    $(this).find("*[propertyDefinitionId='cm:title']").find("[nodeName='cmis:value']").text(),
    $(this).find("*[propertyDefinitionId='cm:author']").find("[nodeName='cmis:value']").text(),
    $(this).find("updated").text()
  ]);
});

And the column for the icon to the table:

<thead>
  <tr>
    <th width="0%">Icon</th>
    <th width="30%">Name</th>
    <th width="30%">Title</th>
    <th width="20%">Author</th>
    <th width="20%">Updated</th>
  </tr>
</thead>

And finally I added the column rendering to the table initialization code after the sPaginationType parameter:

"aoColumns": [
  {"bVisible": false},
  { "fnRender": function ( oObj ) {
    return '<img src="' + oObj.aData[0] + '" alt="Icon" /> ' + oObj.aData[1];
  } },
  null,
  null,
  { "fnRender": function ( oObj ) {
    var updated = $.datepicker.parseDate($.datepicker.ATOM, oObj.aData[4]);
    return $.datepicker.formatDate('yy-mm-dd', updated);
  }}
],

Now if you reload the page and execute a query the result should look similar to this page:

Conclusion

In this post I returned to the jQuery DataTables to show how you can use the CMIS standard to populate a DataTable using a CMIS service request. I used Alfresco for this example, but this approach should also work for other systems that support CMIS (except for the joins to include the aspects). Once the CMIS browser binding is finalized, it will be even easier to develop CMIS clients using a framework like jQuery or YUI since it will replace the XML data format with JSON.

Read the previous tutorial

Read the first post jQuery DataTables and Alfresco. It covers jQuery DataTables with Alfresco’s OpenSearch keyword search as a back-end service. Read the third post in this series here. It covers jQuery DataTables and Spring web Scripts.

Update History

• March 22, 2011: added formatting section and reference to previous tutorial
• March 23, 2011: added note about aspects and some additional query examples
• March 27, 2011: added a reference to the third tutorial in this series

Today Alfresco released Alfresco Enterprise 3.4.0. This new release contains some important new features including language packs for French, German, Italian, and Spanish.

Collaboration

There are several new features in Alfresco Share, their collaboration interface, including advanced search and full support for advanced workflow. There are also some improved options for site visibility. You can now control which users can see public sites to support an extranet use case. There is also support for content transfers between Alfresco environments to enable content replication and the form engine is improved and provides more user interface controls.

Repository

With this release Alfresco also moved from Hibernate to Apache iBatis for the storage of objects in the database and for data access. This provides more control resulting in better scalability and increased performance.

DeckShare is built on top of Alfresco’s new Web Content Management (WCM) offering called Web Quick Start. Honestly, Web Quick Start, as the name implies, provides a good starting point for building a dynamic web site on top of Alfresco, and the sample site was so close to what a basic slide-sharing site needed, we didn’t have to do a whole lot of work. Even so, if you want to do slide-sharing on top of Alfresco, you can save even more time by starting with DeckShare.

Alfresco 3.4.c Community release has just been released, and there are a few enhancements to Web Quick Start that are worth a mention.

Last week I attended the Alfresco Developer Conference in Paris and one of the things I realized during the conference was how many core parts of Alfresco are currently being refactored.

Persistency Layer
One major change is that they replaced the Hibernate persistency layer with iBATIS. This layer is responsible for writing objects to the database, performing database queries and reading objects from the database. Some parts of Alfresco already used iBATIS, but starting with version 3.4 Hibernate is completely removed in favor of iBATIS. According to Alfresco the new persisteny layer provides more control resulting in an improved performance, scalability and stability.

Domain Model
They also moved the code for the domain model from the repository project to a separate project in the code repository. The new project is called data-model. The main reason for this is to prepare the replacement of Lucene with Solr, an enterprise search platform based on Lucene. Solr provides a better separation of concerns and has a lot of features that are not available in Lucene. Solr provides features like clustering and replication, hit highlighting and faceted search. I expect the integration of Solr to be a major improvement. As far as I know it is not yet on the road map, so it is unclear when it will be released. I expect Alfresco to use a more loosely coupled approach here. In the future this might even make it possible to configure Alfresco to use a different search engine.

Workflow
Although starting with version 3.4 Alfresco Share supports the advanced worklfow capabilities based on the current workflow engine, this is likely to change in the near future. A team of Alfresco developers is currently developing a complete new BPM and workflow system called Activiti. The presentations at the conference looked very promising. Activiti is based on the general purpose process language BPMN 2.0 and attempts to bring together developers and business people. It fits into any Java based application, but also provides web based clients to directly support end users.

Web Content Management
Another big project is the replacement of the WCM (Web Content Management) module. Currently WCM support is only available in the Alfresco Explorer interface and under the hood it uses a repository implementation that is not compatible with the regular content repository. A couple of sessions at the conference discussed new core services that will be used by a new WCM module that is currently under development. These include the Transfer Service and the Rendition Service, but there are also major changes in the Action Service.

Web Quick Start
To demonstrate the new capabilities, the Alfresco team created a Web Quick Start application that you can use to create a dynamic web site with Alfresco Share as content management backend. I was suprised by the amount of features they put into the application. It is highly configurable and includes a reusable domain model, support for content renditions, deployments to test and live servers and even content caching. The frontend is build using Spring Surf, CMIS and Web Scripts.

At the same time the quick start application reveales how much there is to be done. It is currently not possible to deploy static content to a web server, there is no support for custom content types or XML content editing, there is no such thing as a Web Project or Web Project Site and there is no overall lifcycle in place to create, approve, publish, expire and monitor web content.

Alfresco Share
Of course Alfresco Share itself is also an ongoing project with a major impact. With every release new features are added to improve the collaboration capabilities and to provide general content management features currently only available in Alfresco Explorer. It will take a while before Alfresco Share completely replaces Alfresco Explorer, but today Share provides a serious alternative to Microsoft Sharepoint. Alfresco is also constantly improving the configuration options for Alfresco Share to make it more simple to tailor the system to customer needs.

Although Share is a major improvement for end users compared to Alfresco Explorer, I am still not fully convinced that Alfresco made the right decision to build a client using the Yahoo User Interface (YUI). For developers the learning curve is very steep and I am not sure if the library is future proof. I guess if someday Alfresco wanted to move to a newer version of YUI, they have to rebuild most of the client interface since for version 3 the developers at Yahoo decided to completely rebuild the library.