List

Lists are collections of record names. To learn more about how they are used, have a look at the List Tutorial.

Lists and record names have an n:m relationship. A record name can be part of many lists and a list can contain many record names. A list can also contain the same record name multiple times.

Creating lists

Lists are created and retrieved using client.record.getList( 'name' );

const list = client.record.getList( 'cars' );

Properties

Events

entry-added

Emitted whenever a new entry is added to the list. Passes the entry and its position within the list to the callback.

entry-moved

Emitted whenever an entry is moved within the list. Passes the entry and its new position within the list to the callback.

entry-removed

Emitted whenever an entry is removed from the list. Passes the entry and its last position within the list to the callback.

delete

Emitted when the list was deleted, whether by this client or by another.

discard

Emitted once the list was discarded.

error

Emitted if the list encounters an error. The error message is passed to the event callback.

Methods

whenReady( callback )

Invokes callback once the list has been loaded. This might happen synchronously if the list is already available or asynchronously if the list still needs to be retrieved. Some methods, e.g. addEntry() or setEntries() or subscribe() can be used before the list is ready.

// Callback
list.whenReady( ( list ) => {
  // interact with the list
});

// ES6
await list.whenReady()

isEmpty()

Returns false if the list has entries or true if it doesn’t.

if( list.isEmpty() ) {
  // You don't have any entries
}

getEntries()

Returns an array of the current entries in the list.

const entries = list.getEntries()
console.log( entries ) // [ 'car/1', 'car2' ]

setEntries( entries )

Sets the contents of the list to the provided array of record names. To add or remove specific entries use addEntry() or removeEntry() respectively.

list.setEntries( [ 'car/1', 'car/2' ] );

addEntry( entry, index )

Adds a new record name to the list.

function addCar( number ) {
  const id = 'car/' + client.getUid();
  client.record.getRecord( id ).set( 'number', number );
  list.addEntry( id );
}

removeEntry( entry, index )

Removes an entry from the list. removeEntry will not throw any error if the entry doesn’t exist.

function removeCar( carRecord ) {
  list.removeEntry( carRecord.name );
}

subscribe( callback, triggerNow )

Registers a function that will be invoked whenever any changes to the list’s contents occur. Optionally you can also pass true to execute the callback function straight away with the list’s current entries.

function listChanged( entries ) {
  // entries in list has changed
}
list.subscribe( listChanged, false );

unsubscribe( callback )

Removes a subscription that was previously made using list.subscribe()

Please Note: unsubscribe is purely a client side operation. To notify the server that the app no longer requires updates for this list use discard().

list.unsubscribe( listChanged );

discard()

Removes all change listeners and notifies the server that the client is no longer interested in updates for this list.

list.discard();

delete()

Deletes the list on the server. This action deletes the list for all users from both cache and storage and is irreversible.

list.delete();