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

Rendering and View bindings#

View and CollectionView share the contracts on this page. Their rendering/composition lifecycles remain class-specific. For common object methods, event subscriptions, and state ownership, see common, events, and state.

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 shows the Lit integration, whose ordinary interpolations render values as text.

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:

import { View } from 'marionette';
import LitDomApi from '@mnjs/adapters/dom/lit-html';
import { html } from 'lit-html';

const Greeting = View.extend({
  template: ({ name }) => html`<p>Hello, ${name}</p>`,
});
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. 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.

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.

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() binds current model/collection 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. Call undelegateEntityEvents() before assigning the new source or event map, then call delegateEntityEvents() to observe it. Delegation alone does not release a previous subscription. 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.

These bindings do not own or destroy the model/collection. State bindings have separate ownership and delivery rules: see state.

Child events#

The owning View/CollectionView can handle events from its immediate managed children:

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 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 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.

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 uses top-level setters to configure all relevant default classes together. See runtime configuration for isolated families and setter scope, rendering/DOM providers for authoring interfaces, and data/state providers 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<Receiver, Template, Data, Output>: 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 and data/state providers.