Coral.Collection provides a standardized way to manipulate items in a component.

Let's assume we have an object called component that implements the Coral.Collection. This will enable us to add and remove items with ease.

add(item, insertBefore)

Adding a new item can be done using the add() method. It also accepts the insertBefore parameter to be able to specify where the item is added. If this value is null, then it is added at the end of the collection. Adding an item triggers the coral-collection:add event.

var addedItem = component.items.add(item);

The item can also be an Object whose properties match the setter of the items that the collection typically manipulates. This will depend highly in the component that is exposing the Coral.Collection.

var addedItem = component.items.add({
  "label":"Hello"
});

remove(item)

We can also remove an item by using the remove() method. It only accepts HTMLElement. Removing an item triggers an coral-collection:remove event.

var removeditem = component.items.remove(item);

getAll()

To obtain all the items inside a Coral.Collection getAll() should be used. This method should always return an Array.<HTMLElement>.

var items = component.items.getAll();

clear()

Removing all elements can be done using clear(). This will trigger a coral-collection:remove event for every item that is removed.

var items = component.items.clear();

Coral.Collection API

The Collection API as used as an interface to manipulate item collections within the components.

Instance Properties

instance.length {Number}

Number of items inside the Collection.
Default Value:
  • 0

Methods

instance.add

Adds an item to the Collection. The item can be either a HTMLElement or an Object with the item properties. If the index is not provided the element appended to the end. If options.onItemAdded was provided, it will be called after the element is added from the DOM.
Parameters:
Name Type Optional Description
item HTMLElement|Object No
The item to add to the Collection.
insertBefore Number Yes
Existing item used as a reference to insert the new item before. If the value is null, then the new item will be added at the end.
Fires:
Returns:
the item added. {HTMLElement}

instance.clear

Removes all the items from the Collection.
Returns:
an Array with all the removed items. {Array.<HTMLElement>}

instance.first

Returns the first item of the collection.
Returns:
the first item of the collection. {HTMLElement}

instance.getAll

Returns an array with all the items inside the Collection. Each element is of type HTMLElement.
Returns:
an Array with all the items inside the collection. {Array.<HTMLElement>}

instance.last

Returns the last item of the collection.
Returns:
the last item of the collection. {HTMLElement}

instance.remove

Removes the given item from the Collection. If options.onItemRemoved was provided, it will be called after the element is removed from the DOM.
Parameters:
Name Type Description
item HTMLElement The item to add to the Collection.
Fires:
Returns:
the item removed. {HTMLElement}

Events

coral-collection:add

Triggered when an item is added to the Collection.
Callback Parameters:
Name Type Description
event Object

Event object.

Name Type Description
event.detail.item HTMLElement The item that was added.

coral-collection:remove

Triggered when an item is removed from a Collection.
Callback Parameters:
Name Type Description
event Object

Event object.

Name Type Description
event.detail.item HTMLElement The item that was removed.