On almost every topic
Spring Surf with an Alfresco backend

Spring Surf is actively under development. Recently authentication against Alfresco was added to the Surf Quick Start application making it very simple to add an Alfresco backend to your Surf application. To get an idea in what direction this is heading to, I added a page to the example application that displays blog posts from Alfresco Share. The page requires authentication.

Note: this tutorial demonstrates Spring Surf features that are not stable yet.


I have an Alfresco Enterprise 3.2r backend running on http://localhost:8080/alfresco and will run Jetty on my Surf project. I guess it will also work with Alfresco Community. Make sure that you have Maven installed.

Download Spring Roo

The first step is to download and install Spring Roo from the Spring Source Community download page at http://www.springsource.com/download/community. Spring Roo is a rapid application development tool for Java developers focusing on productivity and ease of use.

The next step is to download the latest snapshot for the Spring Surf Roo Addon from http://www.springsurf.org/downloads.html. Of course you can also create a new build. Check the Spring Source Development Guide for instructions on how to do this. In order to build from source you need a Subversion client and Maven. Add the snapshot for Roo to the dist directory of your Roo installation (on my Windows machine it is C:\Apps\spring-roo-1.0.2.RELEASE\dist). It might be useful to open the Surf Roo Command Index as a reference.

Create a project

We are now ready to create a new project with Roo. From the command line navigate to a directory where you want to create your application, create a new directory for your Surf application and start the Roo shell:

c:\projects>mkdir surf-alfresco

c:\projects>cd surf-alfresco


Your Roo shell looks similar to this:

We are now ready to start coding. First create a new project:

roo>project --topLevelPackage com.example.surf

Tip: roo supports completion using the TAB key, so if you type project and then TAB roo will suggest to add the topLevelPackage argument.

Now install Surf:

roo>surf install

When you install Surf, Roo creates an example application to get you started. We will add authentication to this application and a new page showing blog posts from an Alfresco Share site called Company.

Enable authentication

In order to to enable authentication against the Alfresco repository, open the file surf.xml in the src/main/webapp/WEB-INF directory and comment out the following line:


In addition I made some changes to the file login.ftl in the src/main/webapp/WEB-INF/templates/sample directory. I changed these lines:

<input name="success" type="hidden" value="/"/>
<input name="failure" type="hidden" value="/type/login"/>


<input name="success" type="hidden" 
<input name="failure" type="hidden" 

This will show the user information on a successful login and the login page when the login is not successful. The templates for login, logout and the user information are already added as example templates.

Test the application

You can now test the application. To do this exit roo and run Jetty:

c:\apps\surf-allfresco>mvn jetty:run

Make sure Alfresco is also running and visit the Surf application by visiting http://localhost:8180/

You should see the following page. This is the example application we created by installing Surf:

Now visit the page http://localhost:8180/sample/login. You should see a page like this:

Type an Alfresco user name and password en click Log In. The system should now display the login details.

You are now able to authenticate, so the next step is to add a page that requires the user to login. To stop Jetty you can simple type Ctrl-C.

Note: you are not required to stop Jetty, you can also open a new command shell. Jetty will notice changes and do a reload.

Create a new component

We start with creating a new Surf component. Surf components basically are Web Scripts. If you are not familiar with Web Scripts, you might want to read some documentation first. You can find it here.

First we create a folder called posts under the WEB-INF/webscripts directory. We then create a new file called posts.get.desc.xml with the following content:

  <shortname>Company Posts</shortname>
  <description>Company Posts</description>

This is the descriptor for our new component. It provides a name and description and a URL to provide access to the resource. We also set the authentication to user, since we require the user to be authenticated when he/she requests blog posts. By default authentication is set to none.

The next step is to create the controller. The controller knows what to do when the user requests the resource (in this case showing the blog posts stored in Alfresco). The controller is implemented using JavaScript. Create a file called posts.get.js with the following contents:

var connector = remote.connect("alfresco");
var result = connector.get("/api/blog/site/company/blog/posts");
var posts = eval('(' + result + ')');
model.posts = posts;

The connector’s get method retrieves the blog posts from a site called company. You can change company with the name of any Alfresco Share site. If you do not have a site yet, you can create one and add some blog posts to it.

The final part of the component is the view. The Web Scripts Framework uses Freemarker as the default template engine. Create a file called posts.get.html.ftl and add the following contents:

<#if posts.items?exists>
  <#list posts.items as post>
There are no posts.

I must admit that this template is not going to return a stunning web page, but for now it will work just fine.

One final change I made is to forward the user to the news page on a succesful login in stead of the user information by editing the login.ftl once more:

<input name="success" type="hidden" value="${url.context}/news" />

Create a new page

We now have to revisit Roo to create a new page, add the required components to the page including our blog posts component and to add the page to the site navigation. To do this start Roo and first create the page:

roo> surf page create --id news --template home

We create a new page based on the existing template for the Home Page. Next we add the blog posts to the main region of the page:

roo> surf component create --page news --region main
  --url /news/posts

We can then run a report to see if we need to add addditional components:

roo> surf report page --id news
Report on Page news

Basic Information

Id: news
Name: news
Path: pages\news\news.xml
Instance: home
Template: home
Page Scoped Components

Region: main Url: /news/posts
Region: side Scope: page Configued: false

Template Scoped Components

Region: header Url: /company/header
Region: horznav Url: /navigation/horizontal
Region: footer Url: /company/footer

Global Scoped Components

Page Associations


It seems that the component for the side region is missing, so we simply add the same component as the one used for the home page. I simply looked it up in the file pages/home/home.xml and it is the component /home/side:

roo> surf component create --page news --region side 
  --url /home/side

The last thing we need to do is to add our new page to the horizontal navigation by creating an association between the page home and our new page called news:

code>roo> surf page association create --sourceId home 
  --destId news

We can now exit Roo:


Before starting Jetty again, visit the page news.xml and set authentication to user instead of none. Save the file and run Jetty again.

c:\projects\surf-alfresco>mvn jetty:run

Test the new page

Now test the application by visiting http://localhost:8180 again. You should see a news button added to the horizontal navigation:

When you click the news page, the system shows the login page again and returns to the news page on a successful login:

We now have added a page to Surf’s Quick Start application that enables the user to authenticate against Alfresco and read blog posts stored in the backend repository.


Spring Surf and Spring Roo provide a very promising development approach enabling the Java developer to focus on getting things done without having to create huge amounts of code and a lot of configuration files. The built-in support for Alfresco makes Surf a perfect framework to build your Alfresco front-end application. With the upcoming CMIS (Content Management Interoperability Services) standard we will even have a standard interface to access content repositories.

The upcoming Alfresco book Professional Alfresco (ISBN 978-0-470-57104-0) is now available for pre-order at Amazon. I look forward to this publication since it is written by Alfresco insiders including CTO John Newton, Chief Architect David Caruana and product managers Mike Farman and Michael Uzquiano. The book will be published by Wrox Press and is expected to be available in May.

Professional Alfresco seems to focus on developing Alfresco extensions using light-weight scripting technologies. This topic is increasingly important for Alfresco developers and only covered to some extend in the other books available about Alfresco. The Alfresco Developing Guide by Jeff Potts focuses more on writing Java customizations and Alfresco 3 Enterprise Content Management Implementation focuses on the out of the box functionalities and configuration options. From the Table of Contents it is difficult to judge if the book covers more advanced topics related to Web Scripts, Surf and Share development.

This “work in progress” looks very promising. Together Spring Surf and OpenCMIS will provide a platform for building CMIS enabled web applications.

Spring Surf documentation

I am positively surprised about the amount of documentation that is already available for the Spring Surf project. Spring Surf is a web application framework based on light weight scripting technologies. It used to be part of the Alfresco software stack, but they decided to contribute it to Spring Source. Alfresco’s primary concern is to deliver a first class content management platform and not a web framework. There are some strong concepts behind the Surf framework, but the lack of tooling and documentation made it almost impossible to use it in real world projects, although Alfresco managed to build their collaboration product on top of this framework.

Spring Surf is basically 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. In Spring Surf you can implement this pattern using light weight scripting technologies like JavaScript for the controller and Freemarker for the view.

One of the drawbacks of Spring is that the framework requires a lot of configuration and Spring Surf is no exception. Thanks to frameworks like Ruby on Rails, that introduced new concepts like convention over configuration and scaffolding, the Spring Source community realizes that developers need tools right from the start to avoid a steep learning curve and to reduce development cycle times. Spring Surf provides an Eclipse plugin and the command-line tool Roo to get you started and these tools look promising.

But the best is yet to come and that is support for the Content Management Interoperability Services (CMIS) standard. Once available this technology will enable developers to create web applications against content management back-ends like Alfresco using an approach similar to the way you use SQL to talk to a relational database.