The Uize.Widget.ListEditor class uses a number of child widgets and implied nodes to build a UI that lets the user edit the list.

The input child widget, which is an instance of the Uize.Widget.TextInput class, lets the user enter text for a new item to be added to the list array. The add child widget, which is an instance of the Uize.Widget.Button class, lets the user add the currently entered text as a new item in the list array. The list Implied Node, which is a multiple select select tag (ie. where the multiple attribute is set to the value 'multiple'), displays the current list and lets the user select one or more items in the list to be removed. The remove child widget, which is an instance of the Uize.Widget.Button class, lets the user remove the items currently selected in the list Implied Node from the list array.

2.1.1. More on Adding Items

2.1.2. More on Removing Items

2.1.3. Editing Items

The list that is edited by the user can be accessed programmatically through the list set-get property, which is an array of string values.

The list can also be pre-seeded or updated programmatically by setting the value of this property.

2.2.1. Value Interface

myListEditor.get ('list');
myListEditor.get ('value');
myListEditor.valueOf ();

The sort set-get property provides a way to maintain the list array in a sorted state.

The list can be sorted ASCIIbetically, in ascending or descending order, or it can be sorted with your own custom sort function, or it can be unsorted with new items added to the beginning or the end of the list. When sorting is enabled, the list is kept sorted as items are added by the user, or as its items are otherwise changed - even when items are changed programmatically by setting the value of the list set-get property.

The Uize.Widget.ListEditor class manages the state of its button child widgets, so they are only enabled when appropriate.

2.4.1. Disabled Add Button

2.4.2. Disabled Remove Button

An instance of the Uize.Widget.Button class, that lets the user add the current text entered in the input child widget as a new item in the list array.

When the value of the input child widget's isValid set-get property is set to false, then the add button will be disabled. This typically occurs when the input child widget's value is '' (an empty string), but could also occur if its value is non-empty but not valid according to a validator function specified by its validator set-get property.

When the add button is enabled and is clicked by the user, any text entered in the input child widget will first be processed by the itemConformer function (if specified) and will then be added to the list array. Where the new item appears in the list will depend on the value of the sort set-get property.

NOTES

An instance of the Uize.Widget.TextInput class, that lets the user enter text for a new item to be added to the list array.

Text entered in the input child widget can be added to the list array by either pressing the enter key when the input child widget is focused, or by clicking on the add button. Upon adding the input widget's text to the list array, the value of the input widget is cleared (ie. set to an empty string). Pressing the escape key when the input child widget is focused will clear the value of the input widget without adding the item to the list array.

NOTES

An instance of the Uize.Widget.Button class, that lets the user remove the items currently selected in the list Implied Node from the list array.

When no options of the list Implied Node are selected, then the remove button will be disabled. This may happen when there are no items in the list array, when the user has just removed the previously selected items, or if the user uses ctrl-click to deselect all selected items.

NOTES

A multiple select select tag (ie. where the multiple attribute is set to the value 'multiple'), that is used to display the current items in the list array, and that allows the user to select one or more items to remove.

When the list Implied Node is focused and one or more options of the select tag are selected, then pressing the delete key will result in the selected items being removed from the list.

NOTES

An optional function, that should be used to conform new items that are added to the list by the user.

EXAMPLE

page.addChild (
  'domainListEditor',
  Uize.Widget.ListEditor,
  {
    itemConformer:function (value) {
      return value.replace (/(^\s*(https?\:\/\/)?|(\/)+\s*$)/gi,'');
    }
  }
);

In the above example, an instance of the Uize.Widget.ListEditor class is being used to set up a domain list editor. This could be for something like a domain whitelist, or a domain based, blacklist style content filter. In this case, we only care about the host name and path, but don't care about the protocol. So, by specifying a function for the itemConformer property, we can have the "http" or "https" stripped off the beginning of new items before they are added to the list.

NOTES

An array of strings, representing the items in the list.

Setting the value of this property programmatically will result in the instance updating its UI to reflect the new items in the list. Whenever an item is added to the list by the user, or when one or more items are removed by the user, the value of this property will be changed. Therefore, registering a handler for the Changed.list event will catch cases where the list is modified by the user as well as programmatically by code setting the value of this property.

5.2.1. New Items Become Selected

myListEditor.set ({list:myListEditor.get ('list').concat ('new item 1','new item 2')});

5.2.2. Automatically Sorted

var myListEditor = page.addChild ('myListEditor',Uize.Widget.ListEditor,{sort:'a-z'});
myListEditor.set ({list:['c','b','a']});

5.2.3. Ignored Sets

var myListEditor = page.addChild ('myListEditor',Uize.Widget.ListEditor,{sort:'a-z'});
myListEditor.wire ('Changed.list',function () {alert ('LIST CHANGED')});
myListEditor.set ({list:['a','b','c']});  // WE GET AN ALERT THIS TIME
myListEditor.set ({list:['a','b','c']});  // NO ALERT!
myListEditor.set ({list:['c','b','a']});  // STILL NO ALERT!

NOTES

A string, specifying one of the supported list sort modes, or a function reference for a custom list sorter function.

VALUES

Whenever the value of the sort property is changed, the list array is resorted according to the new sort mode. Whenever the value of the list set-get property is set, it is first conformed by sorting it according to the current sort mode.

NOTES

An alias to the list set-get property, so that this class effectively implements the Value Interface.

NOTES