List Stock Element

You can use this Stock Element by extending the exported global: window.casthub.elements.list

The List Stock Element is a great base element for any, well, lists. For example, we use the List Stock Element in the various Donation Modules, such as the Tipeeestream Donations Module.

Adding or Removing Items

You can add or remove Items from the List using the add and remove methods. The signature for these methods is super-simple:

  • add(id, item) - Items must have a unique id!
  • remove(id) - Removes an Item based on the unique id.
  • clear() - Removes all Items from the list.

If you'd like to manually access the current list items, you can use the this.items Object.

Item Definition

When adding an Item object, it must follow a given definition.

{
    // All Items are required to have a title.
    title: 'My Item',
    // Subtext displays below the title.
    subtext: 'Hello World',
    // Avatar must be a URL to an image if they're enabled.
    avatar: '',
    // An optional `update` function that is run once a second.
    update(item) {
        // `item` is a reference to the item data that you can update.
    },
}

Limiting List Length

To keep your List to a specific length, you can set the limit property in your constructor. For example:

constructor() {
    super();

    this.limit = 5;
}

This property is reactive and if lessened, will remove any overflowing items. However, if increasing the value, it will not show more items until new ones are added.

By default, limit is set to -1, which means the list will not limit the Items you add.

Avatars

Avatars are disabled for List Items by default. You can enable them by setting the avatars property to true in your constructor. For example:

constructor() {
    super();

    this.avatars = true;
}

Sorting and Filtering

By implementing the optional functions, you can easily filter and sort any of the List Items that you add automatically.

/**
 * Filters out any unwanted Items.
 *
 * @param {Array} items
 *
 * @return {Array}
 */
filter(items) {
    return items;
}

/**
 * Sorts the given List Items.
 *
 * @param {Array} items
 *
 * @return {Array}
 */
sort(items) {
    return items;
}

Modifying the Header

The List Stock Element comes with a Header Component and provides short and easy setters for modifying it. For example:

constructor() {
    super();

    this.icon = 'tipeeestream';
    this.title = 'Latest Donations';
    this.color = '#313747';
}