Aikau - Simple Picker Updates

cancel
Showing results for 
Search instead for 
Did you mean: 

Aikau - Simple Picker Updates

Intermediate II
2 9 2,429

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:

This is a simple picker constructed with hard-coded data. 

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):

The simple picker with label, description and re-ordering enabled 

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:

A Simple Picker with a custom message when no items are available for selection 

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:

SImple Picker configured to access group data from the Alfresco Repository 

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.

 

9 Comments
Active Member
Hello,



SimplePicker doesn't work correctly: it is impossible to choose the last item!
Intermediate II
@Andrej... what version of Aikau are you using and why have you raised this as a comment on a blog post rather than as an issue in either the Aikau GitHub project or in the Alfresco JIRA?
Active Member
Thank you for the speedy Answer. I try it with Aikau Sandpit. I hope Aikau Sandpit uses the latest version.
Occasional Visitor

Hi @Dave,

I am trying to update the list of available items based on a user search result, but I can't figure out how to do it.

The SimplePicker works for hardcoded items and it also works when I use the loadDataPublishTopic just as you described it.  But both of these ways work only when the Picker is initialized.

Can you please tell me if there is a way to update the available items (on the left side of the picker) ?

Regards

Pajtim

Edit:  I'm on Aikau 1.0.88

Intermediate II

The main reason that this doesn't work is because the model for the available items (defined by the "widgetsForAvailableItemsView" attribute) has an AlfListView rather than an AlfList as it's root object. An AlfList will handle state changes to load new data and pass that data onto an AlfListView for rendering. However, it is possible to configure the AlfListView to subscribe to data load topics so that it can be dynamically updated.

You can configure the "subscribeToDocRequests" attribute on the AlfListView to be true and configure the "documentSubscriptionTopic" attribute to be the topic that the AlfListView should subscribe to receive new data.  Depending upon the published payload you may need to also configure the "itemsProperty" attribute to identify the location of the data array.

So this does mean that you're going to need to override the "widgetsForAvailableItemsView" for the simple picker.

Hopefully this makes sense, let me know if not !

Occasional Visitor

Thank you for your helpful response.

Additionally to your suggestions I had to set

  • currentData: {}
  • the pubSubScope of the AlfListView​ (widgetsForAvailableItemsView)
  • the pubSubScope of the PickedItems  (widgetsForPickedItems) to make sure that the selected items were added to the picked items
Occasional Visitor

Can you please paste the code changes here you added for to update the list of available items based on a user search result. Thanks in advance.

Occasional Visitor

Hi Dave/Pajitim,

Can you please paste/provide the code changes here you suggested above to update the list of available items based on a user search result. Thanks in advance.

Regards,

Naresh

Established Member II

Hi,

Is is possible to specify loadDataPublishPaylod url to somewhere OUTSIDE the alfresco? (i.e http://www.example.com/query?search=sample) 

Regards,

Mike