marionette.state
One-way state architecture for a Marionette.js app.
Installation
npm install marionette.state
bower install marionette-state
git clone git://github.com/Squareknot/marionette.state.git
Documentation
Reasoning
A Marionette View is a DOM representation of a Backbone model. When the model updates, so does the view. Here is a quick example:
// Region to attach viewsvar region = el: '#region' ; // Model synced with '/rest-endpoint'var model = url: '/rest-endpoint' ; // View will re-render when the model changesvar View = MnItemView; // Create the viewvar view = model: model ; // Fetch the latest datamodel; // Updating the model later will cause the view to re-render.model;
This is great for views that are only interested in representing simple content. Consider more complex, yet quite common, scenarios:
- A view renders core content but also reacts to user interaction. E.g., a view renders a list of people, but the end user is able to select individal items with a "highlight" effect before saving changes.
- A view renders core content but also depends on external state. E.g., a view renders a person's profile, but if the profile belongs to the authenticated user then enable "edit" features.
- Multiple views share a core content model but each have unique view states. E.g., multiple views render a user profile object, but in completely different ways that require unique view states: an avatar beside a comment, a short bio available when hovering over an avatar, a full user profile display.
Common solutions:
- Store view states in the core content model, but override
toJSON
to avoid sending those attributes to the server. - Store view states in the core content model shared between views, but avoid naming collisions or other confusion (which view is "enabled"?).
- Store view states directly on the view object and follow each "set" with "if different" statements so you know when a state has changed.
Each of these solutions works up until a point, but side effects mount as complexity rises: Logic-heavy views, views unreliably reflecting state changes, models doing too much leading to excessive re-renders, accidentally transmitting state data to server on save.
Separating state into its own entity and then maintaining that entity with one-way data binding solves each of these problems without the side effects of other solutions. It is a pattern simple enough to implement using pure Marionette code, but this library seeks to simplify the implementation further by providing a state toolset.
Mn.State
allows a view to seamlessly depend on any source of state while keeping state logic self-contained and eliminates the temptation to pollute core content models with view-specific state. Best of all, Mn.State
does this by providing declarative and expressive tools rather than over-engineering for every use case, much like the Marionette library itself.
Examples
In each of these examples, views are demonstrated without core content models for simplicity. This emphasizes that state management is occurring independently from renderable core content. Adding core content models should be familiar to any Marionette developer.
Stateful View
From time to time, a view needs to support interactions that only affect itself. On refresh, these states are reset. In this example, a transient view spawns it own, also transient, State.
State flow for a simple interactive view:
- A view is rendered with some initial state.
- The user interacts with the view, triggering a state change.
- The view reacts by updating the DOM according to the new state.
Solved with Mn.State:
- View renders initial View State.
- View triggers events that are handled by View State.
- View State reacts to view events, updating its attributes.
- View reacts to state changes, updating the DOM.
// Listens to view events and updates view state attributes.var ToggleState = MnState; // A toggle button that is alternately "active" or not.var ToggleView = MnItemView; var toggleView = ; var appRegion = el: '#app-region' ;appRegion;
View Directly Dependent upon Application State
Relatively often, it is convenient for a view to depend on long-lived application state. This example uses authentication status to demonstrate binding a view directly to the state of the application.
State flow for a simple view that depends directly upon long-lived application state:
- A view is rendered with current app state.
- The view triggers an app-level event, resulting in an app state change.
- The view reacts to app state changes, updating the DOM.
Solved with Mn.State:
- View renders initial App State.
- View trigger events that are handled by App State.
- App State reacts to events, updating its attributes.
- View reacts to App State changes, updating the DOM.
// Listens to application level events and updates app State attributes.var AppState = MnState; // Alternately a login or logout button depending on app authentication state.var ToggleAuthView = MnItemView; var appChannel = Radio;var appState = component: appChannel ;var toggleAuthView = appState: appState ; var appRegion = el: '#app-region' ;appRegion;
View Indirectly Dependent upon Application State
Sometimes a view has its own, transient, internal state that is related to long-lived application state. While this particular example doesn't require that layer of indirection to achieve its goal (a Login/Logout button), the goal here is to demonstrate all that is necessary to achieve two tiers of State.
State flow for a simple view that depends indirectly on long-lived application state:
- View is rendered with initial state dependent upon current app state.
- View triggers an app-level event, resulting in an app state change.
- App state change results in a view state change.
- View reacts to view state changes, updating the DOM.
Solved with Mn.State:
- View State synchronizes with App State.
- View renders initial View State.
- View triggers events that are handled by App State.
- App State reacts to events, updating its attributes.
- View State reacts to App State changes, updating its attributes.
- View reacts to View State changes, updating the DOM.
// Listens to application level events and updates state attributes.var AppState = MnState; // Syncs with application State.var ToggleAuthState = MnState; // Alternately a login or logout button depending on app authentication state.var ToggleAuthView = MnItemView; var appChannel = Radio;var appState = component: appChannel ;var toggleAuthView = appState: appState ; var appRegion = el: '#app-region' ;appRegion;
View Indirectly Dependent upon Application State with Business Service
An application with a business layer for handling persistence to a server is just one more step--the addition of an app controller that responds to Radio requests.
State flow for a simple view that depends indirectly on long-lived application state connected to a business service:
- View is rendered with initial state dependent upon current app state.
- View makes an app-level request, affecting business objects and resulting in an app state change.
- App state change results in a view state change.
- View reacts to view state changes, updating the DOM.
Solved with Mn.State:
- View State synchronizes with App State.
- View renders initial View State.
- View makes requests that are handled by App Controller.
- App Controller modifies business objects and triggers app events.
- App State reacts to app events, updating its attributes.
- View State reacts to App State changes, updating its attributes.
- View reacts to View State changes, updating the DOM.
// Listens to application level events and updates state attributes.var AppState = MnState; // App controller fields application level requests and triggers application events.var AppController = MnObject; // Syncs with application State.var ToggleAuthState = MnState; // Alternately a login or logout button depending on app authentication state.var ToggleAuthView = MnItemView; var appController = ;var appState = appController;var toggleAuthView = appState: appState ; var appRegion = el: '#app-region' ;appRegion;
Sub-Applications
Within an application modularized into sub-applications, state can cascade from app -> sub-app -> view. In this particular configuration, Radio can be used to make both sub-application and application requests.
Sub-Views
Within a deeply nested, complex view that requires a deeper layer of state, perhaps for child views within a CollectionView, state can cascade from app -> view -> sub-view.
State API
Initialization Properties
defaultState
Optional default state attributes hash. These will be applied to the underlying model when it is initialized.
componentEvents
Optional hash of component event bindings. Enabled by passing {component: <Evented object>}
as an initialization option.
modelClass
Optional Backbone.Model class to instantiate, otherwise a pure Backbone.Model will be used.
Initialization Options
initialState
Optional initial state attributes. These attributes are combined with defaultState
for initializing the underlying state model, and become the basis for future reset()
calls.
component
Optional evented object to which to bind lifecycle and events. The componentEvents
events hash is bound to component
. When component
fires 'destroy'
the State instance is also destroyed, unless {preventDestroy: true}
is also passed.
preventDestroy
Only applies when component
is provided. By default, the State instance will destruct when component
fires 'destroy'
, but {preventDestroy: true}
will prevent this behavior.
Properties
attributes
Proxy to model attributes
property. This permits a State instance to be used in place of a Backbone.Model within a Marionette view.
Methods
getModel()
Returns the underlying model.
getInitialState()
A clone of model's attributes at initialization.
get(attr)
Proxy to model get(attr)
.
set(key, val, options)
Proxy to model set(key, val, options)
.
reset(attrs, options)
Resets model to its attributes at initialization. If any attrs
are provided, they will override the initial value. options
are passed to the underlying model #set
.
changedAttributes()
Proxy to model changedAttributes()
.
previousAttributes()
Proxy to model previousAttributes()
.
hasAnyChanged(...attrs)
Determine if any of the passed attributes were changed during the last modification.
var StatefulView = MnItemView;
toJSON()
Proxy to model.toJSON()
.
bindComponent(component, options)
Bind componentEvents
to component
and self-destruct when component
fires 'destroy'
. This prevents a state from outliving its component and causing a memory leak. To prevent self-destruct behavior, pass {preventDestroy: true}
as an option.
unbindComponent(component)
Unbind componentEvents
from component
and stop listening to component 'destroy'
event.
syncEntityEvents(entity, bindings, event)
See syncEntityEvents
)
var State = MnState
See State Functions API #syncEntityEvents.
Events
A State instance proxies events from its underlying model, substituting the model argument for the State instance.
'change' (state, options)
Fired when any attributes are updated, once per #set
call.
'change:{attribute}' (state, value, options)
Fired when a specific attribute is updated.
State Functions API
sync(target, entity, bindings)
Calls Backbone entity event handlers in bindings
located on target
with standard Backbone event arguments. This is useful to apply event handlers without waiting for a change, such as for synchronization purposes. The following event handlers will be synced, and no others:
Backbone.Model
'all' (model)
'change' (model)
'change:{attribute}' (model, value)
Backbone.Collection
'all' (collection)
'reset' (collection)
'change' (collection)
Notably, Collection 'add'
and 'remove'
event handlers will not be synchronized, because 'add'
and 'remove'
do not have a backing value (the added or removed element is not known until the event occurs). However, 'add remove reset'
is syncable and also tracks with changes in the collection.
hasAnyChanged(entity, ...attrs)
Determine if any of the passed attributes were changed during the last modification.
var MyView = MnItemView;
syncEntityEvents(target, entity, bindings, event)
Registers event bindings bindings
with entity
using Mn.bindEntityEvents
using target
as context, and then synchronizes using sync()
. If event
is supplied, rather than syncing immediately, syncing will occur on every firing of event
by target
. This is useful for syncing a model to DOM within a View, for example. The standard event options
object will contain the value syncing: true
to indicate the call was made during a sync rather than an entity event.
Example without syncEntityEvents
var View = MnItemView;
Example with syncEntityEvents
var View = MnItemView
Handling Multiple change:{attribute} Events
Just like Backbone, all handlers will be called for all supported events on sync. In the following binding, onChangeFooBar
will be called twice on sync--once with the value of foo
and once with the value of bar
, similarly to if both foo and bar had changed at once.
modelEvents: 'change:foo change:bar': 'onChangeFooBar'
Because handlers called multiple times for a single sync is probably not desired behavior, the best practise to synchronize multiple attributes with a single handler is the same as standard Backbone: Listen for change
and check model.changed
for the presence particular attributes. The only addition is to check for whether handler was called during a sync.
modelEvents: 'change': 'onChange' { var model = ; MnState;} { var syncOrChange = optionssyncing || MnState; if !syncOrChange return; // Either syncing or foo/bar have changed}
When synchronizing with a State instance, this can become:
stateEvents: 'change': 'onChange' { var state = ; MnState;} { var syncOrChange = optionssyncing || state; if !syncOrChange return; // Either syncing or foo/bar have changed}