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

View#

API index · Region · Shared View runtime

A View owns one fixed DOM element, renders supplied data, and can compose child Views through named Regions. Use it for an individual control or a layout. CollectionView manages a set of children instead.

Import View from marionette. Shared rendering, DOM, UI, data bindings, and child forwarding are defined in View runtime. Inherited common methods, events, and state 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 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.

For shared records or selection that change over time, receive an observable source and use model/collection bindings or state bindings. 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.

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.

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:

import { View, type ViewConfiguration } from 'marionette';

const el = document.createElement('section');
el.innerHTML = '<h2>Preview</h2><div class="content"></div>';
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#

For template selection, serialization, renderAttributes, and renderer customization, see rendering contracts. 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. 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.

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.

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. The current missing-selector limitation can also make this reset fail after an allowed missing-element lookup.

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.

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.

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.

Configuration and inherited API#

The class methods setRenderer, setDomApi, setDataApi, setStateApi, and setEventDelegator return the receiving class. Their configuration contracts 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: getOption, mergeOptions, normalizeMethods, bindEvents, unbindEvents, bindRequests, unbindRequests, extend and constructor inheritance.
• Events: on, once, off, trigger, triggerMethod, listenTo, listenToOnce, stopListening.
• State: createState, getState, state, stateEvents, and the State provider.
• View runtime: $, getUI, UI normalization/binding, DOM/entity delegation, template serialization, attachElContent, root attributes, Behaviors, and child events.

TypeScript#

ViewConfiguration describes recognized options. ViewInstance<Options, State, Query> describes instances; Query defaults to ArrayLike<Element> and follows the DOM provider. ViewConstructor<Props, Args, State, Statics, Query> 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.