21 Nov

The simplest Alfresco client using Material Design and Ajax

How is supposed to be the simplest client over Alfresco?

I’m quite sure the answers could vary in number depending on the framework, technology and complexity. In this post is shared an example of possible client over Alfresco REST API, assuming some involved technologies like Google Material Design and Ajax.

Curious to see the source code and cannot wait anymore?

Take a look at the simplest-alfresco-rest-client project on GitHub.

Installing the client

alfrescoAs described above, the client interacts with the Alfresco REST API.  So, before moving to the explanation of the client, you should have (or setup) a working Alfresco instance, installed into your environment. Suggested but not mandatory, is the installation of the Alfresco API Explorer.

If you don’t know how to do it, please go through the Alfresco setup paragraph of the post here (you can avoid to install the Enabling CORS module).

To check if everything is working properly, open a browser and access to the URLs below.

  • http://localhost:8080/alfresco to see Alfresco repository available.
  • http://localhost:8080/api-explorer-1.1 to discover the Alfresco REST API (if installed).

Once the Alfresco instance is up and running, create a new folder called simplest-alfresco-rest-client into the <alfresco>/tomcat/webapps path. Now that the folder of the project is created, it’s time to copy the whole content of the GitHub project into it. Last but not least, restart alfresco to be sure the new project will be correctly available.

To use the client, simply open a browser and access to the URL below.

http://<alfresco_url>:<alfresco_port>/simplest-alfresco-rest-client/

 What you will get, it’s something similar to the screenshot below.

alfresco rest client

Understanding how it works

Starting to examine how it works, all the magic happens into the index.html file. The file is a combination of three different technologies:

  1. The HTML used as container of the entire web page.
  2. The Google Material Design used as responsive CSS to render the various components of the page and manage the layout.
  3. The AJAX JavaScript to manage the interaction with Alfresco, using the Alfresco REST APIs.

In this post is assumed you are confident with the HTML markup language and the basics of the web development. In the paragraphs below we are going to describe how the other two technologies are used in this particular use case.

About the Material Design CSS

google-material-designMaterial Design is a design language developed in 2014 by Google. Being a little more technical, Google Material Design is a modern CSS framework, specifically responsive and used in several mobile and web applications by Google (Gmail, YouTube, Google Drive, Google Docs, Sheets and Slides, Google Maps, Inbox).

During the development of this simple client, I found particularly useful the use of the MUI CSS (a lightweight CSS framework that follows Google’s Material Design guidelines). This site has been used as reference for all the development and is used also below to describe how the project works.

Going to the source code of the project, everything starts from a boilerplate HTML5.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="//cdn.muicss.com/mui-0.9.4/css/mui.min.css" rel="stylesheet" type="text/css" />
    <script src="//cdn.muicss.com/mui-0.9.4/js/mui.min.js"></script>
  </head>
  <body>
    <!-- content goes here -->
  </body>
</html>

Then a fluid container has been added into the content space.

<div class="mui-container-fluid">
  <!-- content goes here -->
</div>

With the customized CSS below, to have a nice background and position.

<style type="text/css">
  .mui-container-fluid {
    background: url('images/background.png') top center no-repeat;
    background-size: 100%;
  }
</script>

Now that the container is almost ready, it’s time to setup the grid. Currently, MUI uses the same grid system as Bootstrap except with the mui- class prefix prepended. The system is a mobile-first grid that scales up to 12 columns as the viewport size increases.

The grid is 1 empty column + 10 columns with content + 1 empty column. The content is presented in two rows: the first showing the form with the requested inputs and the second showing the results and messages to the user.

<div class="mui-row">
  <div class="mui-col-md-1">&nbsp;</div>
    <div class="mui-col-md-10">
      <!-- form here -->
    </div>
  <div class="mui-col-md-1">&nbsp;</div>
</div>

<div class="mui-row">
  <div class="mui-col-md-1">&nbsp;</div>
    <div class="mui-col-md-10">
      <!-- result here -->
    </div>
  <div class="mui-col-md-1">&nbsp;</div>
</div>

After the grid, for a better presentation, a panel is setup for each content (form and result).

<div class="mui-panel">
  <!-- content goes here -->
</div>

To setup the form, the source code below is used. A particular attention should be given to declare the id property for each form field and button.

<form>

  <legend>Alfresco javascript client for REST API</legend>

  <div class="mui-textfield">
    <input type="text" id="alfresco-rest-login" value="admin">
    <label>Login</label>
  </div>

  <div class="mui-textfield">
    <input type="text" id="alfresco-rest-password" value="admin">
    <label>Password</label>
  </div>

  <div class="mui-select">
    <select id="alfresco-rest-method">
      <option value="delete" selected>DELETE</option>
      <option value="get" selected>GET</option>
      <option value="post" >POST</option>
      <option value="put" >PUT</option>
    </select>
    <label>RESTFul method</label>
  </div>

  <div class="mui-textfield">
    <input type="text" id="alfresco-rest-copy-body" value="">
    <label>RESTFul copyBody</label>
  </div>

  <div class="mui-textfield">
    <input type="text" id="alfresco-rest-url" value="...">
    <label>RESTFul url</label>
  </div>

  <button id="submit-button" type="submit" class="mui-btn mui-btn--primary">Go</button>
  <button id="reset-button" type="submit" class="mui-btn mui-btn--primary">Reset</button>
  <button id="api-explorer-button" type="submit" class="mui-btn mui-btn--primary">API Explorer</button>

</form>

The setup of the results panel is straightforward using a pre tag with an id property, as described below.

<p>
  <pre id="alfresco-result">
    Press 'Go' to view the result here.
  </pre>
</p>

To view the complete source code of the HTML page, please look here.

About the AJAX call

ajax_logoNow that the HTML page is defined, it’ time to setup the JavaScript source code related. As mentioned above, the AJAX techniques are used to send data to and retrieve from an Alfresco server asynchronously (in the background) without interfering with the display and behavior of the existing page.

Going to the source code of the project, everything happens into the script tag described below.

<script type="text/javascript">
  $(function() {
    // Events declared here.
  }
</script>

For each button defined into the HTML source code, a related event is declared to manage the actions. Below the source code defining the events.

// Submission event.
$('#submit-button').click(function(e) {

  // Avoid to trigger the default action of the event.
  e.preventDefault();

  // Actions declared here...

}

// Resetting event.
$('#reset-button').click(function(e) {

  // Avoid to trigger the default action of the event.
  e.preventDefault();

  // Actions declared here...

}

// API-Explorer link.
$('#api-explorer-button').click(function(e) {

  // Avoid to trigger the default action of the event.
  e.preventDefault();

  // Actions declared here...

}

The submission event develops the interaction with the Alfresco REST API and shows the result into the web page. Below the source code defining the event.

// Retrieve values from the HTML inputs into local variables.
var alfrescoLogin = $("#alfresco-rest-login").val();
var alfrescoPassword = $("#alfresco-rest-password").val();
var alfrescoRestMethod = $("#alfresco-rest-method").val();
var alfrescoRestCopyBody = $("#alfresco-rest-copy-body").val();
var alfrescoRestUrl = $("#alfresco-rest-url").val();

// Various checks...

// AJAX call and management of the result.
$.ajax({
  username: alfrescoLogin,
  password: alfrescoPassword,
  type: alfrescoRestMethod,
  data: alfrescoRestCopyBody,
  url: alfrescoRestUrl,
  success: function(result,status,xhr) {

    // Shows the result into the result panel.
    $('#alfresco-result').html("<p>Status: " + status +"</p>");
    $('#alfresco-result').append(JSON.stringify(result, null, "\t"));

  },
  error: function(xhr,status,error) {

    // Shows the result into the result panel.
    $('#alfresco-result').html("ERROR: " + error);

 }
});

The resetting event cleans the result panel of the web page, initializing it to the first sentence used during the default presentation. Below the source code defining the event.

$('#alfresco-result').html("Press 'Go' to view the result here.");

The API-Explorer event opens a browser window with the Alfresco API Explorer, if available. Below the source code defining the event.

window.open("/api-explorer-1.1","explorer");

To view the complete source code of the HTML page, please look here.

How the result looks like

Now that the page is developed with HTML5, CSS and Javascript, it’s time to use it by filling the fields in the form and pressing the Go button. Once the button is pressed and the parameters are good to interact with Alfresco REST APIs, the result will be showed as described below.

Alfresc rest api result

Conclusion

In this post is described an example of possible client over Alfresco REST API, assuming some involved technologies like Google Material Design and Ajax. The description is based on the simplest-alfresco-rest-client project on GitHub. The goal of the post is to share the details of the implementation of a very simple client for the Alfresco services available using the new and powered REST API.

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload CAPTCHA.