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.
Environment
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
c:\projects\surf-alfresco>roo
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:
<user-factory>webframework.factory.user.alfresco32</user-factory>
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"/>
To:
<input name="success" type="hidden"
value="${url.context}/sample/userinfo"/>
<input name="failure" type="hidden"
value="${url.context}/sample/login"/>
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:
roo>exit
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:
<webscript>
<shortname>Company Posts</shortname>
<description>Company Posts</description>
<url>/news/posts</url>
<authentication>user</authentication>
</webscript>
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");
logger.log(result);
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:
<div>
<#if posts.items?exists>
<#list posts.items as post>
<h2>${post.title}</h2>
${post.content}
</#list>
<#else>
There are no posts.
</#if>
</div>
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:
roo>exit
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.
Conclusion
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.
View Bas Peters's Linkedin profile
