List

A lightweight display list for rendering dynamic items. Items are plain containers with no visual frame by default — add your own padding and layout inside the html payload. For drag-to-reorder behaviour, use the Reorderable component instead.

Basic List

Items can be updated, added, or removed via the JS API without a page reload.

Review pull requests

Deploy staging build

Fix login redirect bug

Update documentation

Interact to see output...

// Static list — items provided server-side
<?= $m->list('myList')
    ->emptyMessage('No items yet')
    ->items([
        ['key' => '1', 'html' => '<div style="padding:.6rem .85rem"><i class="fas fa-inbox"></i> Item one</div>'],
        ['key' => '2', 'html' => '<div style="padding:.6rem .85rem"><i class="fas fa-code"></i> Item two</div>'],
    ]) ?>

// Empty list — populated via JS
<?= $m->list('taskList')->emptyMessage('No tasks yet') ?>

// Get list instance
var list = m.list('myList');

// Add / update / remove items
list.addItem('5', '<div style="padding:.6rem .85rem"><strong>New</strong> item</div>');
list.upsertItem('2', '<div style="padding:.6rem .85rem"><em>Updated</em> item</div>');
list.removeItem('1');
list.clear();

// Count
var n = list.count();

// Refresh from URL (replaces list contents)
list.refresh('/api/items').then(function() {
    console.log('Refreshed');
});

// Listen for refresh events
document.getElementById('myList')
    .addEventListener('m:list:refresh', function(e) {
        console.log('Items refreshed:', e.detail);
    });

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->list($id)`	`string`	Create a list component.
`->items($items)`	`array`	Set list items. Each: `{key, html, id?, class?, attrs?}`.
`->emptyMessage($msg)`	`?string`	Message shown when the list has no items.

JS JS Methods

Method / Property	Parameters	Description
`m.list(id, opts)`	`string, ?object`	Get or create list instance.
`addItem(key, html, opts)`	`string, string, ?object`	Append a new item.
`upsertItem(key, html, opts)`	`string, string, ?object`	Update existing item or insert if not found.
`removeItem(key)`	`string`	Remove an item by key.
`clear()`		Remove all items.
`count()`		Returns number of items.
`getItems()`		Returns array of item DOM elements.
`getOrder()`		Returns array of item keys in current order.
`refresh(url, opts)`	`string, ?object`	Fetch item HTML from URL and replace list contents (returns Promise).

EVENT Events

Event Name	Detail	Description
`m:list:refresh`	`{id, items}`	Fired after content is refreshed from a URL.
`m:list:refresh:error`	`{id, error}`	Fired if content refresh fails.