5.0.0-rc.2 · release candidate (published on npm) · f4243b83 snapshot. Reading source: f4243b8334cafe0bd1b06eba85d87e2310cb3618. Match APIs to your installed version.

CollectionView#

API index · View · Shared View runtime

CollectionView owns repeated child Views and their placement, order, and lifetime. Supply a collection for one child per model, or add View instances directly. Use a View with named Regions for a layout containing distinct pieces of UI.

Render a collection#

This standalone TypeScript example uses @mnjs/data for observable membership and Lit for text rendering. API access and persistence remain separate concerns; see data setup.

import { CollectionView, Region, View } from 'marionette';
import { Collection, DataApi } from '@mnjs/data';
import LitDomApi from '@mnjs/adapters/dom/lit-html';
import { html } from 'lit-html';

const Item = View.extend({
  tagName: 'li',
  template: ({ label }: { label: string }) => html`${label}`,
  modelEvents: { change: 'render' },
}).setDataApi(DataApi).setDomApi(LitDomApi);

const Empty = View.extend({
  tagName: 'li',
  template: () => 'No items',
});

const List = CollectionView.extend({
  tagName: 'ul',
  childView: Item,
  emptyView: Empty,
  viewComparator: 'label',
}).setDataApi(DataApi);

const items = new Collection([
  { id: 'b', label: 'Blueberry', available: false },
]);
const list = new List({ collection: items });
const mount = document.createElement('section');
document.body.append(mount);
const region = new Region({ el: mount });
region.show(list);

items.add({ id: 'a', label: 'Apricot', available: true });
// Apricot sorts before Blueberry; the existing row keeps its View.
list.setFilter('available'); // Hides Blueberry; its child View stays alive.
list.removeFilter();        // Shows that same child again.

The Region owns the list; the list owns its rows and empty View. region.destroy() destroys that composition. It does not destroy items or its Models. Child model changes render through the child's modelEvents; they do not automatically rerun the list's comparator or filter. Call list.sort() or list.filter() when those criteria depend on changed attributes.

Construction and options#

new CollectionView(options?) establishes its fixed root, children storage, Behaviors, state access and event bindings. It calls preinitialize(options) before those resources, then initialize(options) after child storage and Behaviors exist. getState() is available inside initialize; state bindings, the empty Region, and entity bindings initialize afterward. Construction does not create rows or subscribe to collection membership; the first render() does.

CollectionView accepts View's root, template, data, UI/DOM, entity-event, state, Behavior and child-forwarding options. Their shared contracts are in View runtime, state, and View construction. It has no named-Region methods or regions/regionClass options. Custom options use common option methods.

Resolver functions and comparator/filter callbacks run with the CollectionView as this. childView and emptyView constructors are instantiated, not called as resolvers. Use CollectionView.extend(prototypeProperties?, staticProperties?) to declare defaults and overrides.

cid is generated with the class's cidPrefix ('mncv' by default). options contains merged class and constructor options. RegionClass configures the empty Region on the prototype or in initialize; despite appearing in the configuration type, passing it as a constructor option does not set that hook in this prerelease.

Rendering and collection updates#

A plain array is not observed. After changing it, render() rebuilds the list. Observable sources let additions and ordering changes preserve surviving Views and their DOM; do not call full render() merely to apply a filter or comparator. Use a new CollectionView when changing the collection source; assigning collection does not transfer an existing observer to that source.

The DataApi supplies models and stable, unique, non-null keys. The default uses each array value as its key; @mnjs/data uses Model cid, not id. Missing, duplicate or changing keys throw MN0039. Full adapter authoring is a separate reference area; normal consumers use a compatible DataApi setup.

template is optional. With no template or template: false, render() still manages rows and emits events; it only skips rendering the list's own template. A supplied root is adopted, but existing markup does not mark a CollectionView rendered or bind its UI automatically. With no template, call bindUIElements() when you need UI queries against that markup. Place children in a dedicated childViewContainer when the root also contains persistent markup.

Sorting#

Sorting changes View order without changing the source collection. Comparators operate on child Views:

• A string reads that attribute from each child's model through the DataApi.
• function(view) returns a sort key. Equal keys retain their current ordering; missing (undefined) keys sort last.
• function(left, right) returns a negative, zero, or positive number. Use two declared parameters: function arity distinguishes this form from a key function.

viewComparator: false disables comparator sorting. To ignore source reorder notifications as well, use sortWithCollection: false. With sortWithCollection: true, source updates establish source order before custom comparison, so equal-key ties follow the source. The default source-order comparator places manual children before collection rows when their model is missing or absent from the collection. Use an explicit comparator or indexed insertion when you need another order.

Configure initial options before rendering. The setters do not check readiness: their default behavior immediately runs a presentation pass. Use { preventRender: true } to defer a changed setting. Apply a deferred comparator with sort(); a deferred filter with filter() or sort(). Full rendering applies both.

Filtering#

Filtering controls presentation; it does not remove models or destroy their children. Hidden children keep state and subscriptions and remain owned by the list. children exposes the presented set after a filter pass.

Changing values captured by a predicate does not change the predicate's identity. Call filter() explicitly to apply those changes. Hidden Views can be shown again as the same instances; they are still destroyed when removed from the source, on full render/reset, or when the list is destroyed.

Empty presentation#

isEmpty() reports whether children has no presented rows. All rows can be filtered out while the source still has models. The emptyView appears for this presentation state, through the Region returned by getEmptyRegion().

The empty View is separate from children. It receives emptyViewOptions, or the childViewOptions fallback, with no automatic model. Give it a root suitable for the child container, such as li inside ul. Each empty presentation pass creates a new empty View and replaces the previous one; it is destroyed when rows appear or the list is destroyed. Its events use the same child forwarding as rows.

getEmptyRegion() returns the list-owned Region for the current child container, with replacement disabled. It is created during construction and reused while live; its owner is this CollectionView. If explicitly destroyed while the list is live, the next call recreates it. After list destruction, the getter returns the destroyed Region. Use it to inspect currentView; configure empty presentation through emptyView and emptyViewOptions.

Find and inspect children#

children is an iterable child container for the current presentation. It excludes filtered-out rows and the empty View. Newly adopted manual children enter it immediately, including when rendering is deferred; the next filter pass establishes the presented subset. Query this container; change ownership through the CollectionView methods below.

The container's Data is its lookup provider. Public query helpers do not change membership.

Manage View instances directly#

These operations do not change the source collection. For collection-backed rows, normally change the collection; direct removal does not remove the model and a later rebuild can recreate its View.

For addition, { index, preventRender } may be supplied as options; a non-null options index takes precedence over the positional index. preventRender defers child presentation, not adoption or the parent's initial render. Destroyed/falsy incoming Views and additions to a destroying/destroyed list return unchanged. Already owned incoming Views throw MN0003.

A child that destroys itself is removed from the list automatically. Full render() destroys manual children too and rebuilds only collection rows.

A same-key source update inserts its replacement View at the old child's position before sorting. Unaffected manual children retain identity; their placement follows the sorting rules, including preceding collection rows under the default source-order comparator.

Lifecycle and extension points#

CollectionView has the shared View attach/detach, DOM and destruction notifications described in View lifecycle. isRendered(), isAttached() and isDestroyed() report those states. destroy(options?) returns the list, removes its root, destroys all managed rows (including hidden rows) and its empty Region, and releases observation, bindings, Behaviors and owned state. Repeated destruction does nothing; it does not destroy the supplied model or collection.

Every event below dispatches its matching on… hook before subscribers. Child operations and observed changes can emit these events without a full list render.

A full render runs: before:render → old-row destruction → new-row additions → template/container setup → sort → filter → child/empty presentation → render. A collection reset omits the outer render and template phases. Direct removal tears down the child before remove-child notifications; observable removal drops its entry, updates presentation, then destroys the removed child. Region replacement explains the outer owner's teardown order. Callbacks are synchronous; a thrown callback can interrupt an operation.

DOM extension points perform placement only; ownership and lifecycle remain the job of the enclosing operations. Keep the fixed root. Shared getTemplate, serialization, UI, delegation, attributes, Behavior composition, child events and their methods are defined in View runtime. Class setters setRenderer, setDomApi, setDataApi, setStateApi, and setEventDelegator use its configuration contracts. Inherited object APIs are in common methods, events, and state.

TypeScript#

Import CollectionViewConfiguration, CollectionViewInstance, CollectionViewConstructor, CollectionChild, and ChildRenderOptions from marionette. Configuration describes accepted options; ChildRenderOptions contains index and preventRender. CollectionChild describes a managed View with container identity. Instance generics describe child type, options, state, collection source and query type. Constructor inference carries supplied child/source types and subclass properties through extend; normal applications can use that inference as in the example.

The children container interface is reachable through the instance type; its constructor is not a top-level Marionette export.