Markdown & source details
5.1.0 · stable release (published on npm) · 86ee0599 snapshot. Reading source: 4e5c36d9e8b19ee4dcab2842e3bca6182be0c5a6. Match APIs to your installed version.
On this page
Setup and data#
Continue from the quick start. This page adds @mnjs/data for observable data and retains the @mnjs/html rendering configuration; those are independent integration choices. Core framework methods are covered in the API reference.
Add observable data#
From the example project, install the current data package. Its nonoptional Utils
peer accepts ^5.0.1, using the same instance as core and Radio rather than a
private copy; Data does not require an identical core version:
npm install --ignore-scripts --save-exact @mnjs/data@5.1.1
Use a different source with its compatible provider when it better fits your application. Views using plain template data do not require this package.
Configure once#
Import a setup module before constructing Applications or Views:
// setup.js
import { setDataApi, setDomApi, setStateApi } from 'marionette';
import { DataApi, StateApi } from '@mnjs/data';
import HtmlDomApi from '@mnjs/html/marionette';
setDataApi(DataApi);
setStateApi(StateApi);
setDomApi(HtmlDomApi);
These setters configure the default class family. Standalone reference examples instead use View.extend(...).setDomApi(...) or .setDataApi(...) to keep their configuration local to a subclass. Both scopes are supported; configure the chosen scope before constructing instances. Use runtime configuration for class-specific or isolated setup, and the provider references when connecting a different data solution. DataApi connects Models and Collections to Views; StateApi connects observable state to state owners. The renderer calls a template function with its data, and the @mnjs/html DOM adapter places the result in the View's element.
import './setup.js';
import { View } from 'marionette';
import { html } from '@mnjs/html';
export const DetailView = View.extend({
template: ({ title, description }) => html`
<h3>${title}</h3>
<p>${description}</p>
`,
});
Ordinary @mnjs/html interpolation renders these values as text, including characters such as <. No HTML escaping helper is needed. A View supplied with a Model receives its attributes as template data.
A provider implements a Marionette contract such as DataApi, StateApi or DomApi. An adapter connects a particular library to that contract; for example, HtmlDomApi connects @mnjs/html rendering. Installing an adapter does not configure it.
Observable data and API access#
@mnjs/data provides local observable Models and Collections. Use it alongside an API layer for fetching and persistence, or replace it with another data solution and the corresponding Marionette integration. Models and Collections do not provide an HTTP client, server synchronization, or a complete application data architecture.
For initial feature data, an Application can import its API module directly, await the request in prepareStart, and return a Collection built from the response attributes. The successful result reaches onStart. If the API layer already supplies a compatible observable source, use it directly.
import { Model, Collection } from '@mnjs/data';
const item = new Model({ id: 'alpha', title: 'First item' });
const items = new Collection([item]);
item.set('title', 'Updated item');
Use Model and Collection for attribute updates, membership, identity, events, and local disposal. A View can observe Model changes through modelEvents; CollectionView observes membership changes through DataApi. Reading data into a template alone does not subscribe to later attribute changes.
Use state ownership when an Application or View needs its own observable state. With StateApi configured, createState can return a Model whose disposal belongs to the owner. Passing { state } borrows an existing source instead.