# Collection Class

Extends EventDispatcher
Defined in: `js/model/Collection.js:17`
Module: model
Parent Module: StructureJS

The Collection class provides a way for you to manage your models.

## Index

Show: Inherited Protected Private Deprecated

### Properties

- _listeners
- _modelType
- isEnabled
- length
- models
- parent
- sjsId

### Methods

- Collection constructor
- _findPropertyValue
- _where
- add
- addEventListener
- addEventListenerOnce
- clear
- clone
- destroy
- disable
- dispatchEvent
- enable
- filter
- findBy
- fromJSON
- get
- getEventListeners
- getQualifiedClassName
- groupBy
- has
- hasEventListener
- indexOf
- pluck
- remove
- removeEventListener
- reverse
- sort
- sortOn
- toJSON
- toJSONString

## Properties

### `_listeners` Array. protected

Inherited from EventDispatcher: `js/event/EventDispatcher.js:39`

Holds a reference to added listeners.

### `_modelType` Any protected

Defined in `js/model/Collection.js:64`

A reference to a BaseModel type that will be used in the collection.

### `isEnabled` Boolean public

Inherited from ObjectManager: `js/ObjectManager.js:31`

The isEnabled property is used to keep track of the enabled state of the object.

Default: false

### `length` Int public

Defined in `js/model/Collection.js:54`

The count of how many models are in the collection.

Default: 0

### `models` Array.

Defined in `js/model/Collection.js:46`

The list of models in the collection.

### `parent` Any public

Inherited from EventDispatcher: `js/event/EventDispatcher.js:47`

Indicates the object that contains a child object. Uses the parent property to specify a relative path to display objects that are above the current display object in the display list hierarchy and helps facilitate event bubbling.

### `sjsId` Int public

Inherited from BaseObject: `js/BaseObject.js:27`

The sjsId (StructureJS ID) is a unique identifier automatically assigned to most StructureJS objects upon instantiation.

Default: null

There are no properties that match your current filter settings. You can change your filter settings in the index section on this page. index

## Constructor

### `Collection`
(

- `baseModelType`

)

Defined in `js/model/Collection.js:17`

#### Parameters:

- `baseModelType` BaseModel

  Pass a class that extends BaseModel and the data added to the collection will be created as that type.

#### Example:

    let data = [{ make: 'Tesla', model: 'Model S', year: 2014 }, { make: 'Tesla', model: 'Model X', year: 2016 }];

    // Example of adding data to a collection
    let collection = new Collection();
    collection.add(data);

    // Example of adding data to a collection that will create a CarModel model for each data object passed in.
    let collection = new Collection(CarModel);
    collection.add(data);

## Methods

### `_findPropertyValue`
(

- `arg`

)
Array. protected

Defined in `js/model/Collection.js:265`

Loops through all properties of an object and check to see if the value matches the argument passed in.

#### Parameters:

- `arg` String | Number | Boolean>

#### Returns:

Array.:

Returns a list of found object's.

### `_where`
(

- `propList`

)
Array. protected

Defined in `js/model/Collection.js:222`

Loops through the models array and creates a new array of models that match all the properties on the object passed in.

#### Parameters:

- `propList` Object | Array

#### Returns:

Array.:

Returns a list of found object's.

### `add`
(

- `model`
- `[silent=false]`

)
public chainable

Defined in `js/model/Collection.js:74`

Adds model or an array of models to the collection.

#### Parameters:

- `model` Any | Array

  Single or an array of models to add to the current collection.

- `[silent=false]` Boolean optional

  If you'd like to prevent the event from being dispatched.

#### Example:

     collection.add(model);

     collection.add([model, model, model, model]);

     collection.add(model, true);

### `addEventListener`
(

- `type`
- `callback`
- `scope`
- `[priority=0]`

)
public chainable

Inherited from EventDispatcher: `js/event/EventDispatcher.js:59`

Registers an event listener object with an EventDispatcher object so the listener receives notification of an event.

#### Parameters:

- `type` String

  The type of event.

- `callback` Function

  The listener function that processes the event. This function must accept an Event object as its only parameter and must return nothing, as this example shows. @example function(event:Event):void

- `scope` Any

  Binds the scope to a particular object (scope is basically what "this" refers to in your function). This can be very useful in JavaScript because scope isn't generally maintained.

- `[priority=0]` Int optional

  Influences the order in which the listeners are called. Listeners with lower priorities are called after ones with higher priorities.

#### Example:

     this.addEventListener(BaseEvent.CHANGE, this._handlerMethod, this);

     _handlerMethod(event) {
         console.log(event.target + " sent the event.");
         console.log(event.type, event.data);
     }

### `addEventListenerOnce`
(

- `type`
- `callback`
- `scope`
- `[priority=0]`

)
public chainable

Inherited from EventDispatcher: `js/event/EventDispatcher.js:102`

Registers an event listener object once with an EventDispatcher object so the listener will receive the notification of an event.

#### Parameters:

- `type` String

  The type of event.

- `callback` Function

  The listener function that processes the event. This function must accept an Event object as its only parameter and must return nothing, as this example shows. @example function(event:Event):void

- `scope` Any

  Binds the scope to a particular object (scope is basically what "this" refers to in your function). This can be very useful in JavaScript because scope isn't generally maintained.

- `[priority=0]` Int optional

  Influences the order in which the listeners are called. Listeners with lower priorities are called after ones with higher priorities.

#### Example:

     this.addEventListenerOnce(BaseEvent.CHANGE, this._handlerMethod, this);

     _handlerMethod(event) {
         console.log(event.target + " sent the event.");
         console.log(event.type, event.data);
     }

### `clear`
(

- `[silent=false]`

)
public chainable

Defined in `js/model/Collection.js:304`

Clears or remove all the models from the collection.

#### Parameters:

- `[silent=false]` Boolean optional

  If you'd like to prevent the event from being dispatched.

#### Example:

     collection.clear();

### `clone` () Collection public

Defined in `js/model/Collection.js:323`

Creates and returns a new collection object that contains a reference to the models in the collection cloned from.

#### Returns:

Collection:

#### Example:

    let clone = collection.clone();

### `destroy` () Void public

Inherited from BaseObject: `js/BaseObject.js:55`

The purpose of the destroy method is to make an object ready for garbage collection. This should be thought of as a one way function. Once destroy is called no further methods should be called on the object or properties accessed. It is the responsibility of those who implement this function to stop all running Timers, all running Sounds, and take any other steps necessary to make an object eligible for garbage collection.

By default the destroy method will null out all properties of the class automatically. You should call destroy on other objects before calling the super.

#### Returns:

Void:

#### Example:

    destroy() {
         this.disable();

         this._childInstance.destroy();

         super.destroy();
    }

### `disable` () public chainable

Inherited from ObjectManager: `js/ObjectManager.js:64`

The disable method is responsible for disabling event listeners and/or children of the containing objects.

#### Example:

     disable() {
         if (this.isEnabled === false) { return this; }

         this._childInstance.removeEventListener(BaseEvent.CHANGE, this.handlerMethod, this);
         this._childInstance.disable();

         return super.disable();
     }

### `dispatchEvent`
(

- `event`
- `[data=null]`

)
public chainable

Inherited from EventDispatcher: `js/event/EventDispatcher.js:159`

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

#### Parameters:

- `event` String | BaseEvent

  The Event object or event type string you want to dispatch. You can create custom events, the only requirement is all events must extend BaseEvent.

- `[data=null]` Any optional

  The optional data you want to send with the event. Do not use this parameter if you are passing in a BaseEvent.

#### Example:

     this.dispatchEvent('change');

     // Example: Sending data with the event:
     this.dispatchEvent('change', {some: 'data'});

     // Example: With an event object
     // (event type, bubbling set to true, cancelable set to true and passing data) :
     let event = new BaseEvent(BaseEvent.CHANGE, true, true, {some: 'data'});
     this.dispatchEvent(event);

     // Here is a common inline event object being dispatched:
     this.dispatchEvent(new BaseEvent(BaseEvent.CHANGE));

### `enable` () public chainable

Inherited from ObjectManager: `js/ObjectManager.js:41`

The enable method is responsible for enabling event listeners and/or children of the containing objects.

#### Example:

    enable() {
         if (this.isEnabled === true) { return this; }

         this._childInstance.addEventListener(BaseEvent.CHANGE, this.handlerMethod, this);
         this._childInstance.enable();

         return super.enable();
    }

### `filter`
(

- `callback`
- `[callbackScope=null]`

)
Array. public

Defined in `js/model/Collection.js:443`

The filter method creates a new array with all elements that pass the test implemented by the provided function.

#### Parameters:

- `callback` Function

  Function to test each element of the array. Invoked with arguments (element, index, array). Return true to keep the element, false otherwise.

- `[callbackScope=null]` Object optional

  Optional. Value to use as this when executing callback.

#### Returns:

Array.:

Returns the list of models in the collection.

#### Example:

     let isOldEnough = function(model){
         return model.age >= 21;
     }

     let list = collection.filter(isOldEnough);

### `findBy`
(

- `arg`

)
Array. public

Defined in `js/model/Collection.js:184`

Examines each element in a collection, returning an array of all elements that have the given properties. When checking properties, this method performs a deep comparison between values to determine if they are equivalent to each other.

#### Parameters:

- `arg` Object | Array

#### Returns:

Array.:

Returns a list of found object's.

#### Example:

     // Finds all  Base Model that has 'Robert' in it.
     collection.findBy("Robert");
     // Finds any  Base Model that has 'Robert' or 'Heater' or 23 in it.
     collection.findBy(["Robert", "Heather", 32]);

     // Finds all  Base Models that same key and value you are searching for.
     collection.findBy({ name: 'apple', organic: false, type: 'fruit' });
     collection.findBy([{ type: 'vegetable' }, { name: 'apple', 'organic: false, type': 'fruit' }]);

### `fromJSON`
(

- `json`

)
public chainable

Defined in `js/model/Collection.js:371`

Converts the string json data into an Objects and calls the add method to add the objects to the collection.

#### Parameters:

- `json` String

#### Example:

     collection.fromJSON(str);

### `get`
(

- `index`

)
Object public

Defined in `js/model/Collection.js:171`

Finds an object by an index value.

#### Parameters:

- `index` Int

  The index integer of the model to get

#### Returns:

Object:

the model

#### Example:

     let model = collection.get(1);

### `getEventListeners` () String public

Inherited from EventDispatcher: `js/event/EventDispatcher.js:248`

Generates a string output of event listeners for a given object.

#### Returns:

String:

#### Example:

     this.getEventListeners();

     // [ClassName] is listening for the 'BaseEvent.change' event.

### `getQualifiedClassName` () String public

Inherited from BaseObject: `js/BaseObject.js:40`

Returns the fully qualified class name of an object.

#### Returns:

String:

Returns the class name.

#### Example:

    let someClass = new SomeClass();
    someClass.getQualifiedClassName();

    // SomeClass

### `groupBy`
(

- `propertyName`

)
Any public

Defined in `js/model/Collection.js:492`

Convenient way to group models into categories/groups by a property name.

#### Parameters:

- `propertyName` String

  The string value of the property you want to group with.

#### Returns:

Any:

Returns an object that is categorized by the property name.

#### Example:

     collection.add([{name: 'Robert', id: 0}, {name: 'Robert', id: 1}, {name: 'Chris', id: 2}]);

     let list = collection.groupBy('name');

     // {
     //    Robert: [{name: 'Robert', id: 0}, {name: 'Robert', id: 1}]
     //    Chris: [{name: 'Chris', id: 2}]
     // }

### `has`
(

- `model`

)
Boolean public

Defined in `js/model/Collection.js:145`

Checks if a collection has an model.

#### Parameters:

- `model` Object

  Item to check

#### Returns:

Boolean:

#### Example:

     collection.has(model);

### `hasEventListener`
(

- `type`
- `callback`
- `scope`

)
Boolean public

Inherited from EventDispatcher: `js/event/EventDispatcher.js:223`

Check if an object has a specific event listener already added.

#### Parameters:

- `type` String

  The type of event.

- `callback` Function

  The listener method to call.

- `scope` Any

  The scope of the listener object.

#### Returns:

Boolean:

#### Example:

     this.hasEventListener(BaseEvent.CHANGE, this._handlerMethod, this);

### `indexOf`
(

- `model`

)
Int public

Defined in `js/model/Collection.js:158`

Returns the array index position of the Base Model.

#### Parameters:

- `model` Object

  get the index of.

#### Returns:

Int:

#### Example:

     collection.indexOf(model);

### `pluck`
(

- `propertyName`
- `[unique=false]`

)
Array. public

Defined in `js/model/Collection.js:462`

Convenient way to get a list of property values.

#### Parameters:

- `propertyName` String

  The property name you want the values from.

- `[unique=false]` String optional

  Pass in true to remove duplicates.

#### Returns:

Array.:

#### Example:

     collection.add([{name: 'Robert'}, {name: 'Robert'}, {name: 'Chris'}]);

     let list = collection.pluck('name');
     // ['Robert', 'Robert', 'Chris']

     let list = collection.pluck('name', true);
     // ['Robert', 'Chris']

### `remove`
(

- `model`
- `[silent=false]`

)
public chainable

Defined in `js/model/Collection.js:114`

Removes a model or an array of models from the collection.

#### Parameters:

- `model` Object | Array

  Model(s) to remove

- `[silent=false]` Boolean optional

  If you'd like to prevent the event from being dispatched.

#### Example:

     collection.remove(model);

     collection.remove([model, model, model, model]);

     collection.remove(model, true);

### `removeEventListener`
(

- `type`
- `callback`
- `scope`

)
public chainable

Inherited from EventDispatcher: `js/event/EventDispatcher.js:131`

Removes a specified listener from the EventDispatcher object.

#### Parameters:

- `type` String

  The type of event.

- `callback` Function

  The listener object to remove.

- `scope` Any

  The scope of the listener object to be removed.

#### Example:

     this.removeEventListener(BaseEvent.CHANGE, this._handlerMethod, this);

### `reverse` () Array. public

Defined in `js/model/Collection.js:525`

Changes the order of the models so that the last model becomes the first model, the penultimate model becomes the second, and so on.

#### Returns:

Array.:

Returns the list of models in the collection.

#### Example:

     collection.reverse();

### `sort`
(

- `[sortFunction=null]`

)
Array. public

Defined in `js/model/Collection.js:423`

Specifies a function that defines the sort order. If omitted, the array is sorted according to each character's Unicode code point value, according to the string conversion of each element.

#### Parameters:

- `[sortFunction=null]` Function optional

#### Returns:

Array.:

Returns the list of models in the collection.

#### Example:

     let sortByDate = function(a, b){
         return new Date(a.date) - new Date(b.date)
     }

     collection.sort(sortByDate);

### `sortOn`
(

- `propertyName`
- `[sortAscending=true]`

)
Array public

Defined in `js/model/Collection.js:386`

Allows you to sort models that have one or more common properties, specifying the property or properties to use as the sort keys

#### Parameters:

- `propertyName` String
- `[sortAscending=true]` Boolean optional

#### Returns:

Array:

Returns the list of models in the collection.

#### Example:

     collection.sortOn('name');
     collection.sortOn('name', false);

### `toJSON` () Array. public

Defined in `js/model/Collection.js:337`

Creates a JSON object of the collection.

#### Returns:

Array.:

#### Example:

    let arrayOfObjects = collection.toJSON();

### `toJSONString` () String public

Defined in `js/model/Collection.js:359`

Creates a JSON string of the collection.

#### Returns:

String:

#### Example:

    let str = collection.toJSONString();

There are no methods that match your current filter settings. You can change your filter settings in the index section on this page. index