EditableList Widget

A replacement for a <ol> element where the items can be complex elements in their own right. Used by the core Switch and Change nodes.

• Options
• Methods

Options

addButton

Type: Boolean|String

Determines whether a button is shown below the list that, when clicked, will add a new entry to the list.

If not specified, or set to true (boolean) a button is shown with the text ‘Add’.

If set to false (boolean), the button is not shown.

If set to a non-blank string, a button is shown using its value as the text of the button.

$("ol.list").editableList({
    addButton: "pets"
});

addItem( row, index, data )

Type: Function

A callback function that gets called when a new item is being added to the list.

• row - the jQuery DOM element to which any row content should be added
• index - the index of the row
• data - the data object for the row

If it was triggered by clicking the ‘add button’, data will be {}. Otherwise it will be the data passed to the call to the addItem method.

$("ol.list").editableList({
    addItem: function(row, index, data) {
        $(row).html("Item "+index);
    }
});

buttons( array )

Type: Array

An array of button objects, that need to be added at the bottom of the editableList. Each button object can have the following properties:

• label - the (optional) button label
• icon - the (optional) button icon
• title - the (optional) button tooltip text
• click - the callback function that will be executed when the button is clicked

Note that the ‘add button’ is added implicit to this array, when the addButton is activated.

$("ol.list").editableList({
    addItem: function(row, index, data) {
        $(row).html("Item "+index);
    }
    buttons: [{
        label: "with icon",
        icon: "fa fa-star",
        title: "my custom button",
        click: function(evt) {
            alert("button clicked");
        }
   }]
});

connectWith

Type: CSS Selector

If the list is sortable, this option allows items to be dragged from this list to any other jQuery sortable list, such as another editableList.

$("ol.list").editableList({
    connectWith: ".my-other-list"
});

header

Type: DOM/JQuery object

Inserts the DOM/JQuery object as a header for the list.

$("ol.list").editableList({
    header: $("<div>").append($.parseHTML("<div style='width:40%; display: inline-grid'>Name</div><div style='display: inline-grid'>Type</div>")),
});

height

Type: String|Number

Sets the height of the list including, if enabled, its add button. Setting height to ‘auto’ removes the vertical scrollbar and displays the list at the full height needed to contain the contents.

$("ol.list").editableList({
    height: 300
});

filter( data )

Type: Function

A callback function that gets called to filter what items are visible in the list.

• data - the data object for the row

The function should return true/false (boolean) to indicate whether the item should be visible.

$("ol.list").editableList({
    filter: function(data) {
        return data.index%2 === 0
    }
});

resize()

Type: Function

A function that gets called when the size of the list changes.

$("ol.list").editableList({
    resize: function() {
        console.log("I have changed in size")
    }
});

resizeItem( row, index )

Type: Function

A function that gets called against each item in the list when the size of the list changes.

• row - the jQuery DOM element for the row
• index - the index of the row

The original data for the item is stored under a property called data.

This callback is invoked after the main resize callback is called.

$("ol.list").editableList({
    resizeItem: function(row,index) {
        var originalData = $(row).data('data');
        console.log("Resize the row for item:", originalData)
    }
});

scrollOnAdd

Type: Boolean

Determines whether the list should automatically scroll to the bottom whenever a new item is added.

If not specified, or set to true (boolean) the list will scroll to show newly added items.

If set to false (boolean), the list will not scroll.

$("ol.list").editableList({
    scrollOnAdd: false
});

sort( itemDataA, itemDataB )

Type: Function

A callback function that gets called to compare two items in the list to determine their order.

• itemDataA - a data item
• itemDataB - a data item

If the function returns a value less than 0, itemDataA comes before itemDataB.

If the function returns 0, the items are left unchanged.

If the function returns a value greater than 0, itemDataA comes after itemDataB.

$("ol.list").editableList({
    sort: function(dataA, dataB) {
        return dataA.index-dataB.index;
    }
});

sortable

Type: Boolean|CSS Selector

Determines whether the list items can be dragged to sort them.

If set to true (boolean), a default drag handle is displayed alongside the item.

If set to a CSS Selector, that is used to identify the element that should be used as the drag handle within the item’s content element.

$("ol.list").editableList({
    sortable: true
});

sortItems( items )

Type: Function

A function that is called after an item in the list is moved.

• items - an Array of the jQuery DOM elements for each row, in order.

Each row element stores the original data for the item under the property called data.

$("ol.list").editableList({
    sortItems: function(items) {
        console.log("The items have changed order")
    }
});

removable

Type: Boolean

If set to true, each row is displayed with a delete button on the right-hand side. Clicking the button will remove the row from the list and trigger the removeItem callback, if set.

$("ol.list").editableList({
    removable: true
});

removeItem( data )

Type: Function

A function that is called when an item is removed from the list.

• data - the original data item for the item

The remove can be triggered by either clicking an item’s remove button, or calling the remoteItem method.

$("ol.list").editableList({
    removeItem: function(data) {
        console.log("An item has been removed")
    }
});

Methods

addItem( itemData )

Adds an item to the end of the list. itemData is an object that will be associated with the item in the list.

$("ol.list").editableList('addItem',{fruit:"banana"});

addItems( itemData )

Adds items contained in an array to the end of the list. itemData is an array of objects that will be associated with the item in the list.

$("ol.list").editableList('addItems',[{fruit:"banana"},{fruit:"apple"},{fruit:"pear"}]);

removeItem( itemData )

Removes an item from the list. itemData is the object that identifies the item to be removed.

$("ol.list").editableList('removeItem',{fruit:"banana"});

width( width )

Sets the width of the editableList. This must be used in place of the standard jQuery.width() function as it ensures the component resizes properly.

$("ol.input").editableList('width', '200px');

height( height )

Sets the height of the editableList. This must be used in place of the standard jQuery.height() function as it ensures the component resizes properly.

$("ol.input").editableList('height', '200px');

items()

Type: Array

Gets an Array of all list items. Each item is the jQuery DOM element for the item.

Each element stores the original data for the item under the property called data.

var items = $("ol.list").editableList('items');

empty()

Clears the list of all items. This does not trigger any callbacks.

$("ol.list").editableList('empty');

filter( filter )

Type: Number

Filters the list to show/hide items based on the active filter function and returns the number of visible items.

See filter for details of the filter function.

If filter is not provided, the list is filtered using the currently active filter function.

If filter is null, the filter is removed.

var filteredCount = $("ol.list").editableList('filter',function(data) {
    return data.index%2 === 0
});

show( item )

Since 0.20.0

Scrolls the list to ensure the specific item is in view.

$("ol.list").editableList('show', item);

sort( sort )

Sorts the list using the active sort function.

A callback function that gets called to compare two items in the list to determine their order.

• itemDataA - a data item
• itemDataB - a data item

See sort for details of the sort function.

If sort is not provided, the list is sorted using the current active sort function.

$("ol.list").editableList('sort', function(dataA, dataB) {
    return dataA.index-dataB.index;
});

length()

Type: Number

Gets the number of list items.

var length = $("ol.list").editableList('length');

cancel()

Since 3.1.0

Cancels an item sort operation on the list.

$("ol.list").editableList('cancel');