Aikau - Simple Picker Updates

[ddraper]

Introduction

In my last blog post I described how I had updated the dynamic visibility configuration options in order to support a new picker widget that I was working on. In this post I'm going to describe how to use this new picker.

The Simple Picker Widget

This new picker widget is defined in the “alfresco/forms/controls/SimplePicker” module and is intended to be used in forms where the user might need to select one or more items from a list. This widget re-uses much of the same code implemented for the more complex form pickers (e.g. for selecting documents, folders or properties) but distils the underlying JSON model into a small configuration set that is intended to make it as simple as possible get a picker onto your page.

The this list of available items is unsurprisingly a re-use of the existing 'alfresco/lists/AlfList' widget and the items can be populated either by directly configuring a “currentData” attribute or by configuring a “loadDataPublishTopic” (with an optional “loadDataPublishPayload”).

Let's start with a really simple configuration and build up towards a more realistic use case. All these examples are included in this JAR file for you to try out for yourself.

Basic Hard-coded Data

Let's start with some a really simple picker containing some hard-coded data that will be set using the 'currentData' attribute:

...
{
  name: 'alfresco/forms/controls/SimplePicker',
  config: {
    currentData: {
      items: [
        {
          name: 'One'
        },
        {
          name: 'Two'
        },
        {
          name: 'Three'
        }
      ]
    }
  }
}
...
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

This configuration will result in the following picker:

 

Just by providing some data we're able to build a picker, however it is worth nothing that our data has been tailored to fit the SimplePicker defaults (using 'items' to identify the list and 'name' to identify both the unique item key and displayable property) but I'll show how these can be configured later.

Simple Picker is a Form Control

Let's not forget that the Simple Picker is a form control and as such we can use any of the standard form configuration attributes... so let's update our picker to include a label, description and the request parameter name that would be posted on form submission.

We're also going to make the selected items re-orderable by setting the 'reorderable' attribute to true:

...
{
  name: 'alfresco/forms/controls/SimplePicker',
  config: {
    label: 'Pick Some items',
    description: 'This is a simple picker with some hard-coded data',
    name: 'hardcoded',
    reorderable: true,
    currentData: {
      items: [
        {
          name: 'One'
        },
        {
          name: 'Two'
        },
        {
          name: 'Three'
        }
      ]
    }
  }
}
...

‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

This results in the following picker (with all the items selected to show the re-ordering controls):

 

Nothing to Display?

You have control over all of the messages that are displayed in the picker. One of which is the message shown when there is no data. This is done by setting the 'noItemsMessage' attribute.

PLEASE NOTE: In my examples I'm using hard-coded strings, but these would typically be replaced with localization keys for multi-language support in a real-world example.

...
{
  name: 'alfresco/forms/controls/SimplePicker',
  config: {
    label: 'No Items Picker',
    description: 'This examples shows a custom message to show when no items are available for picking.',
    name: 'nothingAvailable',
    noItemsMessage: 'Nothing to pick!',
    currentData: {
      items: []
    }
  }
},
...‍‍‍‍‍‍‍‍‍‍‍‍‍‍

This will result in the following picker:

 

One at a Time Please!

If we want to configure our picker to only allow a single item to be selected then we can set the 'singleItemMode' to be true. This also has the effect of overriding the 'reorderable' attribute (because what's the point in having re-ordering controls when you can only ever have one item selected).

The effect of this is that if you have an item already selected, then selecting another will remove the previously selected item.

Accessing Server Side Data

For a slightly more real-world example let's configure our Simple Picker to allow us to select from the User Groups that are configured in the Alfresco Repository. This means that we replace the hard-coded 'currentData' object with a 'loadDataPublishTopic'. We're going to be using the trusty 'alfresco/services/CrudService' for this so you'll need to remember to include it in the list of services.

As well as configuring the data source we also need to configure how we handle the resulting data:

...
{
  name: 'alfresco/forms/controls/SimplePicker',
  config: {
    label: 'Pick User Groups',
    description: 'This is a simple picker publishes a request to get data to display',
    name: 'groups',
    loadDataPublishTopic: 'ALF_CRUD_GET_ALL',
    loadDataPublishPayload: {
      url: 'api/groups?zone=APP.DEFAULT'
    },
    itemsProperty: 'data',
    itemKey: 'shortName',
    propertyToRender: 'displayName',
    availableItemsLabel: 'Available Groups',
    pickedItemsLabel: 'Currently Selected Groups'
  }
}
...‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Here is a break-down of the attributes used:

• 'itemsProperty' identifies the attribute within the JSON response from the server that contains the list of items to display. This could be a dot-notation address in the JSON object if necessary.

• 'itemKey' should be set to an attribute in each item that is a unique identifier. This is important to get right because it could result in multiple items getting picked if there are duplicate keys

• 'propertyToRender' is the attribute in each item to use as the display value. Note that we use 'shortName' as the 'itemKey' (because it is unique) but 'displayName' as the 'propertyToRender' because it is the user-friendly group name

For added fun we're also adding labels to the available and picked item columns using the 'availableItemsLabel' and 'pickedItemsLabel' attribute.

The resulting picker looks like this:

 

Still Not Enough?

Finally, if you're still not happy with how the available items and picked items are displayed then you can set 'widgetsForAvailableItemsView' and 'widgetsForPickedItemsView' which allow you to declare JSON models of views for both columns.

Although configuring these attributes will override some of the previously mentioned configuration options it does give you complete flexibility for rendering the data as you see fit. Once again this is demonstrating the key-strength of Aikau which is re-usabiliy. The views you configure for items are defined in exactly the same way as all views of data - this means that you can easily re-use previously defined views or reference your own custom widgets.

Summary

Hopefully this gives another indication of where we're trying to take Aikau. Maximising code re-use, attempting to distil complex widget models into simple to configure widgets but retaining the ability to fully customize them as required.