# Marionette 5.0.0 documentation bundle
Version: 5.0.0
Channel: latest
Publication: stable release (published on npm)
Source revision: 0f2284ad4bbfe8c82ce82714471697a68c2acaeb
Local changes: false
Content SHA-256: 44c0d535fd36d11f31d909246f4ee7c6592eae3f25fb7513c61af65842593a90
Read individual documents for focused tasks. Each section below contains the exact published reading Markdown, including its source identity.
---
Document: docs/api/application.md
Canonical URL: https://marionettejs.com/docs/api/application/
Markdown URL: https://marionettejs.com/docs/api/application.md
Reading SHA-256: efe451d101c2b3d8a1da78910ac833fe8b0d80132412d8f29044a98388ba9c9a
# Application
[API index](/docs/api.md) · [View](/docs/api/view.md) · [Region](/docs/api/region.md)
Application coordinates readiness, composition, and state for a feature lifetime. It can own a root View, registered child Applications, and a destination Region. A local control can remain a View; use an Application when shared workflow or lifetime needs an owner.
## Prepare before showing UI
This standalone TypeScript example loads a summary before showing it. `/summary.json` returns `{ "title": string }`. Application owns the request; View renders the result.
```ts
import { Application, View, type ApplicationInstance, type LifecycleContext } from 'marionette';
import LitDomApi from '@mnjs/adapters/dom/lit-html';
import { html } from 'lit-html';
type Summary = { title: string };
const SummaryView = View.extend({
template: ({ title }: Summary) => html`
${title}
`,
}).setDomApi(LitDomApi);
const SummaryApplication = Application.extend({
async prepareStart(_options: unknown, { signal }: LifecycleContext): Promise {
const response = await fetch('/summary.json', { signal });
if (!response.ok) throw new Error('Could not load the summary.');
return response.json();
},
onStart(_app: ApplicationInstance, _options: unknown, summary: Summary) {
this.showView(new SummaryView({ model: summary }));
},
});
const mount = document.createElement('section');
document.body.append(mount);
const app = new SummaryApplication({ region: { el: mount } });
await app.start();
```
`prepareStart` may return a value or Promise. Its current successful result reaches `onStart`; failure rejects the requesting `start()` or `restart()`. The caller handles that rejection. `stop()` cancels pending preparation and tears down owned UI synchronously.
`restart()` repeats preparation while retaining the current presentation and active children. This example explicitly replaces SummaryView in `onStart` after success. To keep a shell, input, and child identity through completion too, see [retained restart](/docs/guides/retained-restart.md).
Plain response data uses the default DataApi. For observable data, configure [native data](/docs/integrations/setup.md#observable-data-and-api-access) or another integration. API access and persistence remain separate.
## Construction and options
`new Application(options?)` creates a stopped instance. Construction calls `preinitialize(options)`, configures Region, Radio and state, constructs declared children, calls `initialize(options)`, then binds state events. Neither hook starts the Application. `getState()` is available inside `initialize`.
| Option | Contract |
| --- | --- |
| `region` | Selector string, Region options object, Region constructor, or existing Region instance. Optional without mounted UI. See [root ownership](#root-view-and-region). |
| `regionClass` | Default constructor when building a Region from configuration; defaults to the runtime's Region. Individual definitions can override it. |
| `childApps` | Map of names to Application constructors, or a function returning that map. Children are constructed once without arguments. Constructor/subclass maps replace rather than merge. |
| `state`, `stateEvents` | Borrowed state and declarative observation. `createState(options)` supplies owned state; see [state](/docs/api/shared/state.md). |
| `viewEvents` | Event-handler map, or function returning one, bound to each selected root View. Values are callbacks or Application method names. See [View events](#view-events). |
| `channelName` | Channel name, or function returning one. A falsy name disables declarative Radio setup. |
| `radioEvents`, `radioRequests` | Event/reply handler maps, or functions returning maps. Values are callbacks or Application method names. See [Radio bindings](#radio-bindings). |
Resolvers run with the Application as `this`. A Region constructor is a class to instantiate; a function supplied as `state` remains the source itself. `options` merges class and constructor options. Custom options are read with `getOption(name)` and are not automatically instance fields.
`Application.extend(prototypeProperties?, staticProperties?)` creates a subclass. `preinitialize` and `initialize` default to no-ops. `cid` uses the class's `cidPrefix` (`'mna'` by default). See [class utilities](/docs/api/shared/common.md) for shared options and custom constructors.
## Lifecycle methods and results
| Method | Behavior |
| --- | --- |
| `start(options?)` → `Promise` | Prepares and activates. An active Application resolves `true` without repeating preparation or applying new options. Pending initial starts share the first preparation's Promise and options. |
| `restart(options?)` → `Promise` | Repeats preparation without stopping. Retains the root, active children, state, and subscriptions unless application code replaces them. Each call supersedes pending preparation. When stopped, prepares and activates using the retained destination. |
| `stop(options?)` → boolean | Cancels pending preparation, stops registered children, destroys prepared/displayed roots, and returns `true` synchronously. Retains the Application, state, children and destination for reuse. |
| `destroy(options?)` → boolean | Deactivates immediately, cancels preparation, stops descendants and destroys roots, then destroys child Applications and owned resources. Returns `true` synchronously. |
| `isRunning()` → boolean | Reports this Application's activity, independently of its descendants. |
| `isDestroyed()` → boolean | True when terminal destruction commits, before `onDestroy`. |
Initial preparation is inactive. Restart of an active Application stays active, including `stateEvents` delivery. Ordinary stop deactivates after `before:stop` and child stops, before root teardown. Destroy deactivates immediately.
Start/restart resolve `false` when superseded or cancelled, or when a stop/terminal owner prevents activation. Current preparation and startup callback failures reject. A hook returning `false` is not a veto: it may be a successful preparation result.
Stop is synchronous and cannot be superseded during cleanup. Start/restart during stop or destruction resolve `false`. `onStop` runs after successful cleanup and may explicitly start the next run. Calling stop on a stopped owner still cleans roots and stops descendants without repeating that owner's stop notifications. Repeated stop/destroy after successful destruction return `true`.
`ApplicationStartOptions` accepts an existing Region and feature options. `ApplicationRestartOptions` forwards feature options, including any `region`, unchanged to hooks, but restart never changes its destination. Stop/destroy forward arbitrary options to notifications and child operations. None of these arguments merge into constructor `options`.
```text
stopped → start() → prepareStart → active → onStart
stopped → restart() → prepareStart → active → onStart (retained destination)
active → restart() → prepareStart → onStart → active
│
└── preparation rejects → existing active UI retained
active → stop() → stopped (root destroyed; Application/state retained)
live → destroy() → destroyed (owned UI, children and resources disposed)
```
An active restart retains its UI during preparation; `onStart` chooses what to update. Initial preparation failure leaves the Application stopped. A newer restart, stop or destroy cancels pending preparation, preventing its obsolete result from reaching `onStart`. This diagram describes successful synchronous callbacks; the failure boundary below still applies.
## Preparation, cancellation, and failure
`prepareStart(options, { signal })` is the only awaited lifecycle hook. Its result reaches `onStart(app, options, result)` and `start` subscribers. Notification hooks run synchronously and ignore returned Promises. Await required business work before teardown, for example `await app.saveDraft(); app.stop()`.
A newer restart, stop, or destroy cancels pending preparation: the prior call resolves `false`, its signal is aborted, and its obsolete result cannot reach `onStart`. Pass the signal to dependencies. Cancellation cannot undo completed work; return ready data from preparation and apply it in `onStart`. Check `signal.throwIfAborted()` after an await before additional side effects if a dependency ignores cancellation. A completed preparation signal is not a lifetime signal and is not aborted by a later stop.
A failed initial preparation leaves the Application stopped. A failed restart of an active Application leaves it active with its existing UI and children. Display errors without stopping that retained feature. Children or Views explicitly created during initial preparation may need cleanup when abandoning a failed start. A throw from `onStart` rejects after activation; synchronous callback failures do not roll back completed work.
Synchronous construction or teardown failures throw and abort remaining steps. Marionette promises no rollback, attempt-all cleanup, or retry of a partial instance. See [event cleanup](/docs/api/shared/events.md#cleanup) for the same failure boundary.
## Readiness and ongoing effects
Use preparation for data and prerequisites needed before activation or before applying a restarted result. Use `onStart` to commit that result. When retaining UI, construct and connect the shell once, then update the source or child Region that changed; avoid recreating it unconditionally in every `onStart`.
Long-lived effects such as Window listeners or timers need explicit activation and cleanup. Install them once for the active run and release them in `onStop`; restart calls `onStart` again without calling `onStop`. Persistence and other domain operations have their own concurrency and lifetime policy. Marionette does not automatically cancel work started outside preparation. See [retained restart](/docs/guides/retained-restart.md) and [lifetime choices](/docs/architecture.md#choose-what-survives-an-operation).
## Child Applications
`childApps: { summary: SummaryApplication }` constructs a child once with its parent. For per-instance arguments, construct and register it explicitly.
| Method | Contract |
| --- | --- |
| `addChildApp(name, child)` | Registers and returns the instance without starting it. |
| `getChildApp(name)` | Returns the registered instance or `undefined`. |
| `hasChildApp(name)` | Reports whether the name is registered. |
| `getChildApps()` | Returns a new name-to-instance map; changing it does not change registration. |
| `getName()` | Returns the registered name or `undefined`. |
| `removeChildApp(name, options?)` | Destroys the child synchronously and returns it, or `undefined` for an unknown name. A callback failure throws. |
Names must be nonempty. Children must share the parent's runtime and have one owner/name. Self/ancestor registration, conflicting names and multiple owners throw `MN0031`. Repeating the same registration is harmless. A destroying/destroyed parent or child cannot acquire a new registration. Successful child destruction unregisters it automatically.
Registration owns lifetime, not readiness. Parent start does not start or await children. Start prerequisites explicitly in preparation when their readiness is required; handle the separate Promise when starting a child from a notification. Parent restart leaves children active. To reprepare a child too, call its `restart()` explicitly.
Parent stop traverses children in registration order, including descendants beneath stopped intermediate owners. Child instances remain registered for reuse. Parent destruction stops descendants before `before:destroy`, which can inspect stopped, live children; it then destroys children in registration order. Descendant start/restart is blocked during an ancestor's stop or terminal phase. There are no Application add/remove-child notification events.
### Child operations during lifecycle notifications
These phase rules apply to both method hooks and event listeners: `onBefore…` / `on('before:…', callback)`, and `onStop` / `on('stop', callback)`. Hooks run first; listeners then run synchronously in registration order. A notification is not an awaited coordination step.
| Parent notification | Child operation and consequence |
| --- | --- |
| `before:start` | An explicit child `start()` or `restart()` can begin, but its Promise is not awaited by the parent, even if the callback returns it. An explicit child `stop()` completes synchronously; it does not cancel parent startup. |
| `before:stop` | The parent is already stopping. Descendant `start()` and `restart()` resolve `false`, including from descendant cleanup callbacks. Explicitly stopping a child early is safe; normal parent teardown still stops the remaining descendants. |
| `before:destroy` | Descendants have already been stopped and are about to be destroyed. Inspect or release external resources here; descendant activation resolves `false`. New child registration is ignored and leaves the supplied instance owned by the caller. |
| `stop` after ordinary stop | Cleanup has finished, so an explicitly requested next run can start if no ancestor is still stopping. A child can run while its parent remains stopped; starting the parent does not start children automatically. When an ancestor is stopping this parent, descendant activation still resolves `false` during the parent's `stop` callback. During destruction, terminal ownership still blocks activation. |
When child readiness is required for parent success, await it in `prepareStart`, check the preparation signal after the await, and handle a canceled child result explicitly. This recipe assumes parent preparation is the only code that starts this child. Do not use it to join an independently pending child start: `isRunning()` is false during preparation, so the abort handler would cancel work this attempt did not initiate. Give independently started work its own coordinator and cancellation policy:
```js
import { Application } from 'marionette';
const Feature = Application.extend({
childApps: { results: Application },
async prepareStart(options, { signal }) {
const child = this.getChildApp('results');
if (!child) { throw new Error('Required child is missing'); }
if (child.isRunning()) { return; }
signal.addEventListener('abort', () => child.stop(), { once: true });
const started = await child.start();
signal.throwIfAborted();
if (!started) { throw new Error('Required child did not start'); }
},
});
const feature = new Feature();
await feature.start();
```
This recipe explicitly cancels a child started for the pending parent attempt, including the interval after the child starts but before the parent commits. It preserves an already-running child during restart. Keep the abort listener connected until the attempt settles; a committed preparation's signal is not aborted by later lifecycle operations. This is the recipe's coordination policy, not automatic rollback by Application.
Use the child's `restart()` in preparation only when it should reprepare too; `start()` preserves an already-running child. Parent stop cancels pending child readiness. A rejected parent preparation does not roll back already-started children; explicitly stop or destroy the parent when abandoning that startup.
Calling parent `stop()` from its `before:start` callback is supported cancellation, but it does not cancel the remaining notification listeners. A later listener can still perform side effects or independently start a child after that stop has finished. Keep required child activation in `prepareStart`, which only begins if the parent preparation is still current, instead of distributing dependent lifecycle actions across notification callbacks. Starting an optional child from a notification remains explicit independent work: handle its Promise and rejection yourself.
Do not unconditionally call the same Application's `restart()` from its `before:start` callback: restart emits `before:start` again and supersedes the outer attempt. A conditional redirect must terminate; for ordinary refresh, request restart from the coordinating caller. A repeated `start()` during initial preparation joins that pending preparation instead. These rules do not prohibit synchronous preparation of state or inspection in before hooks.
## Root View and Region
| API | Contract |
| --- | --- |
| Constructor `region` | Builds an owned Region or borrows an existing instance. See [Region construction](/docs/api/region.md#construction-and-options). |
| `start({ region })` | Binds an existing Region from the same runtime before startup preparation. An active or pending start ignores newly supplied options. Use `stop(); await start({ region })` to move hosts. |
| `restart({ region })` | Forwards the option to hooks while retaining the current destination. |
| `getRegion()` | Returns the current destination or `undefined`. |
| `setView(view)` | Owns a prepared root without rendering/mounting it and returns it. Replacing a prepared root destroys that root. |
| `getView()` | Returns this Application's prepared root, otherwise its displayed root, or `undefined`. |
| `showView(view?, options?)` | Selects a supplied root and shows it through the destination with Region `ShowOptions`. Returns the root, or `undefined` if none exists. A destination is required when a root exists. If the root is already displayed, returns it without showing again; supplied options have no effect. |
`setView` → the root's `showChildView` → `showView` allows composition before attachment. A prepared replacement leaves the displayed root in place until shown. Display transfers ownership to Region; Application tracks its displayed root. Stop/destroy clean prepared and displayed roots. Restart does neither automatically. `Region.empty()` clears displayed content and its Application association; it does not stop the Application or destroy a separate prepared root.
A selected View must be live and unowned (`MN0007` for destroyed, `MN0003` for another owner). Selecting the same root is harmless. Reselecting the displayed root destroys any prepared replacement. Content shown directly through a Region is Region-owned and cannot be adopted. During/after Application destruction, set/show methods return their supplied View without adopting it; its caller remains responsible.
An Application can own [existing markup](/docs/api/view.md#existing-elements) with `setView(new PageView({ el, template: false }))`, without rendering or a destination. Stop removes that View's element; a later start needs markup again. Applications can also have no root UI.
Stop retains the destination. Destroy disposes a Region built from configuration; a borrowed Region survives. Stop leaves another owner's replacement in a borrowed Region alone. An owned Region's current content is cleaned. Moving to a new destination disposes the old owned Region; old borrowed Regions survive.
### Destination binding order
Initial startup binds the requested Region before `before:start` and `prepareStart`. Omitting `region` keeps the current host. A failed or cancelled preparation does not roll back host binding already completed. Restart uses the current host, including when its forwarded options contain another Region.
### View events
`viewEvents: { submit: 'saveDraft' }` observes events from roots selected with `setView` or `showView`, including a prepared View before display. A function declaration resolves with the Application as `this`; handlers also receive that context and the View event arguments unchanged.
Bindings are made once per selected View through ordinary `listenTo`. They remain active while stopped, during preparation, and when a live View is detached. They end when the View or Application is destroyed, or when explicitly removed with `stopListening`. Reselecting a View does not duplicate or restore explicitly removed bindings. A live replaced source retains ordinary listener lifetime; bind manually if a narrower scope is needed.
## State and Radio
State comes from owned `createState(options)` or borrowed `state`; read it with `getState()`. Start/stop/restart retain the source. Declarative `stateEvents` deliver while `isRunning()` is true, including an active restart; stopped/initial preparation changes are not replayed. Ordinary `listenTo` subscriptions retain their source lifetime. See [state ownership](/docs/api/shared/state.md).
`Application.setStateApi(api)` overlays the receiving class's provider and returns it. `State` is the provider. Configure it before construction; see [StateApi](/docs/api/shared/state.md#configure-the-stateapi).
### Radio bindings
`channelName`, `radioEvents`, `radioRequests`, `getChannel()` and `Radio` follow [declarative Radio bindings](/docs/api/shared/common.md#declarative-radio-bindings). They are active while stopped or running. Destruction releases this Application's bindings while preserving the shared channel.
## Lifecycle hooks and events
Events dispatch their hook first, then subscribers, through [triggerMethod](/docs/api/shared/events.md). Hook and subscriber arguments match.
| Event | Hook | Arguments and timing |
| --- | --- | --- |
| `before:start` | `onBeforeStart` | `(app, options)` before preparation; inactive for initial start, still active for a running restart. |
| `start` | `onStart` | `(app, options, result)` after current preparation succeeds and activity is true. |
| `before:stop` | `onBeforeStop` | `(app, options)` before child stops and root cleanup. Ordinary stop is still active here; destroy has deactivated. |
| `stop` | `onStop` | `(app, options)` after successful child/root cleanup, while inactive. May start the next run. |
| `before:destroy` | `onBeforeDestroy` | `(app, options)` after stop/root cleanup, before child destruction. |
| `destroy` | `onDestroy` | `(app, options)` after terminal state, child/owned-Region disposal, parent unregistration and Radio/state cleanup. Subscriptions are cleared afterward. |
Restart has no separate event and uses only the startup notifications. `preinitialize` and `initialize` are constructor hooks.
### Restart from start completion
The current preparation is complete before `onStart` and `start` subscribers. A restart requested there starts a new preparation with its own options and Promise. The completed outer call resolves `true`, describing its own successful completion, even if the new preparation fails or is superseded later.
## TypeScript
Import `ApplicationOptions`, `ApplicationStartOptions`, `ApplicationRestartOptions`, `LifecycleContext`, `ApplicationInstance`, and `ApplicationConstructor` from `marionette`. Constructor and per-operation options are separate. `LifecycleContext` contains the preparation signal. `ApplicationInstance` describes constructor options, state and the successful result. `extend` carries the awaited return type of `prepareStart` into that contract. Annotate overridden hook parameters as in the example.
Start destinations use `RegionInstance`; constructor definitions use `RegionDefinition`/`RegionClass`. Root methods preserve a supplied View's type. Child lookup/removal returns the common Application interface; narrow it for child-specific methods. Shared types are listed with their [state](/docs/api/shared/state.md) and [event](/docs/api/shared/events.md) contracts.
[Canonical source](/docs/markdown/docs/api/application.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/view.md
Canonical URL: https://marionettejs.com/docs/api/view/
Markdown URL: https://marionettejs.com/docs/api/view.md
Reading SHA-256: 3cb4f074ee914aa5692a65dff64a95638e88fb347d5c74c24ca5850e97d0657d
# View
[API index](/docs/api.md) · [Region](/docs/api/region.md) · [Shared View runtime](/docs/api/shared/view-bindings.md)
A View owns one fixed DOM element, renders supplied data, and can compose child Views through named [Regions](/docs/api/region.md). Use it for an individual control or a layout. [CollectionView](/docs/api/collection-view.md) manages a set of children instead.
Import `View` from `marionette`. Shared rendering, DOM, UI, data bindings, and child forwarding are defined in [View runtime](/docs/api/shared/view-bindings.md). Inherited [common methods](/docs/api/shared/common.md), [events](/docs/api/shared/events.md), and [state](/docs/api/shared/state.md) are part of this API.
## Local interaction and feature coordination
A View can own local input state and save an edit to its model when the data layer supplies that operation. Calling `this.model.save(...)` from an input handler can be appropriate. With `@mnjs/data`, a local edit can instead call the application's API layer and update the model with `set`; the package supplies no persistence method. Having other Views observe the same model does not make that handler responsible for their presentation; each consumer handles its own updates.
Use an [Application](/docs/api/application.md) to coordinate feature readiness and shared workflow decisions. For these actions, the View emits intent; the Application decides what work to start and where its result belongs. Starting a feature's initial load in `onRender` ties readiness to rendering and can repeat the request on rerender. Put that readiness in [Application preparation](/docs/api/application.md#prepare-before-showing-ui).
For shared records or selection that change over time, receive an observable source and use [model/collection bindings](/docs/api/shared/view-bindings.md#data-bindings) or [state bindings](/docs/api/shared/state.md). A replacement View reads current data and subscribes for later changes. Its owner can then replace it without coordinating each presentation update.
## Construction and options
`new View(options?)` creates the element, delegates DOM events, prepares state access and Behaviors, registers Regions, and calls `initialize(options)`. It does not evaluate the template. `View.extend(prototypeProperties?, staticProperties?)` returns a subclass; see [class extension](/docs/api/shared/common.md).
Options below can be declared on the class or supplied at construction. The table identifies which declarations accept resolver functions; those resolvers run with the View as `this`. The renderer controls template invocation. Model, collection, and borrowed state values are used as sources, not invoked as resolvers.
| Option | Accepted value and default |
| --- | --- |
| `el` | An `Element` or function returning one. Otherwise Marionette creates a root from `tagName`. Pass an actual element, not a selector string. |
| `tagName` | String or function returning one; default `'div'`. Used only when creating a root. |
| `id`, `className` | String, `null`, or function returning a string, `null`, or `undefined`. Applied when creating a root; see [attributes](/docs/api/shared/view-bindings.md#root-attributes). |
| `attributes` | Attribute map or function returning one. `id` and `className`, when declared, take precedence over its `id` and `class` entries. |
| `template` | A template understood by the configured renderer, or `false` to preserve existing contents. The default renderer expects a function. No default template is supplied. |
| `templateContext` | Object or function returning an object, merged over serialized data on each render. |
| `model`, `collection` | Sources understood by the configured DataApi. A View serializes the model when both are present. Supplying either does not enable automatic rendering on change. |
| `ui` | Map of names to selectors, or function returning that map. See [UI bindings](/docs/api/shared/view-bindings.md#ui-bindings). |
| `events`, `triggers` | DOM event maps or functions returning them. See [DOM events](/docs/api/shared/view-bindings.md#dom-events). |
| `modelEvents`, `collectionEvents` | Source event maps or functions returning them. See [data bindings](/docs/api/shared/view-bindings.md#data-bindings). |
| `state`, `stateEvents` | Borrowed state and its event bindings. `createState(options)` can supply owned state instead. See [state](/docs/api/shared/state.md). |
| `regions` | Map of names to Region definitions, or function returning that map; default empty. Definitions are described below. |
| `regionClass` | Default Region constructor for this View's definitions; default `Region` from its Marionette runtime. Individual definitions may override it. |
| `childViewEvents`, `childViewTriggers`, `childViewEventPrefix` | Parent handlers, event remapping, and optional prefix; see [child forwarding](/docs/api/shared/view-bindings.md#child-events). Prefix forwarding defaults to `false`. |
| `behaviors` | Array or object of Behavior definitions, or function returning either. See [Behavior composition](/docs/api/shared/view-bindings.md#behavior-composition). |
`preinitialize(options)` runs before the element, Behaviors, and Regions are initialized; `cid`, `options`, and recognized constructor declarations are already available. `initialize(options)` runs after those resources exist and before state/entity event bindings become active. Both hooks are no-ops by default. Constructor values for root-element configuration, model, collection, and DOM events take precedence over assignments made in `preinitialize`.
`options` contains merged class and constructor options. Custom options remain accessible through `getOption(name)`; they are not automatically assigned as instance properties. Declare `cidPrefix` on the class to change the default `'mnv'`; `cid` is the generated instance identifier.
## Existing elements
Construction adopts the supplied element without replacing its contents or applying root attributes. An element with child nodes starts with `isRendered() === true`; an element already inside its document starts attached. Construction does not emit render or attach lifecycle events. UI bindings are available immediately when existing contents are detected.
Use `template: false` to preserve existing HTML. `render()` then returns the View without rendering, resetting Regions, or emitting render events. Destroying the View still removes its element and destroys managed children. The root stays fixed for the View's lifetime; construct a new View to use a different root.
This standalone TypeScript example adopts markup and adds a child without rendering the parent:
```ts
import { View, type ViewConfiguration } from 'marionette';
const el = document.createElement('section');
el.innerHTML = '
Preview
';
document.body.append(el);
const options: ViewConfiguration = {
el,
template: false,
regions: { content: '.content' },
};
const page = new View(options);
const message = document.createElement('p');
message.textContent = 'Ready';
const child = new View({ el: message, template: false });
page.showChildView('content', child);
page.destroy(); // Removes the adopted section and destroys the child.
```
## Rendering and status
| Method or property | Contract |
| --- | --- |
| `el` | The resolved, fixed root `Element`. |
| `render()` → `this` | Resolves `getTemplate()`, emits `before:render`, resets existing Regions when already rendered, renders into the root, binds UI, sets rendered state, and emits `render`. Reset destroys current children but keeps Region registrations. Destroyed Views and `template: false` do not render. |
| `isRendered()` → boolean | Whether rendered contents have been established or were present at construction. Becomes false on destruction. |
| `isAttached()` → boolean | Attachment state maintained by Marionette's lifecycle. Direct DOM moves do not update it automatically. |
| `isDestroyed()` → boolean | Whether destruction has reached its terminal state. |
| `destroy(options?)` → `this` | Removes the root, destroys Regions and their current children, releases bindings/Behaviors/owned state, emits destruction notifications, and releases incoming and outgoing event subscriptions. Repeated calls do nothing. Model and collection sources are not destroyed by the View. |
For template selection, serialization, `renderAttributes`, and renderer customization, see [rendering contracts](/docs/api/shared/view-bindings.md#templates-and-data). `render()` does not refresh root attributes or automatically redelegate changed DOM event maps.
## Named Regions
A `regions` map accepts a selector string, Region constructor, Region instance, or options object such as `{ el: '.content', replaceElement: true }`. An options object can include `regionClass`. Supply options as own enumerable properties; inherited and non-enumerable option properties are not copied. Use a Region subclass for prototype defaults. String selectors resolve inside the View's root by default; `@ui.name` is accepted in selectors and the `el` field. Full Region options are in [Region](/docs/api/region.md). Registration copies the definition map and options objects before resolving UI selectors, so shared declarations remain unchanged and each View uses its own UI map. Supplied Region instances and constructors retain their identity.
Regions are created before `initialize`; their elements can resolve later when content exists. A Region has one owner/name and must belong to the same Marionette runtime. Names must be nonempty strings. Re-registering the same instance under its existing name is harmless; a different definition under an occupied name throws. Remove the old Region before replacing its definition.
| Method | Result and effects |
| --- | --- |
| `addRegion(name, definition)` | Returns the registered Region. Does not render the parent. |
| `addRegions(definitions?)` | Returns a map of the added Regions, or `undefined` for no definitions. Does not render the parent. |
| `hasRegion(name)` | Returns whether that name is registered; no rendering. |
| `getRegion(name)` | Returns the Region or `undefined`; no rendering or element resolution. |
| `getRegions()` | Returns a new map containing current Region instances; no rendering. Changing this map does not change registrations. |
| `showChildView(name, view, options?)` | Renders the parent if needed, shows the child through the named Region, and returns the supplied child. Accepts Region `ShowOptions`. A skipped show with `allowMissingEl` still returns the child but leaves it unowned; the caller must show it elsewhere or destroy it. |
| `getChildView(name)` | Renders the parent if needed, then returns the Region's current child or `undefined`. |
| `detachChildView(name)` | Renders the parent if needed, detaches and releases the current child, and returns it or `undefined`. The child remains alive and becomes the caller's responsibility. |
| `emptyRegions()` | Renders the parent if needed, empties each Region, and returns a map of them. Keeps Region registrations. |
| `removeRegion(name)` | Destroys and unregisters the Region, including its current child; returns the destroyed Region. |
| `removeRegions()` | Destroys/unregisters every Region; returns a map of the destroyed Regions. |
The child operations and `removeRegion` throw for a missing Region. Region registration/removal emits no View `add:region` or `remove:region` events; observe the Region's lifecycle when needed. Rendering an existing layout resets Regions and destroys their children, so render a smaller child when the surrounding composition should remain alive. An allowed missing-element lookup leaves the Region usable for this reset and for parent destruction.
## Lifecycle hooks and events
Each event below uses `triggerMethod`: the corresponding hook runs first, then event subscribers receive the same arguments. The shared monitor can emit nested child/DOM notifications while an event is being delivered; the phases below describe lifecycle order rather than the ordering of every subscriber. See [event dispatch](/docs/api/shared/events.md).
| Event | Hook | Arguments and timing |
| --- | --- | --- |
| `before:render` | `onBeforeRender` | `(view)` before existing Regions reset or template output changes. |
| `render` | `onRender` | `(view)` after output, UI binding, and rendered state are ready. |
| `before:attach` | `onBeforeAttach` | `(view)` before an owning Region/CollectionView inserts the root into the document. |
| `attach` | `onAttach` | `(view)` after insertion and attached state update. |
| `dom:refresh` | `onDomRefresh` | `(view)` when an attached View renders or a rendered View attaches. |
| `before:detach` | `onBeforeDetach` | `(view)` before removal of an attached root. |
| `dom:remove` | `onDomRemove` | `(view)` during `before:detach` or `before:render` when currently attached and rendered. |
| `detach` | `onDetach` | `(view)` after removal and attached state update. |
| `before:destroy` | `onBeforeDestroy` | `(view, options)` while `isDestroyed()` is false, before root/child cleanup. |
| `destroy` | `onDestroy` | `(view, options)` after root/child cleanup and destroyed state update; event subscriptions are cleared afterward. |
For a newly constructed View with a rendering template shown in an attached Region, the usual successful path is:
```text
constructed → render → attach → dom:refresh
│
├── before:render → dom:remove → render → dom:refresh
└── detach → alive, reusable → attach → dom:refresh
live View → before:destroy → detach if attached → child cleanup → destroy
```
Existing markup can start rendered or attached without emitting those construction-time events. With `template: false`, `View.render()` is a no-op and emits no render events. For an initially empty View, `Region.show()` still marks it rendered, so attachment can emit `dom:refresh`. Detachment keeps the View alive; destruction is terminal.
Showing an initially unrendered detached View in an attached Region normally proceeds through render, then attach, then DOM refresh. A direct destroy normally proceeds through `before:destroy`, detach phases if attached, child destruction, and `destroy`. Managed children receive attach/detach propagation; during parent destruction they are destroyed after the parent root is detached. A CollectionView owner may detach a child before destroying it, so its child ordering differs; see [Region replacement](/docs/api/region.md#replacing-a-collectionview).
Lifecycle callbacks are synchronous. A thrown callback interrupts the operation; these phases describe successful completion, not rollback guarantees.
Set `monitorViewEvents: false` on the class to disable descendant attachment propagation and generated `dom:refresh`/`dom:remove` notifications. This is a class property, not a recognized constructor option. Ordinary application code should retain monitoring. `monitorViewEvents(view)` is the exported installer used by Marionette; it returns `undefined` and installs handlers only once, unless monitoring is disabled before installation. Native View and CollectionView construction installs it automatically. A custom integration must satisfy `ViewLifecycle`, including event methods, rendered/attached flags and immediate-child traversal. The installer propagates existing lifecycle events; it does not watch external DOM changes.
### Compose children after rendering
Use `onBeforeRender` or a `before:render` listener to prepare template inputs or inspect the existing UI. Avoid operations that render an unrendered parent: `showChildView()`, `getChildView()`, `detachChildView()`, and `emptyRegions()` each reenter the same notification. An unconditional callback recurses; a one-time callback can complete an inner render. If it shows a child, the outer render then resets the Region and destroys that child. Showing children here is also unsafe on later renders, because existing Region children are still reset after `before:render`. `getRegion()` itself is a pure lookup and does not render.
Compose children in `onRender` or a `render` listener, after the parent's template and Regions are ready:
```js
import { View } from 'marionette';
const Page = View.extend({
template: () => '',
regions: { content: '.content' },
onRender() {
this.showChildView('content', new View({ template: () => 'Ready' }));
},
});
const page = new Page().render();
```
Each full parent render destroys the previous child and composes a new one; parent destruction destroys the current child. Do not call the parent's `render()` again from that completion callback. For `template: false`, no render notification occurs: compose explicitly after establishing the existing markup, as in [existing elements](#existing-elements). CollectionView has a corresponding [manual-child boundary](/docs/api/collection-view.md#compose-manual-children-after-rendering).
## Configuration and inherited API
The class methods `setRenderer`, `setDomApi`, `setDataApi`, `setStateApi`, and `setEventDelegator` return the receiving class. Their [configuration contracts](/docs/api/shared/view-bindings.md#class-configuration) apply to subclasses as well. Configure before constructing Views.
The following methods are shared with other classes; their canonical definitions are linked rather than repeated:
- [Common](/docs/api/shared/common.md): `getOption`, `mergeOptions`, `normalizeMethods`, `bindEvents`, `unbindEvents`, `bindRequests`, `unbindRequests`, `extend` and constructor inheritance.
- [Events](/docs/api/shared/events.md): `on`, `once`, `off`, `trigger`, `triggerMethod`, `listenTo`, `listenToOnce`, `stopListening`.
- [State](/docs/api/shared/state.md): `createState`, `getState`, `state`, `stateEvents`, and the `State` provider.
- [View runtime](/docs/api/shared/view-bindings.md): `$`, `getUI`, UI normalization/binding, DOM/entity delegation, template serialization, `attachElContent`, root attributes, Behaviors, and child events.
## TypeScript
`ViewConfiguration` describes recognized options. `ViewInstance` describes instances; `Query` defaults to `ArrayLike` and follows the DOM provider. `ViewConstructor` describes constructors and preserves properties, arguments, state, static members, and fluent returns through `extend`. Normal application code can use inferred subclasses instead of spelling out these generics.
Region definitions use exported `RegionDefinition` and `RegionClass`; child methods accept `SupportedView` and `ShowOptions`. These are structural contracts, not a promise that an arbitrary object with `render()` is a fully managed child. DOM maps, UI maps, and renderer types are listed in [View runtime](/docs/api/shared/view-bindings.md#types).
[Canonical source](/docs/markdown/docs/api/view.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/collection-view.md
Canonical URL: https://marionettejs.com/docs/api/collection-view/
Markdown URL: https://marionettejs.com/docs/api/collection-view.md
Reading SHA-256: be175dc9d8e98bf327ce9094f07f28fa4906560722364fd1028ec76c119b74b8
# CollectionView
[API index](/docs/api.md) · [View](/docs/api/view.md) · [Shared View runtime](/docs/api/shared/view-bindings.md)
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](/docs/integrations/setup.md#observable-data-and-api-access).
```ts
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](/docs/api/shared/view-bindings.md), [state](/docs/api/shared/state.md), and [View construction](/docs/api/view.md#construction-and-options). It has no named-Region methods or `regions`/`regionClass` options. Custom options use [common option methods](/docs/api/shared/common.md#options-and-initialization).
| CollectionView option | Value and default |
| --- | --- |
| `collection` | Source understood by the configured DataApi. The default accepts a plain array; the native DataApi accepts a `Collection`. May be omitted for manually managed children. |
| `childView` | View/CollectionView class, or `function(model)` returning a class. Required when collection models need children; no default. |
| `childViewOptions` | Options object or `function(model)` returning one. Default construction uses `{ model, ...childViewOptions }`, so an explicit `model` option overrides the source model. Normally retain the supplied model. |
| `childViewContainer` | Descendant selector or function returning one; defaults to the root. Resolved after template rendering. A selector with no match throws `MN0013`. |
| `emptyView` | View/CollectionView class, or function returning a class, `null`, `undefined`, or `false`. Defaults to no empty View. |
| `emptyViewOptions` | Options object or function called without arguments. Falls back to `childViewOptions`, also called without a model. |
| `RegionClass` | Region constructor for the list-owned empty Region; defaults to `Region`. A supplied constructor option overrides the prototype value; omission or `undefined` preserves it. |
| `sortWithCollection` | Boolean, default `true`. Follows source reorder notifications and uses collection order when no custom comparator is selected. |
| `viewComparator` | Model attribute name, one-argument key function, or two-argument comparison function; default is collection order. `false` disables the comparator. See [sorting](#sorting). |
| `viewFilter` | Model attribute name, attribute-value object, or predicate; default no filter. See [filtering](#filtering). |
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` is copied before `initialize`, which can still override it before the empty Region is created. Configure it through a constructor option, prototype property, or `initialize`; native subclass fields are initialized after the empty Region has already been created. This hook affects only empty presentation, not ordinary rows or their named Regions.
## Rendering and collection updates
| Operation | Child identity and presentation |
| --- | --- |
| `render()` → `this` | Destroys all managed rows, creates children from the current collection, renders an optional template, resolves the container, then sorts, filters and presents children. Emits render lifecycle notifications. A destroyed list does nothing. |
| Observable addition/removal | Creates added rows and destroys removed rows; retains unaffected child instances. Reapplies sorting/filtering and presentation. |
| Source reorder | Sorts/presents existing rows when `sortWithCollection` is true. Does not recreate surviving rows. |
| Source reset | Destroys/rebuilds rows from the new snapshot, even if the same Models or keys occur again. Does not rerender the list's own template. |
| Adapter update of the same model object | Retains its child, marks it for rendering, then sorts/filters. A hidden child renders when next presented. |
| Adapter replacement with a different object under the same key | Creates a replacement child and destroys the previous child. Stable keys do not imply rebinding an existing View to a different model. |
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](/docs/integrations/setup.md#configure-once).
`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.
| Method | Contract |
| --- | --- |
| `getComparator()` | Returns the explicit truthy comparator, the source-order comparator, or `false`. Override for a computed comparator. |
| `sort()` → `this` | Sorts managed children, then filters and renders the resulting presentation. Already rendered survivors keep their elements. |
| `setComparator(value, options?)` → `this` | Stores the value and calls `sort()` if its identity changed, unless `preventRender` is true. |
| `removeComparator(options?)` → `this` | Clears the explicit comparator. With a collection and `sortWithCollection: true`, this restores the source-order comparator. |
`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.
| Filter value | Meaning |
| --- | --- |
| `function(view, index, children)` | Keep the View for a truthy result. The index and array describe all managed children in current sorted order. |
| `'available'` | Keep Views whose model has a truthy `available` attribute according to the DataApi. |
| `{ available: true }` | Keep Views whose model has every listed attribute with the matching value, using strict equality. |
| Falsy value | No filter. |
| Method | Contract |
| --- | --- |
| `getFilter()` | Returns `viewFilter`; override for a computed filter. |
| `filter()` → `this` | Recomputes presentation and renders/attaches included children, without sorting first. Detaches excluded rows without destroying them. |
| `setFilter(value, options?)` → `this` | Stores the value and filters immediately when its identity changed, unless `preventRender` is true. |
| `removeFilter(options?)` → `this` | Clears the filter using the same setter rules. |
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](/docs/api/shared/view-bindings.md#child-events) 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.
| Member | Result |
| --- | --- |
| `length`, `isEmpty()` | Presented count and whether it is zero. |
| `findByModel(model)`, `findByKey(key)` | View indexed by `Data.key(model)` or an explicit key, or `undefined`. Model lookup is by provider key, not necessarily object identity. |
| `findByCid(cid)`, `findByIndex(index)` | View by its own `cid` or presentation index, or `undefined`. |
| `findIndexByView(view)` | Index, or `-1` if absent. |
| `hasView(view)`, `contains(view)` | Whether that exact instance is present. |
| `toArray()`, `[Symbol.iterator]()` | A copied array, or iteration over the presentation. |
| `each(callback, context?)` | Calls `(view, index)` for each child; returns the container. |
| `map(callback, context?)`, `pluck(property)` | Array of callback results or View property values. `pluck` reads the View, not its model. |
| `find`, `filter`, `reject`, `every`, `some`, `partition` | Accept `(view, index)` predicates and optional context. Return the first match, matching array, rejected array, boolean, boolean, or `[matching, rejected]`. |
| `reduce(callback, initialValue?, context?)` | Reduces using `(accumulator, view, index)`. Omitting the initial value uses the first View; an empty container then throws. |
| `first(count?)`, `last(count?)` | One View (or `undefined`) when count is omitted; an array when supplied. |
| `initial(count = 1)`, `rest(count = 1)` | Array excluding the last or first count Views. Counts must be nonnegative integers. |
| `without(...views)` | Copied array excluding those instances. |
| `invoke(methodName, ...args)` | Calls each child's named method with that child as `this`; returns its results. |
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.
| Method | Ownership and return |
| --- | --- |
| `addChildView(view, index?, options?)` | Adopts and returns the supplied View, rendering the parent first if needed. A View must be unowned. Without a numeric index, sorts/filters; a numeric index inserts directly and skips those steps for this addition. Also accepts an options object as the second argument. |
| `detachChildView(view)` | Removes a managed View from storage and DOM, releases ownership/forwarding, and returns it alive. The caller must give it a new owner or destroy it. |
| `removeChildView(view)` | Destroys a managed View, removes its entry, and returns it. A missing/falsy or unmanaged View is returned unchanged. |
| `swapChildViews(first, second)` → `this` | Swaps two managed children without changing the collection. Both must belong to this list (`MN0015` otherwise). If only one is currently presented, reapplies filtering. A later sort can override the swap. |
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](#sorting), 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](/docs/api/view.md#lifecycle-hooks-and-events). `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.
| Event pair | Hooks | Arguments and boundary |
| --- | --- | --- |
| `before:render`, `render` | `onBeforeRender`, `onRender` | `(list)` around full rendering. The final event sees `isRendered() === true`. |
| `before:add:child`, `add:child` | `onBeforeAddChild`, `onAddChild` | `(list, child)` around adoption/indexing, before presentation by this list. |
| `before:remove:child`, `remove:child` | `onBeforeRemoveChild`, `onRemoveChild` | `(list, child)` around removal from child storage. These are not a universal before/after boundary for child destruction. |
| `before:sort`, `sort` | `onBeforeSort`, `onSort` | `(list)` around sorting when there are managed children and an active comparator. |
| `before:filter`, `filter` | `onBeforeFilter`, `onFilter` | Before: `(list)`. After: `(list, included, excluded)`. Only emitted with managed children and an active filter. |
| `before:render:children`, `render:children` | `onBeforeRenderChildren`, `onRenderChildren` | `(list, presentedChildren)` around child/empty presentation. The array contains row Views, not the empty View; it is live storage, so copy it if retaining a snapshot. |
| `before:destroy:children`, `destroy:children` | `onBeforeDestroyChildren`, `onDestroyChildren` | `(list)` around bulk managed-row destruction, when rows exist. Bulk destruction does not emit individual remove-child events. |
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](/docs/api/region.md#replacing-a-collectionview) explains the outer owner's teardown order. Callbacks are synchronous; a thrown callback can interrupt an operation.
| Extension point | Default behavior |
| --- | --- |
| `buildChildView(model, ChildClass, options?)` | Constructs `new ChildClass({ model, ...options })` and returns it. Does not itself adopt/render the child. |
| `attachHtml(elements, container)` | Appends the supplied Element/DocumentFragment to the child container; no defined return value. |
| `detachHtml(view)` | Detaches the child's element through the DOM provider; no defined return value. |
| `getComparator()`, `getFilter()`, `isEmpty()` | Can be overridden to compute ordering, filtering, or empty presentation. |
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](/docs/api/shared/view-bindings.md). Class setters `setRenderer`, `setDomApi`, `setDataApi`, `setStateApi`, and `setEventDelegator` use its [configuration contracts](/docs/api/shared/view-bindings.md#class-configuration). Inherited object APIs are in [common methods](/docs/api/shared/common.md), [events](/docs/api/shared/events.md), and [state](/docs/api/shared/state.md).
### Compose manual children after rendering
Do not call `addChildView()` from `onBeforeRender` or a `before:render` listener. It renders an unrendered list before adopting the child, so that callback reenters itself. Even with a one-time callback, the outer render destroys the newly adopted child. On a later full render, children added during `before:render` are also included in the following old-row destruction. `{ preventRender: true }` does not avoid either problem: it defers the child's presentation, not the parent's initial render or adoption.
Prepare collection inputs before rendering. For manual children, compose in `onRender` or a `render` listener, after the full-render child destruction and container setup:
```js
import { CollectionView, View } from 'marionette';
const ManualList = CollectionView.extend({
onRender() {
this.addChildView(new View({ template: () => 'Ready' }));
},
});
const list = new ManualList().render();
```
This creates a fresh child after each full render; the next full render, a collection reset, or parent destruction destroys it. A collection reset does not emit `render`, so a manual child composed in `onRender` is not recreated afterward. Do not invoke another full parent render from the completion callback. For collection-backed rows, configure `collection` and `childView` instead of manually recreating those rows. See the related [View composition boundary](/docs/api/view.md#compose-children-after-rendering).
## 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.
[Canonical source](/docs/markdown/docs/api/collection-view.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/region.md
Canonical URL: https://marionettejs.com/docs/api/region/
Markdown URL: https://marionettejs.com/docs/api/region.md
Reading SHA-256: 9a02d1332b7bbba89b889275946a04462eca747485360f63a5412105c5b0b4ba
# Region
[API index](/docs/api.md) · [View](/docs/api/view.md) · [Shared events](/docs/api/shared/events.md)
A Region owns the placement and lifetime of one View or CollectionView. Showing another View destroys the current one. Detaching releases it for reuse. A View can own named Regions for composition; an Application can use a Region to display its root View.
## Construction and options
`new Region(options?)` configures the Region and calls `initialize(options)`. It does not resolve a selector, render a View, or change the DOM. Supply `el` before showing content. Unlike View, Region has no `preinitialize` hook.
| Option / class property | Contract |
| --- | --- |
| `el` | A native `Element` or selector string. A selector is resolved when an operation needs the element, then the resulting element is cached. A detached element is valid. |
| `parentEl` | An `Element`, `Document`, or function returning either; scopes selector lookup to descendants of that node. Defaults to `document` when absent or the function returns no node. |
| `allowMissingEl` | Boolean or function returning a boolean; false by default. Allows a supplied selector to have no match. It does not allow an omitted `el`. |
| `replaceElement` | Boolean or function returning a boolean; false by default. Replaces the Region's placeholder with the shown View's root instead of inserting the root inside it. |
Functions run with the Region as `this`. Constructor options take precedence over class defaults. Use [common option methods](/docs/api/shared/common.md) for custom options.
This example moves a live View between two Regions without rendering it again:
```ts
import { Region, View, type RegionOptions } from 'marionette';
const options: RegionOptions = { el: document.createElement('section') };
const first = new Region(options);
const second = new Region({ el: document.createElement('aside') });
const content = document.createElement('p');
content.textContent = 'Account settings';
const view = new View({ el: content, template: false });
first.show(view);
const retained = first.detachView();
if (retained) second.show(retained);
first.destroy();
second.destroy(); // Destroys the View now owned by this Region.
```
See [View](/docs/api/view.md) for named Region definitions, including selector, constructor, instance, and options-object forms.
## Showing a View
### `show(view, options?)`
Accepts a View or CollectionView instance and returns the Region. It returns `undefined` when an unmatched selector is allowed by `allowMissingEl`. Both `allowMissingEl` and `replaceElement` can be overridden for this call with boolean values in `options`.
On a successful show, the Region:
1. Resolves its element and checks the incoming View.
2. Emits `before:show`, empties the outgoing View, and takes ownership of the incoming View.
3. Renders the incoming View if it is not already rendered.
4. Inserts its element, emitting attach notifications if the Region is in the document and monitoring is enabled.
5. Emits `show`.
Showing the current View again does not rerender it or repeat show events. A destroyed View cannot be shown. A View already owned by an Application, Region, or CollectionView must first be detached from that owner. A View adopting existing attached markup does not receive another attach notification just because a Region shows it.
An unmatched selector produces `MN0005` unless allowed; no configured element produces `MN0004`. A destroyed incoming View produces `MN0007`, and an already owned View produces `MN0003`. `allowMissingEl` skips that show attempt without taking ownership of the View. A later explicit operation retries an unresolved selector; the Region does not watch for DOM changes.
An unmatched lookup clears the cached `el` but retains the original selector. A later `show()` retries that selector and applies its missing-element options. With no current View, `empty()` also needs to resolve the element; `reset()` and `destroy()` use that emptying path. When a current View exists, cleanup releases it using the resolved element without another selector lookup. A skipped show leaves the Region usable for cleanup or a later explicit show.
Operations are synchronous. Lifecycle callbacks that throw interrupt the operation; Region does not roll back partially completed work.
## Empty, detach, reset, and destroy
| Method | Child and DOM behavior | Return |
| --- | --- | --- |
| `empty(options?)` | Destroys the current View and releases ownership. With no View, clears the Region element's contents. Keeps the Region usable and its resolved element cached. | Region |
| `detachView()` | Removes the current View from the DOM, releases ownership and parent event forwarding, and keeps the View alive. Emits the Region's empty events. | Detached View, or `undefined` |
| `reset(options?)` | Empties, then restores the original `el` reference. An initial selector is queried again on the next operation; an initial Element is reused. Requires emptying to succeed under the supplied missing-element options. | Region |
| `destroy(options?)` | Runs destroy notifications around reset/empty cleanup, unlinks a named View-owned Region, and releases its incoming and outgoing event subscriptions. | Region |
`empty()`, `reset()`, and `destroy()` use `ShowOptions` for element checking. `empty()` without options tolerates an unmatched selector when there is no child; supplying `allowMissingEl: false` makes that check strict. These options are not passed to the outgoing View's `destroy()`.
Keep a reference to a detached View and either give it a new owner or destroy it when finished. Detachment preserves the View's own listeners and state; its [View owner](/docs/api/view.md) stops forwarding its events. See [event cleanup](/docs/api/shared/events.md#cleanup) for native destruction and subscription ownership.
Repeated destruction is a no-op. Once destruction begins, `show()` does nothing and returns the Region; `detachView()` returns `undefined`. After destruction completes, `empty()` and `reset()` also do nothing and return the Region. Destruction leaves the Region's own element in place, with its owned View removed.
### Replacing the Region element
With `replaceElement: true`, the Region retains its original placeholder as `region.el` while the View's element occupies that position in the DOM. Emptying or detaching restores the placeholder. Replacement also works per call with `show(view, { replaceElement: true })`.
Use a placeholder that has a parent node: replacement exchanges nodes in that parent. `isReplaced()` reports whether the Region is currently using replacement mode. The placeholder is restored before the outgoing View is destroyed, which changes detach ordering as described below.
## Properties and queries
| Member | Result / purpose |
| --- | --- |
| `currentView` | The owned View or CollectionView, or `undefined`. Read this property; use lifecycle methods to change ownership. |
| `hasView()` | Boolean indicating whether `currentView` exists. Does not render or inspect the DOM. |
| `getOwner()` | The owning View, including a CollectionView for its empty-view Region, or `undefined`. This reports View registration; an Application's root Region does not report the Application here. |
| `getName()` | Name registered on the owning View, or `undefined` for standalone and unnamed Regions. |
| `isSwappingView()` | True during replacement, including `before:show`, empty, and `show` callbacks. False after a successful show finishes. |
| `isReplaced()` | Whether the placeholder is currently replaced by the View's root. |
| `isDestroyed()` | False before destruction completes; true before `destroy` notifications run. |
| `el` | Initial selector/Element, resolved Element after lookup, or `undefined` after an unmatched lookup. A successful `reset()` restores the initial reference. An unresolved selector is retried on the next element-dependent operation. |
| `options` | Merged constructor options. See [common options](/docs/api/shared/common.md). |
| `cid`, `cidPrefix` | Unique instance identifier and its class-level prefix (`'mnr'` by default). |
| `Dom` | DOM provider used for lookup, insertion, detachment, and replacement. Configure through `setDomApi`. |
## Lifecycle events and hooks
Each event uses `triggerMethod`: its matching hook runs first, then registered event listeners receive the same arguments. See [shared events](/docs/api/shared/events.md). Hook methods are supplied on a subclass, for example `onBeforeShow(region, view, options)`.
| Region event | Hook | Arguments |
| --- | --- | --- |
| `before:show` | `onBeforeShow` | `(region, incomingView, options)` |
| `show` | `onShow` | `(region, incomingView, options)` |
| `before:empty` | `onBeforeEmpty` | `(region, outgoingView)` |
| `empty` | `onEmpty` | `(region, outgoingView)` |
| `before:destroy` | `onBeforeDestroy` | `(region, options)` |
| `destroy` | `onDestroy` | `(region, options)` |
`options` is the object passed to `show()` or `destroy()`, or `undefined`. Empty events have no options argument. The current View is still present at `before:empty` and released by `empty`. Emptying a Region that has no View clears content without emitting empty events. When a child destroys itself, the Region releases it and emits empty events too.
For an occupied Region, `destroy()` runs: Region `before:destroy` → Region `before:empty` → child teardown → Region `empty` → Region `destroy`. The last notification observes `isDestroyed() === true` and cleared View-owner/name references.
### Replacing a CollectionView
Replacement follows the same Region sequence: `before:show` → `before:empty` → outgoing child teardown → `empty` → incoming render/attach → `show`. The outgoing CollectionView destroys its managed children during its teardown; its `before:destroy:children` and `destroy:children` notifications belong to the CollectionView.
Normally the outgoing View receives `before:destroy` before detach. With `replaceElement`, restoring the placeholder detaches it before `before:destroy`. An already rendered incoming View skips rendering. Descendant notifications follow the [View lifecycle](/docs/api/view.md#lifecycle-hooks-and-events); monitoring and attachment state determine which detach/attach notifications occur.
## Customization and inherited methods
Use `Region.extend(prototypeProperties?, staticProperties?)` or subclass Region. `initialize(options)` is the constructor hook; the default does nothing. For custom constructors and `Region.call` / `Region.apply`, see [class construction](/docs/api/shared/common.md).
| Extension point | Default contract |
| --- | --- |
| `getEl(selector)` | Returns the first matching native Element under `parentEl` or `document`, or `undefined`. Does not include the parent node itself in selector matching. |
| `attachHtml(view)` | Appends `view.el` inside `region.el`. Used for ordinary insertion; replacement uses the DOM provider's `replaceEl` instead. Returns `undefined`. |
| `detachHtml()` | Removes the contents of `region.el`. Returns `undefined`. Used for ordinary detachment and clearing unmanaged HTML. |
| `removeView(view)` | Calls `destroyView(view)` when emptying a live owned View. Returns `undefined`. Override only when intentionally replacing the default teardown policy. |
| `destroyView(view)` | Destroys a View unless it is already destroyed, respecting the owner's detach-monitoring policy. Returns that View. |
These methods are called by lifecycle operations. Calling DOM hooks directly does not perform the ownership bookkeeping of `show`, `empty`, or `detachView`. If overriding a lifecycle method, delegate to `Region.prototype` to retain the standard cleanup and event contract.
`Region.setDomApi(partialApi)` merges DOM methods into that class's provider and returns the class. Call it on a Region subclass to scope the override to that subclass. See [runtime configuration](/docs/api/runtime.md#choose-a-configuration-scope) for setter scope and [DomApi](/docs/api/providers/dom.md#domapi) for the provider-authoring contract.
Region inherits [common utilities](/docs/api/shared/common.md): `getOption`, `mergeOptions`, `normalizeMethods`, `bindEvents`, `unbindEvents`, `bindRequests`, and `unbindRequests`. It also inherits [event methods](/docs/api/shared/events.md): `on`, `once`, `off`, `trigger`, `triggerMethod`, `listenTo`, `listenToOnce`, and `stopListening`. Region has no state, model, collection, renderer, or Radio-channel initialization of its own.
## TypeScript types
All of these types are exported from `marionette`:
| Type | Use |
| --- | --- |
| `RegionOptions` | Constructor options from the first table. |
| `ShowOptions` | Per-operation boolean options and extra application-defined keys. |
| `RegionInstance` | Region instance contract, with its constructor-options type. |
| `RegionConstructor` | Constructor, subclass properties, constructor arguments, and static members. `extend` carries these into derived classes. |
| `RegionDefinition`, `RegionClass` | Accepted named Region definition forms and the constructor type used by View/Application configuration. |
| `RegionOwner` | Structural type returned by `getOwner()`. Actual owners are Views; internal forwarding members on this type support the framework's ownership contract. |
| `SupportedView`, `ViewLifecycle` | Contracts used by Region and other composition owners. Native View and CollectionView satisfy them, including lifecycle state and child traversal. `SupportedView` adds `render()` and `destroy()`. |
`show()` is typed as the Region or `undefined`; `detachView()` returns `SupportedView | undefined`. `empty()`, `reset()`, and `destroy()` preserve the derived instance type for chaining. Private lifecycle fields in `ViewLifecycle` are framework integration details, not fields to mutate in application code.
[Canonical source](/docs/markdown/docs/api/region.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/behavior.md
Canonical URL: https://marionettejs.com/docs/api/behavior/
Markdown URL: https://marionettejs.com/docs/api/behavior.md
Reading SHA-256: 122379e902f0374a3f7128d3d139c2552f1142d0e82348a82e77fe36dcaa117c
# Behavior
[API index](/docs/api.md) · [View](/docs/api/view.md) · [CollectionView](/docs/api/collection-view.md)
Behavior adds reusable local interaction to a View or CollectionView. It shares the host's element and lifetime. Use a View method for one-off interaction; extract a Behavior when multiple hosts need the same behavior. Feature requests, navigation and application composition belong with their owner, not in a DOM helper.
## Reuse a local interaction
This Behavior turns Escape into a host event. The owner of the host decides how to dismiss it.
```ts
import { Behavior, View } from 'marionette';
import LitDomApi from '@mnjs/adapters/dom/lit-html';
import { html } from 'lit-html';
const DismissOnEscape = Behavior.extend({
events: { keydown: 'handleKeydown' },
handleKeydown(event: KeyboardEvent) {
if (event.key === 'Escape') {
this.view.triggerMethod('dismiss', this.view);
}
},
});
const SearchPanel = View.extend({
behaviors: [DismissOnEscape],
template: () => html``,
}).setDomApi(LitDomApi);
const panel = new SearchPanel();
panel.render();
```
The host owns the Behavior. Destroying the host removes the Behavior's DOM and data subscriptions too. Rendering the host again retains the Behavior instance.
## Declare and construct
Declare Behaviors through the host's `behaviors` option: an array or named map of Behavior constructors or `{ behaviorClass: SomeBehavior, ...options }` definitions. A function can return that array/map. See [composition](/docs/api/shared/view-bindings.md#behavior-composition). The host constructs and manages these instances; declaration names are not a public lookup API.
`new Behavior(options, host)` requires a host. Prefer host declarations for automatic composition and teardown; constructing an instance directly does not register it in the host's managed Behavior list. A class entry receives an empty options object; an object definition, including `behaviorClass`, is passed to its constructor as options. Behavior options do not inherit the host's options.
Construction establishes `view`, `el`, options, `cid`, and state access before `initialize(options, host)`. UI selectors are resolved before this hook; state and DOM bindings initialize afterward. The host's `initialize` runs after its Behaviors are constructed. Behavior has no `preinitialize` hook.
| Option | Contract |
| --- | --- |
| `events`, `triggers` | DOM event maps or functions returning maps; selectors may use `@ui.name`. See [DOM interaction](#dom-interaction-and-ui). |
| `ui` | Named selector map or function returning one. Merged with host UI; host entries win on matching names. |
| `modelEvents`, `collectionEvents` | Event-to-handler maps or functions returning maps. Observe the host's model/collection through its DataApi. |
| `state`, `stateEvents` | Borrowed state and declarative observation, independent of the host's state. See [state](/docs/api/shared/state.md). |
Maps use functions or Behavior method-name strings for handlers, except `triggers`, whose values name host events. Custom options remain in `options` and are read with `getOption`. Recognized maps replace inherited maps, with the special host UI merge described above.
`Behavior.extend(prototypeProperties?, staticProperties?)` creates a subclass. `cidPrefix` defaults to `'mnb'`. `view` is the host; `el` is its fixed root element. There is no separate Behavior element, template, render method, or Region. Common extension and option methods are in [class utilities](/docs/api/shared/common.md).
## DOM interaction and UI
`events` callbacks run with the Behavior as `this` and receive the DOM event. `triggers` call the **host's** `triggerMethod`, passing `(host, DOMEvent, ...extraArgs)`. A string trigger prevents default and stops propagation; use `{ event, preventDefault: false, stopPropagation: false }` to opt out. See the shared [DOM event contract](/docs/api/shared/view-bindings.md#dom-events).
| Method | Contract |
| --- | --- |
| `$(selector)` | Forwards to the host's scoped query method. Returns the host's query collection. |
| `getUI(name)` | Returns the bound query collection, or `undefined` for an unknown name. Throws `MN0023` before UI binding. Read it after UI binding, usually in `onRender`. |
| `bindUIElements()` | Resolves the Behavior's selectors against the host; returns this Behavior. |
| `unbindUIElements()` | Releases bound UI references; returns this Behavior. |
| `normalizeUIString(value, bindings?)` | Expands `@ui.name` tokens in a selector string. |
| `normalizeUIKeys(map, bindings?)` | Returns a map with UI tokens expanded in its keys. |
| `normalizeUIValues(map, property?, bindings?)` | Mutates and returns the map, expanding tokens in string values or the named property of object values. See [UI helpers](/docs/api/shared/view-bindings.md#ui-bindings). |
The host coordinates UI rebinding during rendering. A saved query still points at its previous elements after a rerender; call `getUI` again. Do not assume Behavior UI is bound in `initialize`. A template-less CollectionView does not automatically bind Behavior UI; call the host's `bindUIElements()` when using existing elements. The Behavior shares the host's [fixed root](/docs/api/view.md#existing-elements).
`Behavior.setEventDelegator(provider)` replaces that class's DOM event provider and returns the class. `EventDelegator` is the provider slot. It is configured on the Behavior class independently from a host-specific override; runtime-wide configuration can configure both. There is no Behavior `setRenderer`, `setDomApi`, or `setDataApi`.
## Host events and data
Host events are forwarded to each Behavior's `triggerMethod` with their original arguments. A host `save` event invokes Behavior `onSave` and its `save` subscribers. The host's hook runs first when the host uses `triggerMethod`. Calling a Behavior's own `triggerMethod` only notifies that Behavior; use `this.view.triggerMethod(...)` to emit host intent as above. That host event is forwarded back to the sending Behavior too; an `onDismiss` hook must not re-emit the same host event recursively.
`initialize(options, host)` initializes the Behavior itself. The separate `onInitialize(host, options)` notification runs after the host's initialization. View lifecycle hooks such as `onRender`, `onAttach`, `onDetach`, `onBeforeDestroy`, and `onDestroy` receive the **host** and its event arguments. See the host's [View lifecycle](/docs/api/view.md#lifecycle-hooks-and-events) or [CollectionView lifecycle](/docs/api/collection-view.md#lifecycle-and-extension-points) for event-specific contracts.
`modelEvents` and `collectionEvents` bind after host initialization. Handlers use the Behavior as context and preserve the source's arguments. Access sources as `this.view.model` and `this.view.collection`. `delegateEntityEvents()` releases previous entity bindings and binds the current declarations to those sources; `undelegateEntityEvents()` removes those bindings. Both return the Behavior. Repeated delegation replaces bindings. Reassigning a host model, collection, or declaration does not automatically rebind it; call `delegateEntityEvents()` afterward.
`createState(options)`, `getState()`, `stateEvents`, `State`, and `Behavior.setStateApi(api)` follow the shared [state contract](/docs/api/shared/state.md). The Behavior's StateApi is independent of its host's provider. State observation does not require rendering or attachment. A host's state is not automatically the Behavior's state; pass a borrowed source deliberately when sharing it.
## Destruction and nested Behaviors
Host destruction invokes `destroy()` on its managed Behaviors. Behavior cleanup removes DOM handlers, state observation/owned state, host subscriptions, and host model/collection subscriptions. It releases its outgoing subscriptions; callbacks registered on the Behavior itself follow the ordinary `off`/`stopListening` ownership rules. Behavior cleanup does not destroy the host or borrowed sources.
Direct `behavior.destroy()` returns the Behavior and removes it from the host's managed list. It emits **no independent `before:destroy` or `destroy` notification** and has no public `isDestroyed()` method. `onBeforeDestroy`/`onDestroy` are forwarded host notifications: a removed Behavior no longer receives them. When the host destroys a managed Behavior, its final `onDestroy(host, options)` notification arrives after Behavior resource cleanup. If a Behavior must release an extra resource on both direct and host teardown, override `destroy` and delegate to `Behavior.prototype.destroy.call(this)` as part of that cleanup. Make the extra cleanup safe to repeat, since direct Behavior destruction has no once-only guard; do not rely only on `onDestroy`.
A Behavior subclass may declare nested `behaviors` using the same definitions as a host. Those instances share the original host and are owned by it. Destroying the declaring Behavior alone leaves its nested Behaviors alive. Use nesting to group host interactions, not to model a child lifetime.
## TypeScript
Import `BehaviorOptions`, `BehaviorHost`, `BehaviorInstance`, and `BehaviorConstructor` from `marionette`. `BehaviorInstance` describes custom options, host, state source and query collection. `BehaviorHost` is a structural host contract; View and CollectionView satisfy it. `BehaviorDefinition`, `BehaviorDefinitions`, and `BehaviorOptionsDefinition` describe host declarations. `DOMEvents`, `DOMTriggers`, `UISelectors`, and `UIBindings` describe shared maps.
Use [common methods](/docs/api/shared/common.md), [events](/docs/api/shared/events.md) and [state](/docs/api/shared/state.md) for inherited contracts.
[Canonical source](/docs/markdown/docs/api/behavior.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/mnobject.md
Canonical URL: https://marionettejs.com/docs/api/mnobject/
Markdown URL: https://marionettejs.com/docs/api/mnobject.md
Reading SHA-256: 2f94f67ed1fa89ed84f9b23725e43aee4265da11622b19209523e445d86fb9f7
# MnObject
[API index](/docs/api.md) · [Application](/docs/api/application.md) · [Shared utilities](/docs/api/shared/common.md)
MnObject gives a nonvisual object Marionette's events, options, state, Radio bindings and synchronous destruction. Use it when an object needs these lifetime services. A plain function or object is enough without them; an Application is appropriate when work needs start/stop, asynchronous preparation, or owned UI.
## Track draft changes
This object records whether a borrowed draft has changed since the last `markSaved()` call. It owns its tracking state and releases its draft subscription when destroyed. It does not save data or compare the draft with a server snapshot.
```js
import { MnObject } from 'marionette';
import { Model, StateApi } from '@mnjs/data';
const DraftChanges = MnObject.extend({
createState() { return new Model({ dirty: false }); },
initialize({ draft }) {
this.listenTo(draft, { change: () => this.getState().set('dirty', true) });
},
markSaved() { this.getState().set('dirty', false); },
}).setStateApi(StateApi);
const draft = new Model({ title: 'Untitled' });
const changes = new DraftChanges({ draft });
draft.set('title', 'Quarterly summary');
changes.getState().get('dirty'); // true
changes.markSaved();
changes.destroy();
```
The draft remains available after `changes.destroy()`. Its owner disposes it when finished. `@mnjs/data` supplies observable data here; API access and persistence require a [separate solution](/docs/integrations/setup.md#observable-data-and-api-access).
## Construction and options
`new MnObject(options?)` merges options, assigns `cid`, configures Radio and state access, calls `initialize(options)`, then binds `stateEvents`. Radio bindings are available during initialization. State is created lazily; calling `getState()` in `initialize` is supported. There is no `preinitialize` hook.
| Option | Contract |
| --- | --- |
| `state` | Exact borrowed source, taking precedence over the class's state source and `createState`. A function remains the source itself. |
| `stateEvents` | Event-to-handler map or function returning one. Values are callbacks or MnObject method names. Observation begins after `initialize`. |
| `channelName` | Radio channel name or function returning one. Falsy disables declarative Radio setup. |
| `radioEvents`, `radioRequests` | Event/reply maps or functions returning maps, with callbacks or MnObject method names as values. See [Radio bindings](/docs/api/shared/common.md#declarative-radio-bindings). |
Resolver functions run with the object as `this`. Custom options remain in `options` and are available through `getOption(name)`; they do not automatically become instance properties. `modelEvents` and `collectionEvents` are not built-in MnObject declarations. Use `listenTo` or `bindEvents` to observe a separate source.
`MnObject.extend(prototypeProperties?, staticProperties?)` defines a subclass. `cidPrefix` defaults to `'mno'`. `initialize` defaults to a no-op. Common constructors, custom constructor invocation, option utilities and binding helpers are documented in [class utilities](/docs/api/shared/common.md).
## State and communication
| Member | Contract |
| --- | --- |
| `createState(options)` | Override to create owned state. Receives original constructor options; defaults to a plain object. |
| `getState()` | Returns the same owned or borrowed source for the object's lifetime. |
| `State` | StateApi provider, not the source. |
| `MnObject.setStateApi(api)` | Overlays the receiving class's StateApi and returns that class. Configure before construction. |
| `getChannel()` | Returns the configured Radio channel, or `undefined`. |
| `Radio` | Radio provider on the class/prototype; not a recognized constructor option. |
[State](/docs/api/shared/state.md) defines observation and owned/borrowed disposal. [Events](/docs/api/shared/events.md) covers `on`, `once`, `off`, `trigger`, `triggerMethod`, `listenTo`, `listenToOnce`, and `stopListening`. State and declarative Radio bindings stay active throughout the live object's lifetime. MnObject has no running/stopped state.
Use [declarative Radio bindings](/docs/api/shared/common.md#declarative-radio-bindings) when the object's lifetime owns channel subscriptions/replies. Destruction removes all replies on the configured channel registered with this object as context, including manual `bindRequests` calls. Replies on other channels or with another context need explicit cleanup; `stopListening` only handles event subscriptions.
## Destruction and ownership
`destroy(options?)` is synchronous and returns the object. `isDestroyed()` is false until destruction commits and true before `onDestroy`. Repeated or reentrant destruction returns the same object without repeating the lifecycle.
| Event | Hook | Arguments and timing |
| --- | --- | --- |
| `before:destroy` | `onBeforeDestroy` | `(object, options)` before Radio/state cleanup, while `isDestroyed()` is false. |
| `destroy` | `onDestroy` | `(object, options)` after marking destroyed and releasing Radio bindings and owned state. Event subscriptions are cleared afterward. |
Hooks run before event subscribers. Returned Promises are ignored; complete required asynchronous work before calling `destroy()`. Exceptions propagate; destruction is not transactional. A throw in `before:destroy` interrupts cleanup and leaves destruction marked in progress, so calling `destroy()` again does not retry it. Keep teardown hooks synchronous and reliable.
Normal destruction releases outgoing `listenTo` subscriptions and incoming event subscriptions automatically. Other subscribers on a shared data source/channel remain intact. State produced by `createState` is disposed through the configured StateApi; supplied state is borrowed and survives.
MnObject does not own arbitrary fields or constructor arguments. Assigning it to an Application field does not register it for destruction: that owner must call its `destroy()` when finished. Similarly, extra resources created by a MnObject need explicit cleanup in its lifecycle hooks. An overridden `destroy` must call the parent implementation to retain these guarantees.
There are no rendering, Region, child Application, `start`, `stop`, or `restart` methods on MnObject.
## TypeScript
Import the runtime constructor as `MnObject` and the instance contract as `MnObjectInstance` from `marionette`. `MnObjectInstance` describes custom options and the state source. `MnObjectConstructor` describes the extensible constructor; `extend` preserves declared methods and state inference. There is no exported `MnObjectOptions` alias. Channel and state provider types are linked from their shared contracts.
[Canonical source](/docs/markdown/docs/api/mnobject.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/shared/common.md
Canonical URL: https://marionettejs.com/docs/api/shared/common/
Markdown URL: https://marionettejs.com/docs/api/shared/common.md
Reading SHA-256: bc8615336f373bcc36ab50fce29ea3edc862f9cc2df9231f741f147eed6ff2ae
# Shared class utilities
Application, View, CollectionView, Region, Behavior, and MnObject share the class and instance utilities below. The Radio section applies specifically to Application and MnObject. See the [API index](/docs/api.md) for class-specific constructor options and lifecycle hooks.
## Define a class
`Parent.extend(prototypeProperties?, staticProperties?)` returns a child constructor. Prototype properties become instance methods and defaults; static properties belong to the constructor. The child inherits the parent's prototype and receives its enumerable static properties, including `extend`. Child properties override matching parent properties. Objects and arrays are shared values unless you create them per instance.
```js
import { View } from 'marionette';
const Panel = View.extend({
template: false,
title: 'Untitled',
initialize() {
this.el.setAttribute('aria-label', this.getOption('title'));
}
});
const panel = new Panel({ title: 'Settings' });
```
Without a `constructor` property, the child forwards construction to its parent. A supplied `constructor` replaces that call: it must call `Parent.call(this, options)` or `Parent.apply(this, arguments)` when it needs the parent's initialization. Marionette's constructors support these calls. Prefer the class's initialization hooks for ordinary setup. An override does not automatically invoke the parent's method; call `Parent.prototype.method.call(this, ...)` when both are needed. `Child.__super__` also refers to `Parent.prototype`.
## Options and initialization
Construction creates `this.options` by shallowly combining the class's `options` object (or the result of its `options()` function) with supplied constructor options. Supplied values take precedence. The source objects are not modified. Each class copies its recognized configuration keys onto the instance; custom options remain available through `getOption`.
`initialize(...)` is a no-op extension hook called during construction with the constructor arguments, including the host View for a Behavior. It does not render a View or start an Application. Application, View, and CollectionView also expose `preinitialize(...)`; their class references describe its position in construction. Region, Behavior, and MnObject do not call a `preinitialize` hook.
| Instance method | Contract and return value |
| --- | --- |
| `getOption(name)` | Accepts a string, number, or symbol property key. Returns `this.options[name]` when it is not `undefined`; otherwise returns `this[name]`. Preserves `false`, `0`, `''`, and `null`. Does not invoke a function-valued option. An omitted/null name returns `undefined`. |
| `mergeOptions(options, keys)` | Copies listed own enumerable string properties from `options` onto this instance, skipping `undefined` values. Use an array of option names. Returns `undefined`; nullish options do nothing. |
| `normalizeMethods(bindings)` | Returns a new map with each function value preserved and each method-name string resolved on this instance/prototype. Does not bind the functions or modify the input. Falsy input returns `undefined`. A missing/nonfunction handler throws `MN0019`. |
Defaults and passed options are merged only one level deep. For example, supplying an `events` map replaces the inherited map rather than combining its keys. Resolve a combined map explicitly when that is your intent.
## Binding helpers
These helpers accept maps from a literal event/request name to a function or an instance method-name string. They resolve names using `normalizeMethods`; [Events](/docs/api/shared/events.md) methods such as `listenTo` accept function references directly.
| Instance method | Contract |
| --- | --- |
| `bindEvents(source, bindings)` | Registers through `this.listenTo`, with this instance as callback context. The source needs compatible `on` and `off` methods. |
| `unbindEvents(source, bindings?)` | Removes this instance's matching subscriptions. Without bindings, removes all of its `listenTo` subscriptions to that source. Other listeners remain. |
| `bindRequests(channel, bindings)` | Registers request replies through `channel.reply(bindings, this)`, with this instance as reply context. |
| `unbindRequests(channel, bindings?)` | Removes matching replies owned by this instance. Without bindings, removes all of this instance's replies on that channel. Other owners' replies remain. |
All four return the receiver. A missing/falsy source or channel does nothing. A missing/falsy bindings map makes either bind method a no-op and either unbind method remove all matching bindings owned by the receiver. Event-binding helpers reject an own enumerable `__proto__` event key (`MN0026`).
`bindEvents` has the lifetime tracking of `listenTo`. `bindRequests` does not add request cleanup to `stopListening`; pair manually registered replies with `unbindRequests` when their owner is finished. Application/MnObject [declarative Radio configuration](#declarative-radio-bindings) has its own lifecycle integration.
See [Events and cleanup](/docs/api/shared/events.md#cleanup) for subscription ownership and [state](/docs/api/shared/state.md) for owned versus borrowed state.
## Declarative Radio bindings
Application and MnObject support `channelName`, `radioEvents`, and `radioRequests`. A channel name or binding map may be supplied by a function called with the owner as `this`. Map handlers are callbacks or owner method names. A falsy channel name disables setup.
`channelName` selects a channel through the owner's `Radio` provider during construction. `getChannel()` returns it, or `undefined` when no channel was configured. `radioEvents` uses event-to-handler bindings and `radioRequests` registers request replies with the owner as callback context.
On an Application, these bindings stay active while stopped as well as running; they are not gated like its `stateEvents`. On MnObject, they stay active for its live lifetime. Destruction removes all replies on the configured channel registered with this owner as context, including manual replies, and releases its subscriptions. The shared channel and other owners' registrations remain. Replies on other channels or with another context need explicit cleanup. Reassigning the declarations later does not reinitialize them. `Radio` is a prototype/provider slot, not a recognized constructor option. Use [runtime configuration](/docs/api/runtime.md#isolation-and-composition) for isolated Radio instances. See the [Radio reference](/docs/packages/radio.md) for channel scope, events, request/reply methods, and logging. Use [binding methods](#binding-helpers) for explicit owner bindings.
[Canonical source](/docs/markdown/docs/api/shared/common.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/shared/events.md
Canonical URL: https://marionettejs.com/docs/api/shared/events/
Markdown URL: https://marionettejs.com/docs/api/shared/events.md
Reading SHA-256: 228e10eb741afbbc67aeaad4a9268184950430eac2eb4101effc15182fa51823
# Events
Application, View, CollectionView, Region, Behavior, and MnObject provide these synchronous event APIs. This page describes object events; see [View runtime](/docs/api/shared/view-bindings.md) for DOM bindings and child event forwarding, and [state](/docs/api/shared/state.md) for provider-based state observation.
## Names, maps, and callback context
An event name is one literal string. Colons are a naming convention; spaces do **not** separate multiple events. Use a map to register several names. Map keys are own enumerable string properties and map values must be functions, not method-name strings. The [binding helpers](/docs/api/shared/common.md#binding-helpers) additionally accept method names.
```js
import { View } from 'marionette';
const listener = new View({ template: false });
const source = new View({ template: false });
listener.listenTo(source, {
selected(view) { this.selectedView = view; },
cleared() { this.selectedView = undefined; }
});
source.trigger('selected', source);
source.destroy();
listener.destroy();
```
`on`/`once` call ordinary functions with the supplied context, or the source as `this` when no truthy context is supplied. `listenTo`/`listenToOnce` use the listening object as context. Arrow functions retain their lexical `this`.
## Subscribe and unsubscribe
| Method | Contract |
| --- | --- |
| `on(name, callback, context?)` / `on(map, context?)` | Adds callbacks to this source. Repeated registrations add repeated calls. |
| `once(name, callback, context?)` / `once(map, context?)` | Registers a separate one-time callback per name. Each is removed before being invoked, including if it throws or triggers the same event recursively. |
| `off(name?, callback?, context?)` / `off(map, context?)` | Removes callbacks on this source that match all supplied filters. An omitted/null name matches every name. `off()` removes all callbacks, including other objects' subscriptions to this source. |
| `listenTo(source, name, callback)` / `listenTo(source, map)` | Subscribes to another source and records the subscription on this listener. The source must implement compatible `on(name, callback, context)` and `off(name, callback, context)` methods. A nullish source does nothing. |
| `listenToOnce(source, name, callback)` / `listenToOnce(source, map)` | The tracked form of `once`. Each mapped name has an independent one-time callback. |
| `stopListening(source?, name?, callback?)` / `stopListening(source, map)` | Removes this listener's matching subscriptions. Omit the name to remove all its subscriptions to the source; omit the source to select all its sources. `stopListening()` removes every tracked subscription. |
All methods in this table return the receiver. Removing a one-time callback can use the original function reference. For selective removal, retain the same function reference used to subscribe; creating a new arrow function does not match the old one. The map forms of `on`, `once`, and `off` also accept a third explicit context argument, which takes precedence over the second when it is not `undefined`.
## Trigger events and hooks
| Method | Contract and return value |
| --- | --- |
| `trigger(name, ...args)` | Synchronously calls that event's listeners with the supplied arguments, followed by `all` listeners with `(name, ...args)`. Returns the source. |
| `triggerMethod(name, ...args)` | Calls the matching instance/prototype hook, then triggers the event with the same arguments. Returns the hook's result, or `undefined` if no callable hook exists. |
`triggerMethod('before:render', view)` calls `onBeforeRender(view)` before emitting `before:render`. Each colon-separated segment begins with a capital letter in the hook name. Hooks come from the instance/prototype, not from `options`.
Calling `triggerMethod` with that same name inside its hook invokes the hook again. Forward a distinct intent, or use `trigger` when only listeners should be notified.
Delivery is synchronous and follows registration order for each event. Callback return values do not cancel an event. A synchronous exception stops the dispatch and propagates to the caller. If the hook throws, `triggerMethod` does not emit the event. Returned Promises are not awaited: an asynchronous hook's result is returned while event listeners run immediately.
An `all` subscription observes event names as well as payloads. It is useful for event forwarding; ordinary feature subscriptions should name the intent they need.
## Cleanup
Successful destruction of a MnObject, View/CollectionView, Region or Application removes its outgoing `listenTo` subscriptions and its incoming callbacks after its final destruction notifications. Native listener bookkeeping is released too: a retained Application does not need a `destroy` handler that calls `stopListening(view)` for each replaced View. Native `@mnjs/data` Models and Collections also release events on destruction.
Application `stop()` preserves subscriptions to surviving sources; it is not Application destruction. Use `stopListening(source, ...)` when a subscription's useful lifetime ends before either object is destroyed. `off()` removes incoming callbacks; `stopListening()` removes outgoing subscriptions. Neither is a substitute for the other's direction.
External sources follow their own cleanup contracts. If an external source can end while its Marionette listener survives, release the listener's subscription explicitly unless the source's integration guarantees equivalent cleanup. Emitting an event named `destroy` alone does not destroy an object or clear subscriptions.
[API index](/docs/api.md) · [Shared utilities](/docs/api/shared/common.md) · [View runtime configuration](/docs/api/shared/view-bindings.md)
[Canonical source](/docs/markdown/docs/api/shared/events.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/shared/state.md
Canonical URL: https://marionettejs.com/docs/api/shared/state/
Markdown URL: https://marionettejs.com/docs/api/shared/state.md
Reading SHA-256: 604ad1126c34067fd167c08da4f9e809523457eb4139270152d3509f5a6f82fb
# State
Application, View, CollectionView, Behavior, and MnObject can own state or borrow a supplied source. Region has no state API. State is separate from a View's `model` and `collection`; it is not automatically included in template data.
## Create or supply state
| Member | Contract |
| --- | --- |
| `createState(options)` | Override to create state owned by this instance. Receives the original constructor options. The default returns a new plain object. |
| `getState()` | Returns the same state source for the owner's lifetime. Calls `createState` lazily on first access when no state was supplied. |
| Constructor `state` | Supplies the exact borrowed source. A non-`undefined` supplied value takes precedence over a class's `state` property and `createState`. |
| Prototype/instance `state` | Supplies a borrowed source when no non-`undefined` constructor state is supplied. A function is treated as the source itself; use `createState` for a factory. |
| `stateEvents` | An event-to-handler map, or function returning one. Values are functions or instance method-name strings. Can be defined on the class or passed as a constructor option. |
Calling `getState()` in `initialize` is supported. Declaring `stateEvents` requests the state during construction, after `initialize`, so observable state is often created then. Rendering or restarting does not create new state.
```js
import { View } from 'marionette';
import { Model, StateApi } from '@mnjs/data';
const Disclosure = View.extend({
template: false,
createState() { return new Model({ expanded: false }); },
stateEvents: { 'change:expanded': 'updateExpanded' },
initialize() { this.updateExpanded(); },
updateExpanded() {
this.el.setAttribute('aria-expanded', String(this.getState().get('expanded')));
}
});
Disclosure.setStateApi(StateApi);
const disclosure = new Disclosure({ tagName: 'button' });
disclosure.getState().set('expanded', true);
disclosure.destroy();
```
This uses native data only for observable state. API access and persistence remain separate concerns; see [data setup](/docs/integrations/setup.md#observable-data-and-api-access).
## Observe state
The configured StateApi subscribes to each literal event name and calls its handler with the owner as `this`. Callback arguments come from the state source unchanged. For `@mnjs/data` Model's `change:expanded`, those arguments are `(model, value, change)`, with mutation options plus `changed` and `previous` properties in `change`. Another state source can have a different event contract. The bindings are initialized once; assigning a new `state` or `stateEvents` property later does not replace them.
The default StateApi cannot observe the plain-object default state. Configure a compatible StateApi before constructing an owner with `stateEvents`; otherwise subscription throws `MN0037`. Changing a plain object's property does not synthesize an event.
| Owner | When `stateEvents` deliver |
| --- | --- |
| View, CollectionView, Behavior, MnObject | After their state bindings initialize, until destruction releases them. View delivery does not require render or DOM attachment; detaching a View keeps its state observation. |
| Application | Only while `isRunning()` is true, including `onStart` and preparation during an active restart. Delivery stops before root View teardown. Startup, stopped, and failed-start writes are not replayed when the Application later activates. |
Application's activity rule applies to configured `stateEvents`. An explicit `app.listenTo(state, ...)` subscription has the ordinary [Events lifetime](/docs/api/shared/events.md#cleanup) and is not automatically gated by `isRunning()`.
## Ownership and disposal
State returned by `createState` belongs to its owner. Destruction first releases that owner's state subscriptions, then calls the configured `State.disposeOwned(source)` when provided. The native data StateApi calls the source's `destroy()` method if it has one. A borrowed source is never disposed by the borrower; multiple Views can share it and release their subscriptions independently.
Application stop/restart retains state. View rendering retains state. Destruction is the disposal boundary; it does not dispose arbitrary fields attached to the owner. If state has never been requested, destruction does not create it. A later first `getState()` on a destroyed owner creates and immediately disposes its owned state.
## Configure the StateApi
`OwnerClass.setStateApi(api)` shallowly overlays that class's `State` provider and returns the class. It applies to Application, View, CollectionView, Behavior, and MnObject. A class's overlay does not mutate its parent's or sibling's provider. Configure before constructing instances. A global `setStateApi(api)` or an isolated runtime's `setStateApi(api)` configures its state-capable classes together; see [setup](/docs/integrations/setup.md#configure-once) and [View runtime configuration](/docs/api/shared/view-bindings.md).
The provider members used by an owner are `subscribe(source, name, callback, context)`, which returns an unsubscribe function, and optional `disposeOwned(source)`. The public `State` property is the configured provider, not the state source returned by `getState()`. The [provider reference](/docs/api/providers/data.md#stateapi) covers authoring; alternative integrations have their own source/disposal policies.
[API index](/docs/api.md) · [View](/docs/api/view.md) · [Shared utilities](/docs/api/shared/common.md)
[Canonical source](/docs/markdown/docs/api/shared/state.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/shared/view-bindings.md
Canonical URL: https://marionettejs.com/docs/api/shared/view-bindings/
Markdown URL: https://marionettejs.com/docs/api/shared/view-bindings.md
Reading SHA-256: a92e7f63e6694b92b894ddd56b01e01e627810e71ebc7a3b391566dcd6667d68
# Rendering and View bindings
[View](/docs/api/view.md) and [CollectionView](/docs/api/collection-view.md) share the contracts on this page. Their rendering/composition lifecycles remain class-specific. For common object methods, event subscriptions, and state ownership, see [common](/docs/api/shared/common.md), [events](/docs/api/shared/events.md), and [state](/docs/api/shared/state.md).
## Templates and data
`template` is a value understood by the renderer. The default renderer calls a template function as `template(data)`; it does not compile template strings. `template: false` disables template rendering. The default DOM provider inserts renderer output as HTML; choose a renderer/DOM integration appropriate to the output. [Setup](/docs/integrations/setup.md#configure-once) shows the Lit integration, whose ordinary interpolations render values as text.
| Method | Default contract and extension use |
| --- | --- |
| `getTemplate()` | Returns `this.template`. Override to choose a template for the current View. |
| `serializeData()` | Serializes `model` if present; otherwise returns `{ models: serializeCollection() }` for a collection, or `undefined`. Override to supply a different template data shape. |
| `serializeModel()` | Returns `this.Data.serialize(this.model)`. |
| `serializeCollection()` | Returns `this.Data.models(this.collection).map(model => this.Data.serialize(model))`. |
| `mixinTemplateContext(data)` | Resolves `templateContext`, then shallow-merges its own enumerable properties over data. Does not mutate either input. Returns either input directly when the other is falsy. |
| `attachElContent(output)` | Sends renderer output to `this.Dom.setContents(this.el, output)`. Override for a specialized insertion strategy that keeps the View's root. Returns no defined value. |
Rendering obtains the template, prepares serialized data plus template context, calls the configured renderer with the View as `this`, and passes its return value to `attachElContent`. Falsy final template data becomes `{}`. The default template function itself receives no View context; use `templateContext` or serialization for View-derived values.
This standalone example configures a subclass with Lit, renders plain supplied data, and cleans up:
```js
import { View } from 'marionette';
import LitDomApi from '@mnjs/adapters/dom/lit-html';
import { html } from 'lit-html';
const Greeting = View.extend({
template: ({ name }) => html`
Hello, ${name}
`,
});
Greeting.setDomApi(LitDomApi);
const greeting = new Greeting({ model: { name: 'Sam' } });
greeting.render();
greeting.destroy();
```
This uses the default DataApi, which serializes plain values unchanged. Observable Models/Collections need their [DataApi configuration](/docs/integrations/setup.md#configure-once). Data changes do not automatically render a View; select the events and response explicitly.
## Root attributes
`renderAttributes()` reevaluates `attributes`, `id`, and `className`, applies them to `el`, and returns the View. It does not render a template, rebuild children, rebind UI, or emit render events. It does nothing while destroying or destroyed.
When creating a root, Marionette applies these declarations once. A supplied root is untouched until an explicit `renderAttributes()`. The native DomApi removes attributes whose value is `null`, leaves `undefined` and omitted keys unchanged, and stringifies other values. `id` and `className` override the corresponding entries in `attributes` when declared. Calling `render()` does not refresh these root declarations.
## UI bindings
Declare `ui` as `{ name: 'selector' }` or a function returning that map. After binding, `ui` contains query results; Marionette retains the selectors for rebinding. Use `@ui.name` in DOM event/trigger keys and View Region selectors to reuse them.
| Method | Contract |
| --- | --- |
| `$(selector)` | Queries descendants of `el`; the root itself is excluded by the native DomApi. Returns the provider's query type (native: static `NodeList`). |
| `getUI(name)` | Returns the bound query result or `undefined` for an unknown name. Throws if no UI map was declared or it has not been bound. Use `[0]` when the first native element is needed. |
| `bindUIElements()` → `this` | Resolves the UI map and queries the current DOM, including Behavior UI. Normally automatic after rendering or construction with existing contents. No-op while destroying/destroyed. |
| `unbindUIElements()` → `this` | Releases query bindings and restores the selector declarations, including Behavior UI. Destruction does this automatically. |
| `normalizeUIString(value, bindings?)` | Returns a string with `@ui.name` references replaced by selectors. |
| `normalizeUIKeys(map, bindings?)` | Returns a new map with normalized keys; nullish input returns `{}`. |
| `normalizeUIValues(map, property?, bindings?)` | Normalizes string values or a named property of object values **in place** and returns the same map. |
Normalization uses the View's original selector map unless an explicit map is provided. An empty or undeclared `@ui` name throws. Bound queries are snapshots; manually changed contents need rebinding before querying through `getUI` again.
## DOM events
`events` maps `'event selector'` to a callback or View method name. For example, `events: { 'click .save': 'save' }` calls the View's `save` handler for a delegated click. Omit the selector to listen on the root. Callbacks run with the View as `this` and receive the DOM event.
With the native delegator, `event.currentTarget` is the View's root element. `event.delegateTarget` is the nearest matching descendant on the event path: use it to read the control matched by the selector, even when a click originated inside that control. The root is not a selector match. `focus` and `blur` use capture.
`triggers` maps the same DOM keys to a View event name or `{ event, preventDefault, stopPropagation }`. A trigger calls `view.triggerMethod(eventName, view, domEvent, ...extraArguments)`. Both prevention flags default to `true`; set either to `false` to allow that browser behavior. `events` handlers do not receive these automatic prevention calls.
Both maps may be functions evaluated on the View. `@ui` selectors are resolved before delegation. A missing named handler is an error.
| Method | Contract |
| --- | --- |
| `delegateEvents(events?)` → `this` | Removes existing View/Behavior DOM handlers, refreshes child event maps, then binds the explicit event map or current `events`, plus current `triggers` and Behavior DOM handlers. Use after changing declarations. |
| `undelegateEvents()` → `this` | Releases View and Behavior DOM handlers. |
Both methods are no-ops while destroying/destroyed. Construction delegates automatically; destruction releases handlers automatically. Detaching a live View preserves its DOM bindings. Rendering does not reread changed event declarations.
## Data bindings
`modelEvents` and `collectionEvents` map source event names to callback functions or View method names; either map may be returned from a function. Bindings use the configured `Data.subscribe`, preserve source arguments, and invoke callbacks with the View as `this`. A plain object/array can supply template data, but the default DataApi requires an `on`/`off` source when an event map is present. Use the appropriate adapter for observable data.
`delegateEntityEvents()` releases previous model/collection bindings, then binds current declarations, including Behaviors, and returns the View. `undelegateEntityEvents()` releases those subscriptions and returns the View. Construction binds them after `initialize`; destruction releases them.
Replacing a View's model or collection after construction does not change its existing subscriptions. Assign the new source or event map, then call `delegateEntityEvents()` to release the old bindings and observe the current declarations. Repeated delegation replaces bindings rather than accumulating them. Use `undelegateEntityEvents()` when observation should stop without rebinding. Render explicitly if the new source should be displayed immediately.
Observable model changes do not automatically update the View's rendered contents. Choose the response in `modelEvents` or `collectionEvents`: for a small View, `modelEvents: { change: 'render' }` rerenders on change. On a layout View, that also resets its Regions and destroys their children; see [View rendering](/docs/api/view.md#rendering-and-status).
These bindings do not own or destroy the model/collection. State bindings have separate ownership and delivery rules: see [state](/docs/api/shared/state.md).
## Child events
The owning View/CollectionView can handle events from its immediate managed children:
| Declaration | Behavior |
| --- | --- |
| `childViewEvents: { eventName: handler }` | Calls a parent method name or callback with the parent as `this` and the child's original event arguments. |
| `childViewTriggers: { eventName: parentEvent }` | Calls `parent.triggerMethod(parentEvent, ...originalArguments)`. |
| `childViewEventPrefix: 'child'` | Forwards every child event as `child:eventName` through `triggerMethod`. Defaults to `false`; set `false` to disable prefix forwarding. |
Each declaration may be a function evaluated on the parent. When all apply, the order is the mapped handler, mapped parent event, then prefixed event. No child argument is added: a DOM `triggers` event already supplies its View, while `child.trigger('selected', id)` supplies only `id`. Define explicit mappings at each level when forwarding through nested composition.
The maps are prepared during construction and refreshed by `delegateEvents()`. Region/CollectionView ownership establishes forwarding and releases it when the child leaves. See [subscription cleanup](/docs/api/shared/events.md#cleanup) for native destruction and listener ownership.
## Behavior composition
`behaviors` accepts an array or named object containing Behavior constructors or `{ behaviorClass: BehaviorClass, ...options }` entries. A function can return either shape. Names organize the definitions; the View does not expose a public lookup-by-name API. Nested Behavior definitions are composed onto the same host.
Marionette constructs each Behavior with `(options, view)`. Behaviors share the host's fixed element and data sources; their DOM events, triggers, UI and entity bindings join the host's lifecycle. Host UI selectors override Behavior selectors with the same name. Behavior DOM triggers emit on the host. Host events are forwarded through each Behavior's `triggerMethod`, including an initialization notification after the host is initialized. Host destruction releases Behaviors and their owned state; it delivers the host's destroy notification to them.
This defines the View's accepted composition option. The [Behavior reference](/docs/api/behavior.md) covers its own APIs, forwarded hooks, and direct versus host destruction.
## Class configuration
Configure a subclass before creating its instances. Each setter returns that class and changes its prototype configuration. Descendants inherit configuration unless they override it; changing a subclass does not modify the parent class.
| Static method | Effect |
| --- | --- |
| `setRenderer(renderer)` | Replaces `_renderHtml` with a function `(template, data) → output`, invoked with the View as `this`. Pass a usable renderer; omitting it assigns `undefined` and does not restore the default. |
| `setDomApi(mixin)` | Shallow-merges methods over the class's existing `Dom` provider, preserving unspecified methods. Controls root creation, queries, attributes, content insertion, and DOM attachment operations. |
| `setDataApi(mixin)` | Shallow-merges methods over `Data`. A View uses `serialize`, `models`, and `subscribe`; CollectionView also uses collection identity/observation operations. |
| `setStateApi(mixin)` | Shallow-merges methods over `State`. See [state configuration](/docs/api/shared/state.md). |
| `setEventDelegator(delegator)` | Replaces `EventDelegator`. Its `delegate({ eventName, selector, handler, rootEl })` must return the cleanup function used when undelegating/destroying. |
`Dom`, `Data`, `State`, `EventDelegator`, and `_renderHtml` are the instance-visible configuration slots. Prefer setters for class configuration; `Dom`, `Data`, `State`, `EventDelegator`, `_renderHtml`, and `monitorViewEvents` are not recognized constructor options. `_renderHtml` is the renderer extension slot despite its underscore; `attachElContent` is the insertion extension point.
The [setup recipe](/docs/integrations/setup.md#configure-once) uses top-level setters to configure all relevant default classes together. See [runtime configuration](/docs/api/runtime.md) for isolated families and setter scope, [rendering/DOM providers](/docs/api/providers/dom.md) for authoring interfaces, and [data/state providers](/docs/api/providers/data.md) for observation and disposal.
## Types
Import these types from `marionette`:
- `DOMEvents`: event-key map to callbacks or method names. `DOMTriggers`: event-key map to `TriggerDefinition`; `TriggerOptions` describes object triggers.
- `UISelectors`: string selector map. `UIBindings`: that map or a function returning it. Query results follow `ViewInstance`'s `Query` type.
- `Bindings`: source event map used by model, collection, and state bindings.
- `BehaviorDefinition`, `BehaviorDefinitions`, `BehaviorOptionsDefinition`: the constructor/options entry, collection of entries, and object-entry shape.
- `Renderer`: renderer signature. `DomApiContract`, `DataApiContract`, `StateApiContract`: provider interfaces; setters accept partial overlays for these three APIs.
- `EventDelegator`, `DelegateOptions`, `DelegatedEvent`: the DOM delegation provider, registration arguments, and native event with optional `delegateTarget`.
These types expose configuration and integration boundaries. The complete interfaces are in [rendering/DOM providers](/docs/api/providers/dom.md) and [data/state providers](/docs/api/providers/data.md).
[Canonical source](/docs/markdown/docs/api/shared/view-bindings.md) · [Source identity](/docs/manifest.json)
---
Document: docs/api/errors.md
Canonical URL: https://marionettejs.com/docs/api/errors/
Markdown URL: https://marionettejs.com/docs/api/errors.md
Reading SHA-256: 505ae9a0a118e9a06e6ad57a84df138a2cba860f05d4efa5dbf18350bf712daf
# Errors and diagnostics
Marionette reports invalid framework configuration with `MarionetteError`. Inspect the error's `code` to identify the contract, then read the matching diagnostic from the installed version. Application failures, such as a rejected API request, can remain ordinary errors handled by the application that owns that work.
## MarionetteError
Import `MarionetteError` from `marionette` or `@mnjs/utils`; within the same module format they export the same constructor. Use `new MarionetteError(options)`. Each call creates a native `Error` instance with a stack; `instanceof Error` and `instanceof MarionetteError` both work. Calling it as a plain function is unsupported.
```js
import { MarionetteError } from 'marionette';
const error = new MarionetteError({
code: 'MN0019',
message: 'The configured handler must resolve to a function.'
});
const diagnosticCode = error.code;
const description = error.toString();
```
The example constructs an error for inspection. Framework operations create their own errors; do not use Marionette's `MN` codes for unrelated application failures.
| Field or method | Contract |
| --- | --- |
| `message`, `name` | Supplied values override native Error values. With no supplied name, the inherited name is `Error`. |
| `code` | A string code selects `https://marionettejs.com/errors//`, overriding an explicitly supplied `url`. |
| `url` | Without a string code, the supplied suffix (default `''`) is appended to `urlRoot`, whose default is `https://marionettejs.com/docs/`. |
| `description`, `fileName`, `lineNumber`, `number` | Optional metadata copied from the options object. |
| `toString()` | Returns `name: message See: url`. |
| `captureStackTrace(fallbackError)` | Captures a native stack when supported; otherwise copies `fallbackError.stack`. Construction already calls it. |
Only the listed metadata fields (`code`, `description`, `fileName`, `lineNumber`, `name`, `message`, `number`, `url`) are copied from options. They become ordinary own fields; other option fields are ignored. Values are preserved rather than validated or coerced. Construction and formatting are synchronous, with no ownership or cleanup lifecycle. Extend the constructor with native `class extends` when a distinct application error type is useful.
## Find a diagnostic
Use the package's [local documentation helper](/docs/agents.md#local-contract-lookup) from the application's directory. Replace `` with the installed or copied `skills/marionette` directory:
```sh
node /scripts/docs.mjs --diagnostic MN0019
```
The result includes the installed version, code status, affected objects, remediation, diagnostic URL, and `docsSection`. Read that section with `--section` to stay inside the installed documentation. Retired codes remain discoverable, but are no longer emitted by that release. Follow the installed contract before changing code: the website can describe a different release. Unknown codes are not evidence of a framework bug; first check which package/version produced the error.
Diagnostics identify invalid inputs and configuration. They do not replace application error handling, and they do not catch every possible misuse. Synchronous callback exceptions propagate through dispatch. An Application's asynchronous preparation rejection is part of its [start lifecycle](/docs/api/application.md); handle failure at the owning workflow boundary.
## MN0001
view-el-must-be-dom-element. Status: **retired**. Applies to CollectionView, View.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0002
region-el-type-invalid. Status: **retired**. Applies to Region.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0003
view-already-owned. Status: **active**. Applies to Application, CollectionView, Region, View.
Use the owning Application to display its prepared root. Detach a displayed view from its Region or CollectionView before adopting it elsewhere, or create a new view instance.
## MN0004
region-el-required. Status: **active**. Applies to Region.
Configure the Region with an el selector or DOM element before using it.
## MN0005
region-el-not-found. Status: **active**. Applies to Region.
Render the parent View before direct selector-backed Region operations, ensure the selector resolves within its parent element, or explicitly allow a missing element where supported.
## MN0006
region-view-required. Status: **retired**. Applies to Region.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0007
region-view-destroyed. Status: **active**. Applies to Application, Region, View.
Create a new View instance instead of attempting to show a destroyed view.
## MN0008
region-definition-invalid. Status: **retired**. Applies to Application, Region, View.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0009
event-bindings-invalid. Status: **retired**. Applies to Application, Behavior, CollectionView, MnObject, Region, View.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0010
request-bindings-invalid. Status: **retired**. Applies to Application, Behavior, CollectionView, MnObject, Region, View.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0011
collection-view-child-view-required. Status: **active**. Applies to CollectionView.
Configure childView with a View class or a function that returns a View class.
## MN0012
collection-view-child-view-invalid. Status: **retired**. Applies to CollectionView.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0013
collection-view-container-not-found. Status: **active**. Applies to CollectionView.
Ensure childViewContainer resolves to an element within the rendered CollectionView.
## MN0014
collection-view-filter-invalid. Status: **retired**. Applies to CollectionView.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0015
collection-view-swap-non-children. Status: **active**. Applies to CollectionView.
Pass two views currently owned by the CollectionView to swapChildViews.
## MN0016
behavior-definition-invalid. Status: **retired**. Applies to Behavior, CollectionView, View.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0017
radio-channel-name-required. Status: **active**. Applies to Radio.
Pass a non-empty channel name when creating or accessing a Radio channel.
## MN0018
ui-reference-invalid. Status: **active**. Applies to Behavior, CollectionView, View.
Use @ui. with a non-empty own key whose value is a string selector, or replace the reference with a literal selector.
## MN0019
handler-not-callable. Status: **active**. Applies to Application, Behavior, CollectionView, MnObject, Region, View.
Provide a function or the string name of a callable method on the binding context.
## MN0020
named-region-not-found. Status: **active**. Applies to View.
Define the named Region before using child-View or Region-removal operations, or use getRegion or hasRegion for optional lookup.
## MN0021
radio-channel-not-found. Status: **active**. Applies to Radio.
Create the named channel with Radio.channel(name) before resetting it, or call Radio.reset() with no arguments to reset all existing channels.
## MN0022
collection-view-empty-view-invalid. Status: **retired**. Applies to CollectionView.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0023
ui-elements-unavailable. Status: **active**. Applies to Behavior, CollectionView, View.
Declare a ui map, then render the View or explicitly bind its UI elements before calling getUI; bind them again before calling getUI after unbinding.
## MN0024
child-container-argument-invalid. Status: **active**. Applies to CollectionView.
Pass nonnegative integer counts. Reducing an empty child container requires an initial value.
## MN0025
child-container-method-not-callable. Status: **retired**. Applies to CollectionView.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0026
entity-event-name-unsafe. Status: **active**. Applies to Application, Behavior, CollectionView, MnObject, Region, View.
Rename an own __proto__ entry in an entity-event map before binding or selectively unbinding it.
## MN0027
feature-name-invalid. Status: **retired**. Applies to Behavior, CollectionView, View.
The v5 feature registry is removed. Configure child event prefixes per View, trigger behavior per trigger, and application values through State or explicit configuration.
## MN0028
region-destroyed-operation. Status: **retired**. Applies to Region.
Calls to show, empty, or reset after Region destruction are lifecycle-safe no-ops. Use a live Region when the operation must take effect.
## MN0029
view-destroyed-set-element. Status: **retired**. Applies to CollectionView, View.
Calls to setElement after View or CollectionView destruction begins are lifecycle-safe no-ops. Use a live instance when element replacement must take effect.
## MN0030
region-registration-conflict. Status: **active**. Applies to Region, View.
Register a live, unowned Region under an unused name; remove an existing named Region before replacing it and use a fresh Region instance for a different owner.
## MN0031
application-registration-conflict. Status: **active**. Applies to Application.
Register a live, unowned Application instance under an unused non-empty string name; use hasChildApp before constructing a dynamic child when allocation must be avoided.
## MN0032
region-name-invalid. Status: **active**. Applies to View.
Pass a non-empty string name to a named Region operation.
## MN0033
merge-options-keys-invalid. Status: **retired**. Applies to Application, Behavior, CollectionView, MnObject, Region, View.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0034
state-key-invalid. Status: **retired**. Applies to StateApi.
The concrete v5 alpha State key validation is removed. Use the selected source's native key contract.
## MN0035
state-ownership-conflict. Status: **retired**. Applies to Behavior, CollectionView, MnObject, View.
The concrete v5 alpha State ownership rule is removed. Supplied sources are borrowed and may be shared by multiple owners; createState results are owned and disposed by their owner.
## MN0036
event-delegator-contract-invalid. Status: **retired**. Applies to Behavior, CollectionView, View.
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
## MN0037
adapter-observation-unsupported. Status: **active**. Applies to Application, Behavior, CollectionView, MnObject, View.
Configure a StateApi or DataApi that can observe the selected source, or remove the declarative event map.
## MN0038
adapter-cleanup-invalid. Status: **retired**. Applies to Application, Behavior, CollectionView, MnObject, View.
DataApi and StateApi adapters must return cleanup functions. Core no longer wraps or validates cleanup on each registration.
## MN0039
collection-data-contract-invalid. Status: **active**. Applies to CollectionView.
Return an ordered array with unique stable keys and emit a valid reorder, reset, or update structural record.
## MN0040
private-framework-member-access. Status: **active**. Applies to Application, Behavior, CollectionView, MnObject, Region, View.
Use the documented public Marionette API instead of reading or calling this private framework member.
[Canonical source](/docs/markdown/docs/api/errors.md) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0001
Canonical URL: https://marionettejs.com/errors/MN0001/
Markdown URL: https://marionettejs.com/errors/MN0001.md
Reading SHA-256: 79c8fed93a9cc9a4ed5b01653c9fc635fc6c42593136423efa9b4b8902e90398
# MN0001: view el must be dom element
Status: retired
Reported by: runtime
Objects: CollectionView, View
Category: dom
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[CollectionView](/docs/api/collection-view/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0002
Canonical URL: https://marionettejs.com/errors/MN0002/
Markdown URL: https://marionettejs.com/errors/MN0002.md
Reading SHA-256: b26b183f6b7beb9f31c59a62bf0acc9cdbb24c4b1daa9c6e068d77cef48367e5
# MN0002: region el type invalid
Status: retired
Reported by: runtime
Objects: Region
Category: dom
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Region](/docs/api/region/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0003
Canonical URL: https://marionettejs.com/errors/MN0003/
Markdown URL: https://marionettejs.com/errors/MN0003.md
Reading SHA-256: 39127beb33558f73a682a86205cd332afd2cb89a701946cad57afda0395e1d4f
# MN0003: view already owned
Status: active
Reported by: runtime
Objects: Application, CollectionView, Region, View
Category: ownership
Severity: error
## Remediation
Use the owning Application to display its prepared root. Detach a displayed view from its Region or CollectionView before adopting it elsewhere, or create a new view instance.
[Application](/docs/api/application/) · [CollectionView](/docs/api/collection-view/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0004
Canonical URL: https://marionettejs.com/errors/MN0004/
Markdown URL: https://marionettejs.com/errors/MN0004.md
Reading SHA-256: 5c8156532d9fd68d9609a9e71e7de67002ed5764e934e8fb448ffb9d1d0033d6
# MN0004: region el required
Status: active
Reported by: runtime
Objects: Region
Category: dom
Severity: error
## Remediation
Configure the Region with an el selector or DOM element before using it.
[Region](/docs/api/region/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0005
Canonical URL: https://marionettejs.com/errors/MN0005/
Markdown URL: https://marionettejs.com/errors/MN0005.md
Reading SHA-256: 341171172adadb724d25080182575e82c79f610ee5e9f513c5525167b104677d
# MN0005: region el not found
Status: active
Reported by: runtime
Objects: Region
Category: dom
Severity: error
## Remediation
Render the parent View before direct selector-backed Region operations, ensure the selector resolves within its parent element, or explicitly allow a missing element where supported.
[Region](/docs/api/region/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0006
Canonical URL: https://marionettejs.com/errors/MN0006/
Markdown URL: https://marionettejs.com/errors/MN0006.md
Reading SHA-256: 6500a2b9380e2dc20ffea91b7a22d9583a03326671a4040ea2ca2cec6a87706c
# MN0006: region view required
Status: retired
Reported by: runtime
Objects: Region
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Region](/docs/api/region/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0007
Canonical URL: https://marionettejs.com/errors/MN0007/
Markdown URL: https://marionettejs.com/errors/MN0007.md
Reading SHA-256: 9b959f917f2414d4fe9308d587b300fbe76a7307d8e4cb0335b5c0113ae6773c
# MN0007: region view destroyed
Status: active
Reported by: runtime
Objects: Application, Region, View
Category: lifecycle
Severity: error
## Remediation
Create a new View instance instead of attempting to show a destroyed view.
[Application](/docs/api/application/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0008
Canonical URL: https://marionettejs.com/errors/MN0008/
Markdown URL: https://marionettejs.com/errors/MN0008.md
Reading SHA-256: bb69bcaf747c0eb94cbe811fb56d6b09d14a1b6b47bdb0fe4f6919e8a35652f5
# MN0008: region definition invalid
Status: retired
Reported by: runtime
Objects: Application, Region, View
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Application](/docs/api/application/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0009
Canonical URL: https://marionettejs.com/errors/MN0009/
Markdown URL: https://marionettejs.com/errors/MN0009.md
Reading SHA-256: a8600f8f3f2f2f48043be0d74883df3f937fe02e20fb94d6a316976c032e110d
# MN0009: event bindings invalid
Status: retired
Reported by: runtime
Objects: Application, Behavior, CollectionView, MnObject, Region, View
Category: communication
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0010
Canonical URL: https://marionettejs.com/errors/MN0010/
Markdown URL: https://marionettejs.com/errors/MN0010.md
Reading SHA-256: 73354740eb6ee660b6e825d9e6e84e4f674e40564a9e14b0018631054b0905ca
# MN0010: request bindings invalid
Status: retired
Reported by: runtime
Objects: Application, Behavior, CollectionView, MnObject, Region, View
Category: communication
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0011
Canonical URL: https://marionettejs.com/errors/MN0011/
Markdown URL: https://marionettejs.com/errors/MN0011.md
Reading SHA-256: 30e535d95deb494c0efb99cccb1593620e1091a5fac24f08530b03ea2f74b6b2
# MN0011: collection view child view required
Status: active
Reported by: runtime
Objects: CollectionView
Category: configuration
Severity: error
## Remediation
Configure childView with a View class or a function that returns a View class.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0012
Canonical URL: https://marionettejs.com/errors/MN0012/
Markdown URL: https://marionettejs.com/errors/MN0012.md
Reading SHA-256: 798b60fcdf0d197f47d2781d7a0d44d4bfcbb2607f317ba7278e02cc4a9df70f
# MN0012: collection view child view invalid
Status: retired
Reported by: runtime
Objects: CollectionView
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0013
Canonical URL: https://marionettejs.com/errors/MN0013/
Markdown URL: https://marionettejs.com/errors/MN0013.md
Reading SHA-256: 22375f8092ca36ea080cd54b0e10cbbb6666ef9f58bc3af7357dd73f8d59677e
# MN0013: collection view container not found
Status: active
Reported by: runtime
Objects: CollectionView
Category: dom
Severity: error
## Remediation
Ensure childViewContainer resolves to an element within the rendered CollectionView.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0014
Canonical URL: https://marionettejs.com/errors/MN0014/
Markdown URL: https://marionettejs.com/errors/MN0014.md
Reading SHA-256: 972f45f5e46ff4bbb5294648247c387d51092cf69b875d0ea10602b3ae3e02ab
# MN0014: collection view filter invalid
Status: retired
Reported by: runtime
Objects: CollectionView
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0015
Canonical URL: https://marionettejs.com/errors/MN0015/
Markdown URL: https://marionettejs.com/errors/MN0015.md
Reading SHA-256: 8266bb5f6af078470f64145c960a17389925763e5207ab2a35d2868df8656237
# MN0015: collection view swap non children
Status: active
Reported by: runtime
Objects: CollectionView
Category: ownership
Severity: error
## Remediation
Pass two views currently owned by the CollectionView to swapChildViews.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0016
Canonical URL: https://marionettejs.com/errors/MN0016/
Markdown URL: https://marionettejs.com/errors/MN0016.md
Reading SHA-256: 23b0919bba2428a35c3f6dab0c9fb716e1f3fc6cfd5127a3a208633a48085b16
# MN0016: behavior definition invalid
Status: retired
Reported by: runtime
Objects: Behavior, CollectionView, View
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0017
Canonical URL: https://marionettejs.com/errors/MN0017/
Markdown URL: https://marionettejs.com/errors/MN0017.md
Reading SHA-256: b826cc7727ff2a703743af1edb2e664d5641ef36bc7d9c6ddffbed7afa4709f3
# MN0017: radio channel name required
Status: active
Reported by: runtime
Objects: Radio
Category: communication
Severity: error
## Remediation
Pass a non-empty channel name when creating or accessing a Radio channel.
[@mnjs/radio: channels and requests](/docs/packages/radio/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0018
Canonical URL: https://marionettejs.com/errors/MN0018/
Markdown URL: https://marionettejs.com/errors/MN0018.md
Reading SHA-256: 41b188f5e187571be992ef5700178c05072358111e662e1317f6d79d79022298
# MN0018: ui reference invalid
Status: active
Reported by: runtime
Objects: Behavior, CollectionView, View
Category: configuration
Severity: error
## Remediation
Use @ui. with a non-empty own key whose value is a string selector, or replace the reference with a literal selector.
[Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0019
Canonical URL: https://marionettejs.com/errors/MN0019/
Markdown URL: https://marionettejs.com/errors/MN0019.md
Reading SHA-256: b04e699657a33db3f82db42a7b9132b9129f4d90e7b4e9518ab761a86bbe8f04
# MN0019: handler not callable
Status: active
Reported by: runtime
Objects: Application, Behavior, CollectionView, MnObject, Region, View
Category: communication
Severity: error
## Remediation
Provide a function or the string name of a callable method on the binding context.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0020
Canonical URL: https://marionettejs.com/errors/MN0020/
Markdown URL: https://marionettejs.com/errors/MN0020.md
Reading SHA-256: cb1238d5195e75eaef50e5f235642d37b1795cf028ab39993b28a5e219159448
# MN0020: named region not found
Status: active
Reported by: runtime
Objects: View
Category: configuration
Severity: error
## Remediation
Define the named Region before using child-View or Region-removal operations, or use getRegion or hasRegion for optional lookup.
[View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0021
Canonical URL: https://marionettejs.com/errors/MN0021/
Markdown URL: https://marionettejs.com/errors/MN0021.md
Reading SHA-256: 0a2b457201265d2613be2fc37e8610be265d1e20e8083c9512ec714907386f47
# MN0021: radio channel not found
Status: active
Reported by: runtime
Objects: Radio
Category: communication
Severity: error
## Remediation
Create the named channel with Radio.channel(name) before resetting it, or call Radio.reset() with no arguments to reset all existing channels.
[@mnjs/radio: channels and requests](/docs/packages/radio/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0022
Canonical URL: https://marionettejs.com/errors/MN0022/
Markdown URL: https://marionettejs.com/errors/MN0022.md
Reading SHA-256: 542c77b5e697ad6d8dc26e1e67625af273fa3cf523228933190aa399b2356c7a
# MN0022: collection view empty view invalid
Status: retired
Reported by: runtime
Objects: CollectionView
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0023
Canonical URL: https://marionettejs.com/errors/MN0023/
Markdown URL: https://marionettejs.com/errors/MN0023.md
Reading SHA-256: c8b31aeae47ea33492a613a48b362294270cd212f19fc714f4534bad14b62043
# MN0023: ui elements unavailable
Status: active
Reported by: runtime
Objects: Behavior, CollectionView, View
Category: lifecycle
Severity: error
## Remediation
Declare a ui map, then render the View or explicitly bind its UI elements before calling getUI; bind them again before calling getUI after unbinding.
[Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0024
Canonical URL: https://marionettejs.com/errors/MN0024/
Markdown URL: https://marionettejs.com/errors/MN0024.md
Reading SHA-256: 6894b53ff4f7d3bc7969e26aeeab4d42d727a39b83e54078087bc33a7a021023
# MN0024: child container argument invalid
Status: active
Reported by: runtime
Objects: CollectionView
Category: configuration
Severity: error
## Remediation
Pass nonnegative integer counts. Reducing an empty child container requires an initial value.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0025
Canonical URL: https://marionettejs.com/errors/MN0025/
Markdown URL: https://marionettejs.com/errors/MN0025.md
Reading SHA-256: 39ddfa7071220abd1aaf06ced53d6b168aa0ceafbc6115248ce8c4d3adbcff44
# MN0025: child container method not callable
Status: retired
Reported by: runtime
Objects: CollectionView
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0026
Canonical URL: https://marionettejs.com/errors/MN0026/
Markdown URL: https://marionettejs.com/errors/MN0026.md
Reading SHA-256: 1dffd6d2de838b8a8f66b473f7cd436ea25eca5a52b29a0182685dd4c77fade8
# MN0026: entity event name unsafe
Status: active
Reported by: runtime
Objects: Application, Behavior, CollectionView, MnObject, Region, View
Category: communication
Severity: error
## Remediation
Rename an own __proto__ entry in an entity-event map before binding or selectively unbinding it.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0027
Canonical URL: https://marionettejs.com/errors/MN0027/
Markdown URL: https://marionettejs.com/errors/MN0027.md
Reading SHA-256: f8182f14f906496be0f64d1e72dd0086b6aecfb42e052c3487b9d220716f30b1
# MN0027: feature name invalid
Status: retired
Reported by: runtime
Objects: Behavior, CollectionView, View
Category: configuration
Severity: error
## Remediation
The v5 feature registry is removed. Configure child event prefixes per View, trigger behavior per trigger, and application values through State or explicit configuration.
[Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0028
Canonical URL: https://marionettejs.com/errors/MN0028/
Markdown URL: https://marionettejs.com/errors/MN0028.md
Reading SHA-256: b42b6da866e55c8a14f2e82793a740badfd8aa8a4adaa753ccffbc2b155cdddb
# MN0028: region destroyed operation
Status: retired
Reported by: runtime
Objects: Region
Category: lifecycle
Severity: error
## Remediation
Calls to show, empty, or reset after Region destruction are lifecycle-safe no-ops. Use a live Region when the operation must take effect.
[Region](/docs/api/region/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0029
Canonical URL: https://marionettejs.com/errors/MN0029/
Markdown URL: https://marionettejs.com/errors/MN0029.md
Reading SHA-256: b4b817dbe783ae01af98479b6a8145a5e6eeece12193896dcd61d26d006a30fb
# MN0029: view destroyed set element
Status: retired
Reported by: runtime
Objects: CollectionView, View
Category: lifecycle
Severity: error
## Remediation
Calls to setElement after View or CollectionView destruction begins are lifecycle-safe no-ops. Use a live instance when element replacement must take effect.
[CollectionView](/docs/api/collection-view/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0030
Canonical URL: https://marionettejs.com/errors/MN0030/
Markdown URL: https://marionettejs.com/errors/MN0030.md
Reading SHA-256: 3c6d80514111fcb315418842a2fb203db40d5b3496048555451d785137f03f14
# MN0030: region registration conflict
Status: active
Reported by: runtime
Objects: Region, View
Category: ownership
Severity: error
## Remediation
Register a live, unowned Region under an unused name; remove an existing named Region before replacing it and use a fresh Region instance for a different owner.
[Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0031
Canonical URL: https://marionettejs.com/errors/MN0031/
Markdown URL: https://marionettejs.com/errors/MN0031.md
Reading SHA-256: e097cbed10a3b7cec5091eddf9f8aebd057d2f8174842b5f3e2bdc2f147ee798
# MN0031: application registration conflict
Status: active
Reported by: runtime
Objects: Application
Category: ownership
Severity: error
## Remediation
Register a live, unowned Application instance under an unused non-empty string name; use hasChildApp before constructing a dynamic child when allocation must be avoided.
[Application](/docs/api/application/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0032
Canonical URL: https://marionettejs.com/errors/MN0032/
Markdown URL: https://marionettejs.com/errors/MN0032.md
Reading SHA-256: b4e03ba07025877db39c56937ae324eba19a80296176e3a90979a2c8c4f35f70
# MN0032: region name invalid
Status: active
Reported by: runtime
Objects: View
Category: ownership
Severity: error
## Remediation
Pass a non-empty string name to a named Region operation.
[View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0033
Canonical URL: https://marionettejs.com/errors/MN0033/
Markdown URL: https://marionettejs.com/errors/MN0033.md
Reading SHA-256: b3d02c0ce0bba7cefd815d48847aeffa90c14cb0a7a9b6179fed11d92b79dd03
# MN0033: merge options keys invalid
Status: retired
Reported by: runtime
Objects: Application, Behavior, CollectionView, MnObject, Region, View
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0034
Canonical URL: https://marionettejs.com/errors/MN0034/
Markdown URL: https://marionettejs.com/errors/MN0034.md
Reading SHA-256: 88c396bd4e7307f0d08b809b16dc9fbe1925741fa7db9227e4f1602dd4d5e2a9
# MN0034: state key invalid
Status: retired
Reported by: runtime
Objects: StateApi
Category: configuration
Severity: error
## Remediation
The concrete v5 alpha State key validation is removed. Use the selected source's native key contract.
[Data and state providers](/docs/api/providers/data/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0035
Canonical URL: https://marionettejs.com/errors/MN0035/
Markdown URL: https://marionettejs.com/errors/MN0035.md
Reading SHA-256: d587de033e6d702c51fc05ddfe3bda82b80f419d46ad4f28caad3c87c4641d85
# MN0035: state ownership conflict
Status: retired
Reported by: runtime
Objects: Behavior, CollectionView, MnObject, View
Category: ownership
Severity: error
## Remediation
The concrete v5 alpha State ownership rule is removed. Supplied sources are borrowed and may be shared by multiple owners; createState results are owned and disposed by their owner.
[Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0036
Canonical URL: https://marionettejs.com/errors/MN0036/
Markdown URL: https://marionettejs.com/errors/MN0036.md
Reading SHA-256: 80ca15d7a0063aaa1c46545e78632104e98bf702f4726b704c121ae480dfd23f
# MN0036: event delegator contract invalid
Status: retired
Reported by: runtime
Objects: Behavior, CollectionView, View
Category: configuration
Severity: error
## Remediation
Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.
[Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0037
Canonical URL: https://marionettejs.com/errors/MN0037/
Markdown URL: https://marionettejs.com/errors/MN0037.md
Reading SHA-256: 520bbe7c18dfb9e96bc1c9c85dd817ab3750e4fd7a80fc7125bd206759a46ecd
# MN0037: adapter observation unsupported
Status: active
Reported by: runtime
Objects: Application, Behavior, CollectionView, MnObject, View
Category: configuration
Severity: error
## Remediation
Configure a StateApi or DataApi that can observe the selected source, or remove the declarative event map.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0038
Canonical URL: https://marionettejs.com/errors/MN0038/
Markdown URL: https://marionettejs.com/errors/MN0038.md
Reading SHA-256: 186091b9b26e7d0f71c6914b3136d2e248070afc12975a176e1a924dda0440d8
# MN0038: adapter cleanup invalid
Status: retired
Reported by: runtime
Objects: Application, Behavior, CollectionView, MnObject, View
Category: configuration
Severity: error
## Remediation
DataApi and StateApi adapters must return cleanup functions. Core no longer wraps or validates cleanup on each registration.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0039
Canonical URL: https://marionettejs.com/errors/MN0039/
Markdown URL: https://marionettejs.com/errors/MN0039.md
Reading SHA-256: 4e5dd45eee28afa4c8fe5759eaaa3923acfbcdf39e4ee81a21a74a116700efa1
# MN0039: collection data contract invalid
Status: active
Reported by: runtime
Objects: CollectionView
Category: configuration
Severity: error
## Remediation
Return an ordered array with unique stable keys and emit a valid reorder, reset, or update structural record.
[CollectionView](/docs/api/collection-view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/MN0040
Canonical URL: https://marionettejs.com/errors/MN0040/
Markdown URL: https://marionettejs.com/errors/MN0040.md
Reading SHA-256: 90ec148884e3dd4afc043db504a8e926624aed8c4e28c129818b2aefaf3a2985
# MN0040: private framework member access
Status: active
Reported by: lint
Objects: Application, Behavior, CollectionView, MnObject, Region, View
Category: configuration
Severity: error
## Remediation
Use the documented public Marionette API instead of reading or calling this private framework member.
[Application](/docs/api/application/) · [Behavior](/docs/api/behavior/) · [CollectionView](/docs/api/collection-view/) · [MnObject](/docs/api/mnobject/) · [Region](/docs/api/region/) · [View](/docs/api/view/)
[Check and debug an application](/docs/tooling/)
[Diagnostic catalog](/errors/index.md) · [Source identity](/docs/manifest.json)
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)
---
Document: errors/index
Canonical URL: https://marionettejs.com/errors/
Markdown URL: https://marionettejs.com/errors/index.md
Reading SHA-256: 0ecd58f2d9c1f40a93f08a98fb90093140446e19656c5458ff934dced2a0360b
# Diagnostic codes
- [MN0001: view el must be dom element](/errors/MN0001.md): retired
- [MN0002: region el type invalid](/errors/MN0002.md): retired
- [MN0003: view already owned](/errors/MN0003.md): active
- [MN0004: region el required](/errors/MN0004.md): active
- [MN0005: region el not found](/errors/MN0005.md): active
- [MN0006: region view required](/errors/MN0006.md): retired
- [MN0007: region view destroyed](/errors/MN0007.md): active
- [MN0008: region definition invalid](/errors/MN0008.md): retired
- [MN0009: event bindings invalid](/errors/MN0009.md): retired
- [MN0010: request bindings invalid](/errors/MN0010.md): retired
- [MN0011: collection view child view required](/errors/MN0011.md): active
- [MN0012: collection view child view invalid](/errors/MN0012.md): retired
- [MN0013: collection view container not found](/errors/MN0013.md): active
- [MN0014: collection view filter invalid](/errors/MN0014.md): retired
- [MN0015: collection view swap non children](/errors/MN0015.md): active
- [MN0016: behavior definition invalid](/errors/MN0016.md): retired
- [MN0017: radio channel name required](/errors/MN0017.md): active
- [MN0018: ui reference invalid](/errors/MN0018.md): active
- [MN0019: handler not callable](/errors/MN0019.md): active
- [MN0020: named region not found](/errors/MN0020.md): active
- [MN0021: radio channel not found](/errors/MN0021.md): active
- [MN0022: collection view empty view invalid](/errors/MN0022.md): retired
- [MN0023: ui elements unavailable](/errors/MN0023.md): active
- [MN0024: child container argument invalid](/errors/MN0024.md): active
- [MN0025: child container method not callable](/errors/MN0025.md): retired
- [MN0026: entity event name unsafe](/errors/MN0026.md): active
- [MN0027: feature name invalid](/errors/MN0027.md): retired
- [MN0028: region destroyed operation](/errors/MN0028.md): retired
- [MN0029: view destroyed set element](/errors/MN0029.md): retired
- [MN0030: region registration conflict](/errors/MN0030.md): active
- [MN0031: application registration conflict](/errors/MN0031.md): active
- [MN0032: region name invalid](/errors/MN0032.md): active
- [MN0033: merge options keys invalid](/errors/MN0033.md): retired
- [MN0034: state key invalid](/errors/MN0034.md): retired
- [MN0035: state ownership conflict](/errors/MN0035.md): retired
- [MN0036: event delegator contract invalid](/errors/MN0036.md): retired
- [MN0037: adapter observation unsupported](/errors/MN0037.md): active
- [MN0038: adapter cleanup invalid](/errors/MN0038.md): retired
- [MN0039: collection data contract invalid](/errors/MN0039.md): active
- [MN0040: private framework member access](/errors/MN0040.md): active
[Canonical source](/docs/markdown/config/diagnostics/catalog.json) · [Source identity](/docs/manifest.json)