About Docs GitHub
arrow_upward Back to top
Docs (4.0.0)
arrow_upward Back to top
Data structures

class ManagedList

A data structure that contains an ordered set of managed objects.

class ManagedList<T extends ManagedObject = ManagedObject>
extends ManagedObject

Description

Lists of managed objects — instances of ManagedObject — can be represented using regular arrays. However, often a ‘list of objects’ needs to be more restrictive, especially in the context of a UI framework. A managed list is useful in the following cases:

  • The list should only contain instances of a certain type, or at least only ManagedObject instances.
  • The list shouldn’t contain any duplicates, gaps, or undefined values.
  • The list should be observable: actions can be taken when items are added, removed, or reordered.
  • Events from (attached) list items should be ‘propagated’ on the list, to avoid having to add event listeners for all items — see ManagedEvent.
  • List items should be able to bind to the object containing the (attached) list — see Binding.

Managed lists are used in many places throughout the framework, such as to reference view objects within a UIContainer object. Managed lists can also be used by application code to efficiently represent lists of data models or other records.

Attaching list items — By default, objects aren’t attached to the list, so they could be attached to other objects themselves and still be part of a managed list. However, you can enable auto-attaching of objects in a list using the ManagedList.attachAll() method — or by attaching the list itself to another object. This ensures that objects in a list are only attached to the list itself, and are unlinked when they’re removed from the list (and removed from the list when they’re no longer attached to it, e.g. when moved to another auto-attaching list).

Events — Since ManagedList itself inherits from ManagedObject, a list can emit events, too. When any objects are added, moved, or removed, a ManagedList.ChangeEvent is emitted. In addition, for auto-attaching lists (see ManagedList.attachAll()) any events that are emitted by an object are re-emitted on the list itself. The ManagedEvent.source property can be used to find the object that originally emitted the event.

Nested lists — Managed lists can contain (and even attach to) other managed lists, which allows for building nested or recursive data structures that fully support bindings and events.

Example

// Create a list, add and remove objects
let a = ManagedRecord.create({ foo: "a" });
let b = ManagedRecord.create({ foo: "b" });
let list = new ManagedList(a, b);

let c = ManagedRecord.create({ foo: "c" });
list.add(c);
list.count // => 3

list.remove(b);
list.count // => 2

let a = list.map(record => record.foo);
a // => ["a", "c"]

// Lists can be iterated using for...of, too
for (let item of list) {
  // ...do something for each item
}

Constructor

Type Members

  • type ManagedList.ChangeEvent staticType definition for an event that’s emitted when elements are added to, removed from, or moved within a list.

Instance Members

Inherited Members