Aikau Mini Examples - Data List (part 1)

[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

There are already pages in Share for handling Data Lists, but they haven't been updated for many releases.  They are therefore a good candidate to demonstrate how it's possible to re-use Aikau widgets to rebuild (and enhance) existing Share features. It may also be necessary to extend the existing Aikau widgets to achieve specific use cases.

Example

This post picks up where the last one left off. Since I'd started using Data Lists as a case study for demonstrating the 'alfresco/services/CrudService' I realised that I may as well continue on the path of re-creating the page using Aikau - especially since it demonstrates more techniques that might be required by Alfresco developers, partners and community members.

Extending AlfList

We've already recreated the part of the Data List page sidebar and we now want to create the main section of the page that will show the currently selected Data List. It would be nice if we could just use another 'alfresco/lists/AlfList' widget for this main section but the problem is that each Data List uses different properties for their items. However, it is possible to re-use the same list but switch views for each Data List type.



Therefore we're going to create a custom widget that extends 'alfresco/lists/AlfList' and to do so we should add in our 'blog' package for our custom widget (see this previous post for details).



The main requirements of our custom list is to handle Data List selection and switch views to match the appropriate Data List type. Our 'blog/DataList' widget is declared as follows:

define(['dojo/_base/declare',

        'alfresco/lists/AlfList',

        'dojo/_base/lang'],

        function(declare, AlfList, lang) {



  return declare([AlfList], {

Now we need to override and add functions to satisfy our requirements:

postMixInProperties: function blog_DataList__postMixInProperties() {

  this.inherited(arguments);

  this.alfSubscribe('BLOG_LOAD_DATA_LIST', lang.hitch(this, this.loadDataList))

},

Note that we call 'this.inherited(arguments)' to execute the extended modules function of the same name. This can be omitted if you want to override rather than extend the function. We then call the 'alfSubscribe' function and bind the 'BLOG_LOAD_DATA_LIST' topic to the 'loadDataList' function using Dojo's lang.hitch utility function (so that when 'BLOG_LOAD_DATA_LIST' is published on, the 'loadDataList' function will be called).

loadDataList: function blog_DataList__loadDataList(payload) {

  this.dataListToLoad = payload;

  this.onViewSelected({

    value: payload.itemType

  });

  this.loadData();

},

The 'loadDataList' function assigns the published payload to the 'dataListToLoad' instance variable (so that it can be referred to later) and switches to the appropriate view by calling the 'onViewSelected' function inherited from the 'alfresco/lists/AlfList' widget. The the 'loadData' function (also inherited) is called to request the data.

loadData: function alfresco_lists_AlfList__loadData() {

  if (this.dataListToLoad != null)

  {

    this.inherited(arguments);

  }

},

This function needs to be extended to prevent attempts to load data when no Data List has been set. Note that we are able to conditionally decide whether or not call the inherited function.

updateLoadDataPayload: function blog_DataList__updateLoadDataPayload(payload) {

  if (this.dataListToLoad != null)

  {

    payload.url = 'slingshot/datalists/data/node/' + this.dataListToLoad.nodeRef.replace('://', '/');

  }

}

Finally we override the 'updateLoadDataPayload' extension point function to set the URL to load. This is a good example of how Aikau intentionally provides functions purely for developers to extend so that they don't need to copy and paste existing code.

Pub/Sub Scoping

Since we're going to be having two instances of the AlfList on the page we need to ensure that their publication/subscription (pub/sub) communications are scoped to prevent cross-communication. Therefore when we define our 'blog/DataList' in the JSON model we will set a specific 'pubSubScope'.

var pubSubScope = 'DATA_LIST_SCOPE';



var dataList = {

  name: 'blog/DataList',

  config: {

    pubSubScope: pubSubScope,

    loadDataPublishTopic: 'ALF_CRUD_CREATE',

    itemsProperty: 'items',

    widgets: buildViews()

  }

};

Configuring Views

Note that we're also calling a 'buildViews' function that you can review in the full example (see download link at end of post) but I won't list here. In summary we need to build a view for each Data List type that we know about. Each view is given an ID of the Data List type (e.g. 'dl:eventAgenda'). Views were described in this earlier post so I won't describe them here, other than to say that we are adding an 'alfresco/renderers/Property' for each property in the Data List type.



One addition to the view construction previously described is that we are also setting the 'widgetsForHeader' attribute for each widget (to create column headers) and setting the 'additionalCssClasses' attribute on each view to make it more tabular in app%MCEPASTEBIN%earance.

Updating the Link

Lastly we need to update our previously created list to make our 'alfresco/renderers/InlineEdityProperty' an 'alfresco/renderers/InlineEdityPropertyLink' so that when it is clicked it publishes the request to load the Data List it represents.

dataListTitle.name = 'alfresco/renderers/InlineEditPropertyLink';

dataListTitle.config.linkPublishTopic = pubSubScope + 'BLOG_LOAD_DATA_LIST';

dataListTitle.config.linkPublishPayloadType = 'CURRENT_ITEM';

Note that we're re-using the 'pubSubScope' variable so that we're publishing into the scope that our 'blog/DataList' is using.

Example in action

This is defined in a JavaScript controller for a WebScript mapped to the /datalist 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/datalist



These screenshots shows the page in action:







 







 







Download the complete example here.

Next Steps

In the next post we'll make further updates to improve the layout and add support for creating Data List items.