Aikau Mini Examples - CRUD Service (get)

[ddraper]

Introduction

This is one post in a series of short examples of things that can be done using the Aikau framework. The series is not intended to provide complete documentation but simply to show how to solve frequently encountered problems, implement repeating UI patterns, showcase how to use existing widgets or how to create new ones.

Real World Use Case

At some stage you're going to need to work with some data and Aikau is specially created to work with Alfresco repositories. The widgets are de-coupled from data by using client-side services as a go-between for getting and setting data on over the Alfresco Repository REST API. Most web applications are ultimately just lists and forms and Share is no different - one area that hasn't had a lot of work recently is the Data Lists in Sites. This area has lots of examples of getting and setting data in a number of different ways. This post and following posts will show how we can use Aikau to work with Data List data.

Example

In this example we're going to do nothing more complicated than just retrieving the list of Data Lists from the Repository. The purpose is just to introduce the 'alfresco/services/CrudService' module as well as basic list building.

Prerequisites

We could have started by actually using the CrudService to create some data lists, but it makes more sense to actually create some data to start of with so that you can compare the existing implementation with the Aikau version, so please do the following:

1. Log into Alfresco Share



2. Create a site



3. Customize the site and add Data Lists to it



4. Create some data lists (doesn't matter what they are).

Pick an API, any API...

Aikau provides a number of dedicated services for working with data (e.g. 'alfresco/services/DocumentService', 'alfresco/services/SearchService', etc.) which typically perform some additional work or error checking to the basic data manipulation. The 'alfresco/services/CrudService' is different in that it provides the raw capability to work with a REST API. Currently there is no dedicated service for working with Data Lists so we're going to use the CrudService for accessing the Data List APIs.

Service Dependencies

First we need to make sure that the CrudService is available on the page. This is done by including in in the list of services in the JSON model for the page.

model.jsonModel = {

  services: [

    'alfresco/services/CrudService'

  ]

};

The majority of services don't require any configuration so can be added to the list as a string. However, it's also possible to add services into the array as objects with name/config attributes as is done with widgets.

Define a List

The most simple form of list in Aikau is the 'alfresco/lists/AlfList' widget that provides basic list capabilities. This is extended by the 'alfresco/lists/AlfHashList' (that allows requests to be manipulated by the URL hash fragment) and the 'alfresco/lists/AlfSortablePaginatedList' (that provides support for sorting and pagination) which is in turn extended by specialist lists such as the 'alfresco/documentlibrary/AlfDocumentList' and 'alfresco/documentlibrary/AlfSearchList', etc. For this example we just need simple capabilities so the basic 'AlfList' widget is sufficient.

var list = {

  name: 'alfresco/lists/AlfList',

  config: {

    loadDataPublishTopic: 'ALF_CRUD_GET_ALL',

    loadDataPublishPayload: {

      url: 'slingshot/datalists/lists/site/datalistexample/dataLists'

    },

    itemsProperty: 'datalists'

  }

};

In this example we are essentially defining the data that we want to work with. The 'loadDataPublishTopic' defines the topic to publish to request data, and the 'loadDataPublishPayload' defines the payload to send when requesting data. We are using a topic defined by the CrudService and which is designed to work with the Alfresco Repository REST API so we do not need to include the full address, just the WebScript declared URL fragment.



It would be nice if all the Alfresco REST APIs used a consistent attribute for the arrays of data that they return but since this is not the case, we can instruct the AlfList to use a specific property in the response body to get the array from using the 'itemsProperty' configuration attribute (note: this will also accept dot-notation values).

Define a View

An 'alfresco/lists/AlfList' widget (and all it's descendants) can render multiple views of data. These are set as the 'widgets' config attribute and in order to actually display any data an AlfList needs to have a least one view configured.



It's possible to build almost any view and you can either re-use the existing view and data rendering widgets or build your own. In this case we're just going to build our view of data as a list of rows, each containing a single cell with a single data renderer.

var views = [

  {

    name: 'alfresco/documentlibrary/views/AlfDocumentListView',

      config: {

      widgets: [

        {

          id: 'VIEW_ROW',

          name: 'alfresco/documentlibrary/views/layouts/Row',

          config: {

            widgets: [

              {

                name: 'alfresco/documentlibrary/views/layouts/Cell',

                config: {

                widgets: [

                  {

                    name: 'alfresco/renderers/Property',

                    config: {

                      propertyToRender: 'title'

                    }

                  }

                ]

              }

            }

          ]

        }

      }

    ]

  }

}];

View definitions can get quite long and if you define a view that you want to re-use then it makes sense to extend 'alfresco/documentlibrary/views/AlfDocumentListView' and declare the widget model in your own subclass (see 'alfresco/documentlibrary/views/AlfSimpleView' and 'alfresco/documentlibrary/views/AlfDetailedView' as examples of this).



The reason that a lot of the list and view modules are defined in the 'alfresco/documentlibrary/' package is purely historical since most of the list and view code has been abstracted from Document Library specific use cases.



Finally we just need to pull all the individual bits together:

list.config.widgets = views;

model.jsonModel.widgets = [list]

Example In Action

This is defined in a JavaScript controller for a WebScript mapped to the /crudService URL. When deployed to a Share (or any Surf based Aikau application) this can be accessed by the URL: http://localhost:8081/share/page/dp/ws/crudService



This screenshot shows the result:







Obviously this isn't especially exiting or indeed useful... the purpose is just to demonstrate how to access data. You can check out the page models for the document and search views for more complex examples of what is possible.



Download the complete example here.