Resource Center

Using REST services and HTML5

Overview

eXo Platform 3 provides a powerful web-based IDE that makes it easy to build a complete web application. Not only does it allow you to write client side code, like gadgets and HTML, but you can also easily deploy code in the Platform's back-end to create your own APIs. Using REST architecture and Ajax calls, developers can separate the data interface from the user interface and therefore build different interfaces depending on the device used to browse the web.

To demonstrate the speed and ease of development in the eXo IDE, we have built a sample app for displaying WCM content in an iPhone browser. The app consumes REST services from eXo Platform, and displays the data in an HTML5 webpage that can store the data in the browser's database.

The application has two components:

• The back-end: REST services deployed in eXo Platform using Groovy language and the JAX-RS library. It exposes taxonomy categories and news articles stored in eXo Platform's Web Content Management (WCM) system in JSON format.
• The front-end: an HTML5 and JavaScript web page that consumes the REST services and displays the data. In this case we will build an iPhone User Interface using the jQtouch library, and the data will be stored in the browser's database for offline access.

Preparation

• Download the latest version of eXo Platform 3 here or connect to the online demo here.
• Start the Platform and login to the Social Intranet as John Smith.
• In the "My Spaces" drop-down menu, select IDE.

Deploying the REST services

eXo Platform 3 offers a set of REST services to access some resources and application logic, but if these APIs do not fit your needs, it is very easy to create a custom API on the fly that can be deployed in the platform.

The first step is to write the REST service, which requires a working knowledge of the eXo Java APIs and of the eXo Java Content Repository. For the WCM Services, the documentation can be found here.

Start by creating a "rest" folder where we will add all the server-side code. To write our service, we will need a couple utility classes that we will help us build our JSON response. Create a "utils" folder, and add the following classes:

• CategoryNode.groovy
• DocumentContent.groovy
• ListResultNode.groovy
• NameComparator.groovy

Validate these classes in the IDE using the upper right button and they become automatically available in the classpath. We can now start writing our main class for the REST Service and import these classes with:

import utils.*;

The next step is writing the REST Service that will expose taxonomy categories and articles. We will not go into the details of the code, but you can take a look at the file here.

This service has two endpoints.

• One to access the list of categories and articles under the catePath category:

/categories/all/{repoName}/{catePath:.*}/

• And another to access the content of the docPath article:

/categories/articles/{repoName}/{docPath:.*}/

After adding all the files to the IDE, you should have the following setup:

After validating all the classes, you should be able to deploy the REST service. If the service is successfully deployed, you can test it using its URL.

In the case of our sample app, these URLs are:

http://localhost:8080/rest/private/categories/all/repository/acme/

or if you are using the online demo:

You should see the following JSON response:

Building the User Interface

The second step is building the UI. Let's create a "ui" folder.

In order to get an iPhone look and feel, we will use the jQtouch library. Create a "jqtouch" folder and add the JavaScript libraries.We also need a "skin" folder in which to put all the CSS and images. These files can be found here:

• jqtouch
• skin

We can now write the core of the application.

The mobileUI.js file will be the controller, which handles the clicks, forwards the data calls to the dataService.js and updates index.html.

The dataService.js will handle the database and REST calls. Every time a request is made, the device will check if the status is online or offline using:

 online = navigator.onLine;

If the device is online, it makes an Ajax request using:

$.getJSON("/rest/private/categories/all/repository/" + currentCategory + "/", callback);

The response to that request is then stored in the browser's local database.

When the device is offline, the categories or articles are retrieved thanks to an SQL query. For example:

db.transaction(                                         
      function (transaction) {                                  
            transaction.executeSql(                        
                  'SELECT * FROM articles WHERE local_path=?;', [path],
                  function (transaction, result) {
                          callback(result);
                  }, errorHandler);
});

Finally, the index.html is the view. If you take a closer look, you will notice it is made mostly ofdiv tags, as the content is injected through JavaScript. We also use a small templating trick as described in this article.

You can find all the files here:

• mobileUI.js
• dataService.js
• index.html
• template.js

If you have done everything right, you should have the following file structure:

The only remaining step is to make your application available offline. You can do so by adding a manifest file to cache the resources; that file can be found here.

You can now turn on your iPhone (or your Safari browser) and test the application with the following URL:

http://localhost:8080/rest/private/jcr/repository/dev-monit/UI/index.html

Since you are accessing private services of the platform, you will be asked to login, so simply enter "john" as the username and "gtn" as the password.

Conclusion

As more and more heterogeneous devices are used to browse the web, we are witnessing an architectural shift in application architecture. Separating the data interface from the user interface allows you to have multiple front-ends and can give third parties the opportunity to build their own app on top of your API. REST exposes the data on one side while Ajax allows the browser to rewrite the page on the fly. With HTML5 features, the browser is even more empowered and server-side native code is less and less relevant.

Using the eXo Platform 3 IDE makes it very easy to leverage this architecture. The deployment mechanism of your REST Services is greatly simplified and you can rely on all the existing eXo Services. Developers can now focus on the front end and improve the end-user experience. It is easy to imagine how fast it would be to build an iPad or Android interface for our demo app. Similarly, you could decide to expose any kind of information from the platform and decide wether you want to display it in a web page, a gadget or native app. The IDE opens-up new prospects for eXo developers that we hope they will explore.

Resources

• jQtouch
• Building an iPhone web application
• Micro-Templating