Coral.Collection

Current Version: 1.5.1
Github: @coralui/coralui-component-collection

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

Usage

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 HTMLElement 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}

Type Definitions

instance.filter

Signature of the function called to determine if an element should be included in the collection. If the function returns true for the given element it will be part of the collection, otherwise it will be excluded.
Parameters:
Name Type Description
element HTMLElement The item to check whether it should be part of the collection.
Returns:
true if should be part of the collection, otherwise false. {Boolean}

instance.onCollectionChange

Signature of the function called when there is a change in the collection. The items that where added and removed will be provided.
Parameters:
Name Type Description
addedNodes Array.<HTMLElement> An array that contains the items that were added to the collection.
removedNodes Array.<HTMLElement> An array that contains the items that were removed from the collection.

instance.onItemAdded

Signature of the function called when ever an item is added to the collection.
Parameters:
Name Type Description
item HTMLElement The item that was added to the collection.

instance.onItemRemoved

Signature of the function called when ever an item is removed from the collection.
Parameters:
Name Type Description
item HTMLElement The item that was added to the collection.

Events

coral-collection:add

Triggered when an item is added to the Collection. Collection events are not synchronous so the DOM may reflect a different reality although every addition or removal will be reported.
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. Collection events are not synchronous so the DOM may reflect a different reality although every addition or removal will be reported.
Callback Parameters:
Name Type Description
event Object

Event object.

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