Demo

Try them

Name (StringCell)	Age (IntegerCell)	Birthday (DateCell)	Gender (SelectCell)	Alive (BooleanCell)
URL (UriCell)	Email (EmailCell)	Next Delivery Time (DateTimeCell)	His Local Time (TimeCell)	Change in Wallet (NumberCell)

Note: Backgrid.js and its author are not associated with Santa and santaclaus.com in any way.

Configuring Cells

While many built-in cells provide reasonable defaults, you may choose to configure them to suit your own needs.

Cell types that you are most likely to configure are the NumberCell, DatetimeCell and SelectCell classes. Once configured, you may use them as the cell attribute values in column definitions.

var grid = new Backgrid.Grid({ columns: [{ name: "id", label: "ID", editable: false, // Dynamically defines a new cell type with new defaults. // ID is displayed as an integer without ','s. cell: Backgrid.IntegerCell.extend({ orderSeparator: '' }) }, { name: "lastaccessed", label: "Last Login Time", editable: false, cell: Backgrid.DatetimeCell.extend({ includeMilli: true }) }, { name: "gender", label: "Gender", cell: Backgrid.SelectCell.extend({ // It's possible to render an option group or use a // function to provide option values too. optionValues: [["Male", "m"], ["Female", "f"]] }) }], collection: col });

Pro Tip

SelectCell treats all option values as strings by default, if you need to persist a different type of values into your model, you should extend SelectCell to provide your own formatter.

See the JSDoc for the various Cell classes for details on what you can configure using this method.

Custom Cell

If the built-in and extension cell classes are not enough for you, you may choose to create your own cell class and supply it to a column definition.

If your custom cell will still use a <input type="text" /> like the predefined ones for editing, you may choose to subclass Cell or one of the predefined classes and simply define a className and a formatter. In fact, most of the core cell classes are done this way.

// This is the verbatim Backgrid.StringCell definition var StringCell = Backgrid.StringCell = Cell.extend({ // Cell default class names are the lower-cased and dasherized // form of the the cell class names by convention. className: "string-cell", formatter: { fromRaw: function (rawData) { return rawData; }, toRaw: function (formattedData) { return formattedData; } } });

If your cell class will render differently in display mode, you may simply override Cell#render() in your subclass.

Custom CellEditor

Advanced Usage

Some cell types, like the TextCell extension, may only make sense if the editor is rendered in a modal dialog or a form element in a different part of the page. In that case the default InputCellEditor, which renders a <input type="text" />, will not be suitable and a new CellEditor must be defined.

A custom cell editor should subclass CellEditor as it defines a number of required parameters in its initializer and clean up operations that are necessary for most cell editors. When a cell class enters edit mode, a new editor instance is constructed by given it the required parameters, and then a Backbone event edit is fired from the cell instance itself. A custom cell class can act on this event to do anything before the cell editor is rendered.

Once the cell has entered edit mode, a Backbone event editing is fired. A custom cell class can then act on it to do anything after the cell editor has been rendered, e.g. placing the focus inside the editor.

During editing, if an error is encountered (see the formatter protocol below), a cell editor should fire a Backbone event error so that listeners—usually a cell instance—can respond appropriately. When editing is done, a cell editor should fire a Backbone done event. A cell should be listening to this event so it can remove its editor and re-render itsef in display mode.

Truely Advanced Hacking

At the most basic level, Cells and CellEditors are simply Backbone.View classes that are guaranteed to be given a number of parameters when constructed by Row. You can use any Backbone.View as your Cell and CellEditor.

Backbone.ModelFactory

Provides a factory for generating model constructors which will never produce multiple instances of a model with the same unique identifier. It allows a developer to manage model sharing between views more easily by maintaining an internal cache of model instances based on the value of their idAttribute property.

In short, when you create a new instance of a model created with Backbone.ModelFactory and give it an id it will never create duplicate instances of the same model with a given id.

var user1 = new User({id: 1});
var user2 = new User({id: 1});
var user3 = new User({id: 2});
console.log(user1 === user2); // true
console.log(user3 === user1); // false

Inclusion

Backbone.ModelFactory supports three methods of inclusion.

1. Node:

   var Backbone = require('backbone-model-factory');
   

2. AMD/RequireJS:

   require(['backbone-model-factory'], function (Backbone) {
    // Do stuff...
   });
   

3. Browser Globals:

   <script src="path/to/backbone.js"></script>
   <script src="path/to/backbone-model-factory.js"></script>
   

Usage

Rather than extending Backbone.Model, constructors are created by a call to Backbone.ModelFactory. Instead of this:

var User = Backbone.Model.extend({
 defaults: {
 firstName: 'John',
 lastName: 'Doe'
 }
});

...do this:

var User = Backbone.ModelFactory({
 defaults: {
 firstName: 'John',
 lastName: 'Doe'
 }
});

Backbone.ModelFactory also supports inheritance, so model constructors can extend each other by providing a model constructor as the first argument:

var Admin = Backbone.ModelFactory(User, {
 defaults: {
 isAdmin: true
 }
});

Consequences of Extending Models

Models created with Backbone.ModelFactory will not share their unique-enforcement capabilities with models which they extend or which extend them. For example, using the User and Admin models above giving each the same ID would not result in the same object:

var user = new User({id: 1});
var admin = new Admin({id: 1});
console.log(user === admin); // false

The ability to share instances between models in an inheritance chain is a feature which is actively being considered, but it leaves a lot of open questions.

Tests

Inclusion

There are 3 files in /test/inclusion and they account for the 3 supported methods of including this module. To execute these tests, simply open the HTML files in a browser or install the npm module backbone and run node node-module.js.

Unit

Mocha unit tests exist in test/test.js. To run, simply do mocha from the project root.

Inspriation

This is inspired by SoundCloud's approach detailed in Building the Next SoundCloud under "Sharing Models between Views."

Backbone.Marionette

Make your Backbone.js apps dance with a composite application architecture!

About Marionette

Backbone.Marionette is a composite application library for Backbone.js that aims to simplify the construction of large scale JavaScript applications. It is a collection of common design and implementation patterns found in the applications that I (Derick Bailey) have been building with Backbone, and includes various pieces inspired by composite application architectures, such as Microsoft's "Prism" framework.

App Architecture On Backbone's Building Blocks

Backbone provides a great set of building blocks for our JavaScript applications. It gives us the core constructs that are needed to build small apps, organize jQuery DOM events, or create single page apps that support mobile devices and large scale enterprise needs. But Backbone is not a complete framework. It's a set of building blocks. It leaves much of the application design, architecture and scalability to the developer, including memory management, view management, and more.

Marionette brings an application architecture to Backbone, along with built in view management and memory management. It's designed to be a lightweight and flexible library of tools that sits on top of Backbone, providing a framework for building scalable application.

Like Backbone itself, you're not required to use all of Marionette just because you want to use some of it. You can pick and choose which features you want to use, when. This allows you to work with other Backbone frameworks and plugins very easily. It also means that you are not required to engage in an all-or-nothing migration to begin using Marionette.

Key Benefits

• Scale applications out with modular, event driven architecture
• Sensible defaults, such as using Underscore templates for view rendering
• Easy to modify to make it work with your applicaton's specific needs
• Reduce boilerplate for views, with specialized view types
• Build on a modular architecture with an Application and modules that attach to it
• Compose your application's visuals at runtime, with Region and Layout
• Nested views and layouts within visual regions
• Built-in memory management and zombie killing in views, regions and layouts
• Built-in event clean up with the EventBinder
• Event-driven architecture with the EventAggregator
• Flexible, "as-needed" architecture allowing you to pick and choose what you need
• And much, much more

Compatibility And Requirements

Backbone.Marionette currently works with the following libraries:

Marionette has not been tested against any other versions of these libraries. You may or may not have success if you use a version other than what it listed here.

While support for Zepto and Enderjs has been added, it is not officially tested against these libraries at this time.

Marionette makes use of jQuery's Deferred objects and, as such, will need supported methods in replacement libraries. Zepto users can use @Mumakil's Standalone-Deferred or @sudhirj's simply-deferred. Enderjs users, please let us know of how you solve any compatibility issues.

Source Code And Downloads

You can download the latest builds directly from the "lib" folder above.
For more information about the files in this folder, or to obtain an archive containing all Marionette dependencies (including Underscore, Backbone, etc), please see the downloads section on the website.

Available Packages

Marionette is unofficially available from various package management systems, such as RubyGems, Node Package Manager, Nuget, etc. These packages are maintained by the community and are not part of the core Backbone.Marionette code.

Documentation

The primary documentation is split up in to multiple files, due to the size of the over-all documentation. You can find these files in the /docs folder, or use the links below to get straight to the documentation for each piece of Marionette.

Marionette's Pieces

These are the strings that you can pull to make your puppet dance:

• Marionette.Application: An application object that starts your app via initializers, and more
• Marionette.AppRouter: Reduce your routers to nothing more than configuration
• Marionette.Callbacks: Manage a collection of callback methods, and execute them as needed
• Marionette.CollectionView: A view that iterates over a collection, and renders individual ItemView instances for each model
• Marionette.Commands: An extension of Backbone.Wreqr.Commands, a simple command execution framework
• Marionette.CompositeView: A collection view and item view, for rendering leaf-branch/composite model hierarchies
• Marionette.Controller: A general purpose object for controlling modules, routers, view, and implementing a mediator pattern
• Marionette.EventAggregator: An extension of Backbone.Events, to be used as an event-driven or pub-sub tool
• Marionette.functions: A suite of helper functions and utilities for implementing common Marionette behavior in your objects
• Marionette.ItemView: A view that renders a single item
• Marionette.Layout: A view that renders a layout and creates region managers to manage areas within it
• Marionette.Module: Create modules and sub-modules within the application
• Marionette.Region: Manage visual regions of your application, including display and removal of content
• Marionette.Renderer: Render templates with or without data, in a consistent and common manner
• Marionette.RequestResponse: An extension of Backbone.Wreqr.RequestResponse, a simple request/response framework
• Marionette.TemplateCache: Cache templates that are stored in <script> blocks, for faster subsequent access
• Marionette.View: The base View type that other Marionette views extend from (not intended to be used directly)

The following have been extracted in to separate plugins:

Please note that this is documentation is rather dry - it's meant to be a reference for those that just need a reference. If you're looking for an introduction and/or examples on how to get started, please see the Wiki.

The Wiki: Sample Apps, Tutorials, And Much More

A wiki is an important aspect of a thriving community, as it provides a place for the community to contribute ideas, examples, answer frequently asked questions, and more. If you're looking for community-driven information, examples that go beyond the dry technical documentation, or want to contribute your own ideas and examples to the community, please see the wiki page.

Annotated Source Code

In addition to this readme, I've commented the source code quite heavily and run it through Docco as part of my build process. This produces a nicely formatted, annotated source code as documenation file.

You can read the annotated for all the detail of how Marionette works, and advice on which methods to override when.

Donations

Marionette needs your support, but not everyone can offer assitance with code, bug submissions, and answering questions. If you're using Marionette and you're finding that it is saving you as much time and effort as I believe it does, then please consider financial support for the project.

Donate via PayPal

Donate via GitTip

GitTip

How To Contribute

If you would like to contribute to Marionette's source code, please read the guidelines for pull requests and contributions. Following these guidelines will help make your contributions easier to bring in to the next release.

Help Is Just A Click Away

#Marionette on FreeNode.net IRC

Join the #marionette channel on FreeNode.net to ask questions and get help.

Get announcements for new releases, share your projects and ideas that are using Marionette, and join in open-ended discussion that does not fit in to the Github issues list or StackOverflow Q&A.

For help with syntax, specific questions on how to implement a feature using Marionette, and other Q&A items, use StackOverflow.

Ask questions about using Marionette in specific scenarios, with specific features. For example, help with syntax, understanding how a feature works and how to override that feature to do what you need or how to organize the different view types to work best with your applications needs.

Questions on StackOverflow often turn in to blog posts and wiki entries.

Report issues with Marionette, submit pull requests to fix problems, or to create summarized and documented feature requests (preferably with pull requests that implement the feature).

Please don't ask questions or seek help in the issues list. There are other, better channels for seeking assistance, like StackOverflow and the Google Groups mailing list.

Lastly, I blog about Marionette on a regular basis, at my LosTechies.com blog.

Release Notes

For change logs and release notes, see the changelog file.

Legal Mumbo Jumbo (MIT License)

Copyright (c) 2012 Derick Bailey; Muted Solutions, LLC

Distributed under MIT license.

Topics will include MVC theory and how to build applications using Backbone's models, views, collections and routers. I'll also be taking you through advanced topics like modular development with Backbone.js and AMD (via RequireJS), solutions to common problems like nested views, how to solve the routing problems with Backbone and jQuery Mobile and a lot more.

Dependencies

Underscore.js

Backbone's only hard dependency. http://underscorejs.org

JSON2.js

Needed if you'd like to parse and serialize JSON in older browsers (read: "Internet Explorer") https://github.com/douglascrockford/JSON-js

jQuery

Recommended for DOM manipulation and Ajax. http://jquery.com

Zepto

Recommended as a jQuery alternative for mobile apps http://zeptojs.com

Model

Backbone Forms

Generate customisable forms from your model schema. Features include custom editors, nested forms, editable lists and validation.

backbone-deep-model

Improved support for models with nested attributes. Get and set attributes and listen to changes on them using a path, e.g. get('user.address.ln1').

Backbone-Nested

A plugin to make Backbone keep track of nested attributes.

Backbone.Memento

Create undo points to store / restore your model's state.

Get the code and read the documentation:

Backbone.actAs.Mementoable

Memento pattern realization for Backbone.js models with more flexible API than in Backbone.Memento

Backbone.actAs.Configurable

Simple helpers to configure your models from one configuration object.

Backbone.Articulation

Backbone.Validations

Backbone.Validation

Backbone.Validator

backbone-view-model

Backbone.ModelRef

• Lets you build your views while you wait for models to load.
• Notifies you when a model unloads so you can change your view state.
• Compatible with Knockback.js (https://github.com/kmalakoff/knockback)

Pretty much just a collection and model id reference. Simple, but useful.

workflow.js

Backbone Dotattr

Backbone.Mutators

Backbone.Chosen

Backbone fetch cache

Storage

Backbone.localStorage

backbone.couchdb.js

Backbone.ioBind

Backbone-websql

Backbone-slet

Backbone.SharePoint

Backbone.SAP

Backbone.Offline

Backbone.Rpc

Backbone.Safe

Relations

Backbone-relational

Backbone-associations

Backbone.Rel

Ligament

backbone-orm

Collection

backbone-pageable

A pageable, drop-in replacement for Backbone.Collection. Supports client-side and server-side pagination, single page and global sorting, and client-side bi-directional event handling. Inspired by Backbone.Paginator, but much better.

Backbone.actAs.Paginatable

Load your collections piece by piece. Very useful for large model sets.

Nesting.js

Simple helper function that makes it easy to work with nested Backbone collections

Backbone.CollectionSubset

Create subsets of collections using filter functions that automatically update allowing you to create a tree of collections that is always in sync.

Backbone Query

Provides NoSQL queries (like MongoDB) for backbone.js collections

Query Engine

Provides extensive querying, filtering, and searching functionality for backbone.js collections

• includes live interactive demo
• source-code documentation only
• runs on node.js and in the browser
• supports NoSQL queries (like MongoDB)
• supports filters (applying a filter function to a collection)
• supports search strings (useful for turning search input fields into useful queries)
• supports pills for search strings (e.g. author:ben priority:important)
• supports optional live collections (when a model is changed, added or removed, it can automatically be tested against the collections queries, filters, and search string, if it fails, remove it from the collection)
• supports parent and child collections (when a parent collection has a model removed, it is removed from the child collection too, when a parent collection has a model added or changed, it is retested against the child collection)
• https://github.com/bevry/query-engine

Backbone fetch cache

View

LayoutManager

Backbone.Stickit

Model-View binding in Backbone style.

Yabbe (Yet Another Backbone Binding Exension)

Synapse

Backbone.ModelBinder.js

Simple, flexible and powerful bidirectional view-model binding for backbone. A javascript only solution (no markup in html) that relies on jQuery delegates for binding. Similar to how backbone view event blocks work.

• Handles partial view binding, nested views, formatting, type conversion, arbitrary html attributes and most html element types.
• JS Weekly Article
• Git

Backbone Bindings

Bi-directional bindings between Backbone.View elements and Backbone.Model attributes.

Backbone.ModelBinding

Awesome model binding between models and form input elements, and more

• KnockoutJS-style data-bind attribute support
• Bind form fields to models and vice-versa
• Convention based
• Pluggable with your own conventions
• Extensible to bind to more than just form input elements

Get the code and read the documentation:

Knockback.js

Knockout bindings for Backbone.js models and collections.

Backbone on the Couch

A little plugin for use in leanback apps, where someone is sat on the couch using a remote control to use your app.

ProxyDollar

Plugin that proxies jQuery/Zepto/$ functions for Backbone Views.

Backbone.declarative

A small plugin that adds declarative model and collection event binding to Backbone Views.

outback.js

KnockoutJS-inspired declarative binding solution for Backbone Views.

• KnockoutJS-compatible binding handler API
• Explicit control over dependencies (e.g. cascading select boxes)
• Unobtrusive (i.e. code-based) and declarative (i.e. markup-based) configuration
• Multiple binding contexts for separating transient and persistent models.
• Tests, TodosMVC, and examples.
• https://github.com/politician/outback

Backbone.BindTo

Extension for automatic binding and unbinding of model events to views. It defines two special view attributes - bindToModel and bindToCollection. They are handled similar to events attribute, but instead of binding to dom events they bind to model/collection. Also this plugin takes care of cleaning events after the view is removed.

https://github.com/RStankov/backbone-bind-to

Backbone.PluginView

Make jQuery plugins from your Backbone Views.

Backbone.ViewKit

View management and transitions geared toward mobile applications.

Templates

Backrub

Helpers

Builder (DOM Builder for Backbone Views)

Widgets

Slickback (integration with SlickGrid)

Vienna IKS Editables

Backbone.Aura

Backbone.Aura is a decoupled, event-driven architecture on top of Backbone.js for developing widget-based applications

Routing

jQuery Mobile Routing

Before/After Filters

Query Parameters

Frameworks

Backbone Boilerplate

Backbone.CQRS

Capt by Ben Nolan

Chaplin

• https://github.com/chaplinjs/chaplin - An opinionated, full-featured architecture framework for creating complex single-page applications with a strong emphasis on memory management and class heirarchies. Includes a powerful CollectionView class, rails-style routing with proper params hash, and controller patterns.

Backbone.Marionette

Make your BackboneJS apps dance with a composite application structure!

Mixin.js

• Provides mixin classes for a local collections (not stored on a server) and for mixing Backbone.Events into any class (including a check if they are mixed-in).
• Provides a facility to use Backbone.Events trigger('destroy') to do memory cleanup instead of a destroy method (event-based instance life-cycles).
  
• https://github.com/kmalakoff/mixin

Backbone Module (Module loader for Backbone apps)

• Not a JS loader like require.js, but a way to structure your code in big Backbone app projects.
• Load JS without worrying about load sequence and dependencies between modules.
• Source: https://github.com/juggy/backbone-module

Singool.js

Backbone-Traversal

Other

Backbone.Analytics: Drop-In Google Analytics For Backbone's Router

Backbone-Callbacks: Node.js style callbacks for asynchronous methods

Backbone.jFeed: RSS/ATOM Feeds For Collections

Cleaning Up And Preventing Memory Leaks With Your Views

Thingy-Client

Backbone (adapted for MooTools)

Backbone-Factory

Backbone.StateMachine

Backbone-FSM

Backbone.Shortcuts

Brunch

• http://brunch.io - provides a powerful, rails-like directory structure and a powerful, extensible set of component generators (for working with Jade, handlebars, sass, less, stylus, etc.)

Backbone Tastypie

• Modifications to Backbone's Model an Collection so that they play nice with django-tastypie. Includes a way to easily paginate over a resource list and a way to access the associated meta information.
• https://github.com/amccloud/backbone-tastypie

Backbone Interface

• Errors are thrown when Backbone instance does not have all the required methods of the interface.
• Better organized code. Keep your interfaces separate, with comments - a well-documented reference point for the methods in your Models, Collections, Views, and Routers. (Not for production).
• https://github.com/luke-siedle/backbone-interface

Backbone.Service

Backbone.GoogleMaps

Backbone-relational

Backbone-relational provides one-to-one, one-to-many and many-to-one relations between models for Backbone. To use relations, extend Backbone.RelationalModel (instead of the regular Backbone.Model) and define a property relations, containing an array of option objects. Each relation must define (as a minimum) the type, key and relatedModel. Available relation types are Backbone.HasOne and Backbone.HasMany. Backbone-relational features:

• Bidirectional relations, which notify related models of changes through events.
• Control how relations are serialized using the includeInJSON option.
• Automatically convert nested objects in a model's attributes into Model instances using the createModels option.
• Lazily retrieve (a set of) related models through the fetchRelated(key<string>, [options<object>], update<bool>) method.
• Determine the type of HasMany collections with collectionType.
• Bind new events to a Backbone.RelationalModel for:
  • addition to a HasMany relation (bind to add:<key>; arguments: (addedModel, relatedCollection)),
  • removal from a HasMany relation (bind to remove:<key>; arguments: (removedModel, relatedCollection)),
  • reset of a HasMany relation (bind to reset:<key>; arguments: (relatedCollection)),
  • changes to the key itself on HasMany and HasOne relations (bind to update:<key>; arguments=(model, relatedModel/relatedCollection)).

Contents

Getting started

Resources to get you started with Backbone-relational:

Installation

Backbone-relational depends on backbone (and thus on underscore). Include Backbone-relational right after Backbone and Underscore:

<script type="text/javascript" src="./js/underscore.js"></script>
<script type="text/javascript" src="./js/backbone.js"></script>
<script type="text/javascript" src="./js/backbone-relational.js"></script>

Backbone-relational has been tested with Backbone 0.9.9 (or newer) and Underscore 1.4.3 (or newer).

Backbone.Relation options

Each Backbone.RelationalModel can contain an array of relations. Each relation supports a number of options, of which relatedModel, key and type are mandatory. A relation could look like the following:

Zoo = Backbone.RelationalModel.extend({
 relations: [{
 type: Backbone.HasMany,
 key: 'animals',
 relatedModel: 'Animal',
 collectionType: 'AnimalCollection',
 reverseRelation: {
 key: 'livesIn',
 includeInJSON: 'id'
 // 'relatedModel' is automatically set to 'Zoo'; the 'relationType' to 'HasOne'.
 }
 }]
});
Animal = Backbone.RelationalModel.extend({
 urlRoot: '/animal/'
});
AnimalCollection = Backbone.Collection.extend({
 model: Animal,
 url: function( models ) {
 return '/animal/' + ( models ? 'set/' + _.pluck( models, 'id' ).join(';') + '/' : '' );
 }
});

relatedModel

Value: a string (which can be resolved to an object type on the global scope), or a reference to a Backbone.RelationalModel type.

key

Value: a string. References an attribute name on relatedModel.

type

Value: a string, or a reference to a Backbone.Relation type

Example: Backbone.HasOne or 'HasMany'.

HasOne relations (Backbone.HasOne)

The key for a HasOne relation consists of a single Backbone.RelationalModel. The default reverseRelation.type for a HasOne relation is HasMany. This can be set to HasOne instead, to create a one-to-one relation.

HasMany relations (Backbone.HasMany)

The key for a HasMany relation consists of a Backbone.Collection, containing zero or more Backbone.RelationalModels. The default reverseRelation.type for a HasMany relation is HasOne; this is the only option here, since many-to-many is not supported directly.

Many-to-many relations

A many-to-many relation can be modeled using two Backbone.HasMany relations, with a link model in between:

Person = Backbone.RelationalModel.extend({
 relations: [
 {
 type: 'HasMany',
 key: 'jobs',
 relatedModel: 'Job',
 reverseRelation: {
 key: 'person'
 }
 }
 ]
});
// A link object between 'Person' and 'Company', to achieve many-to-many relations.
Job = Backbone.RelationalModel.extend({
 defaults: {
 'startDate': null,
 'endDate': null
 }
})
Company = Backbone.RelationalModel.extend({
 relations: [
 {
 type: 'HasMany',
 key: 'employees',
 relatedModel: 'Job',
 reverseRelation: {
 key: 'company'
 }
 }
 ]
});
niceCompany = new Company( { name: 'niceCompany' } );
niceCompany.bind( 'add:employees', function( model, coll ) {
 // Will see a Job with attributes { person: paul, company: niceCompany } being added here
 });
paul.get( 'jobs' ).add( { company: niceCompany } );

keySource

Value: a string. References an attribute on the data used to instantiate relatedModel.

Used to override key when determining what data to use when (de)serializing a relation, since the data backing your relations may use different naming conventions. For example, a Rails backend may provide the keys suffixed with _id or _ids. The behavior for keySource corresponds to the following rules:

1. When a relation is instantiated, the contents of the keySource are used as it's initial data.
2. The application uses the regular key attribute to interface with the relation and the models in it; the keySource is not available as an attribute for the model.

So you may be provided with data containing animal_ids, while you want to access this relation as zoo.get( 'animals' );.

NOTE: for backward compatibility reasons, setting keySource will set keyDestination as well. This means that when saving zoo, the animals attribute will be serialized back into the animal_ids key.

WARNING: when using a keySource, you should not use that attribute name for other purposes.

keyDestination

Value: a string. References an attribute to serialize relatedModel into.

Used to override key (and keySource) when determining what attribute to be written into when serializing a relation, since the server backing your relations may use different naming conventions. For example, a Rails backend may expect the keys to be suffixed with _attributes for nested attributes.

When calling toJSON on a model (either via Backbone.sync, or directly), the data in the key attribute is transformed and assigned to the keyDestination.

So you may want a relation to be serialized into the animals_attributes key, while you want to access this relation as zoo.get( 'animals' );.

WARNING: when using a keyDestination, you should not use that attribute name for other purposes.

collectionType

Value: a string (which can be resolved to an object type on the global scope), or a reference to a Backbone.Collection type.

Determine the type of collections used for a HasMany relation. If you define a url(models<Backbone.Model[]>) function on the specified collection, this enables fetchRelated to fetch all missing models in one request, instead of firing a separate request for each. See Backbone-tastypie for an example of a url function that can build a url for the collection (or a subset of models).

collectionKey

Value: a string or a boolean

Used to create a back reference from the Backbone.Collection used for a HasMany relation to the model on the other side of this relation. By default, the relation's key attribute will be used to create a reference to the RelationalModel instance from the generated collection. If you set collectionKey to a string, it will use that string as the reference to the RelationalModel, rather than the relation's key attribute. If you don't want this behavior at all, set collectionKey to false (or any falsy value) and this reference will not be created.

collectionOptions

Value: an options hash or a function that accepts an instance of a Backbone.RelationalModel and returns an option hash

Used to provide options for the initialization of the collection in the "Many"-end of a HasMany relation. Can be an options hash or a function that should take the instance in the "One"-end of the "HasMany" relation and return an options hash

includeInJSON

Value: a boolean, a string referencing one of the model's attributes, or an array of strings referencing model attributes. Default: true.

Determines how the contents of a relation will be serialized following a call to the toJSON method. If you specify a:

• Boolean: a value of true serializes the full set of attributes on the related model(s). Set to false to exclude the relation completely.
• String: include a single attribute from the related model(s). For example, 'name', or Backbone.Model.prototype.idAttribute to include ids.
• String[]: includes the specified attributes from the related model(s).

Only specifying true is cascading, meaning the relations of the model will get serialized as well!

createModels

Value: a boolean. Default: true.

Should models be created from nested objects, or not?

reverseRelation

If the relation should be bidirectional, specify the details for the reverse relation here. It's only mandatory to supply a key; relatedModel is automatically set. The default type for a reverseRelation is HasMany for a HasOne relation (which can be overridden to HasOne in order to create a one-to-one relation), and HasOne for a HasMany relation. In this case, you cannot create a reverseRelation with type HasMany as well; please see Many-to-many relations on how to model these type of relations.

Please note: if you define a relation (plus a reverseRelation) on a model, but never actually create an instance of that model, the model's constructor will never run, which means it's initializeRelations will never get called, and the reverseRelation will not be initialized either. In that case, you could either define the relation on the opposite model, or define two single relations. See issue 20 for a discussion.

autoFetch

Value: a boolean or an Object (see below). Default: false.

If this property is set to true, when a model is instantiated the related model is automatically fetched using fetchRelated. The value of the property can also be an object. In that case the related model is automatically fetched and the object is passed to fetchRelated as the options parameter.

var Shop = Backbone.RelationalModel.extend({
 relations: [{
 type: Backbone.HasMany,
 key: 'customers',
 relatedModel: 'Customer',
 autoFetch: true
 },{
 type: Backbone.HasOne,
 key: 'address',
 relatedModel: 'Address',
 autoFetch: {
 success: function(model, response){
 //...
 },
 error: function(model, response){
 //...
 }
 }
 }
 ]

Backbone.RelationalModel

Backbone.RelationalModel introduces a couple of new methods, events and properties.

Methods

getRelations relationalModel.getRelations()

Returns the set of initialized relations on the model.

fetchRelated relationalModel.fetchRelated(key<string>, [options<object>], [update<boolean>])

Fetch models from the server that were referenced in the model's attributes, but have not been found/created yet. This can be used specifically for lazy-loading scenarios. Setting update to true guarantees that the model will be fetched from the server and any model that already exists in the store will be updated with the retrieved data. The options object specifies options to be passed to Backbone.sync.

By default, a separate request will be fired for each additional model that is to be fetched from the server. However, if your server/API supports it, you can fetch the set of models in one request by specifying a collectionType for the relation you call fetchRelated on. The collectionType should have an overridden url(models<Backbone.Model[]>) method that allows it to construct a url for an array of models. See the example at the top of Backbone.Relation options or Backbone-tastypie for an example.

Methods on the type itself

Several methods don't operate on model instances, but are defined on the type itself.

setup ModelType.setup()

Initialize the relations and submodels for the model type. See the Q and A for a possible scenario where it's useful to call this method manually.

build ModelType.build(attributes<object>, [options<object>])

Create an instance of a model, taking into account what submodels have been defined.

findOrCreate ModelType.findOrCreate(attributes<string|number|object>, [options<object>])

Search for a model instance in the Backbone.Relational.store.

• If attributes is a string or a number, findOrCreate will just query the store and return a model if found.
• If attributes is an object, the model will be updated with attributes if found. Otherwise, a new model is created with attributes (unless options.create is explicitly set to false).

Events

• add: triggered on addition to a HasMany relation.
  Bind to add:<key>; arguments: (addedModel<Backbone.Model>, related<Backbone.Collection>).
• remove: triggered on removal from a HasMany relation.
  Bind to remove:<key>; arguments: (removedModel<Backbone.Model>, related<Backbone.Collection>).
• update: triggered on changes to the key itself on HasMany and HasOne relations.
  Bind to update:<key>; arguments: (model<Backbone.Model>, related<Backbone.Model|Backbone.Collection>).

Properties

Properties can be defined along with the subclass prototype when extending Backbone.RelationalModel or a subclass thereof.

subModelTypes

Value: an object. Default: {}.

A mapping that defines what submodels exist for the model (the superModel) on which subModelTypes is defined. The keys are used to match the subModelTypeAttribute when deserializing, and the values determine what type of submodel should be created for a key. When building model instances from data, we need to determine what kind of object we're dealing with in order to create instances of the right subModel type. This is done by finding the model for which the key is equal to the value of the submodelTypeAttribute attribute on the passed in data.

Each subModel is considered to be a proper submodel of its superclass (the model type you're extending), with a shared id pool. This means that when looking for an object of the supermodel's type, objects of a submodel's type can be returned as well, as long as the id matches. In effect, any relations pointing to the supermodel will look for instances of it's submodels as well.

Example:

Mammal = Animal.extend({
 subModelTypes: {
 'primate': 'Primate',
 'carnivore': 'Carnivore'
 }
});
var Primate = Mammal.extend();
var Carnivore = Mammal.extend();
var MammalCollection = AnimalCollection.extend({
 model: Mammal
});
// Create a collection that contains a 'Primate' and a 'Carnivore'.
var mammals = new MammalCollection([
 { id: 3, species: 'chimp', type: 'primate' },
 { id: 5, species: 'panther', type: 'carnivore' }
]);

Suppose that we have an Mammal model and a Primate model extending Mammal. If we have a Primate object with id 3, this object will be returned when we have a relation pointing to a Mammal with id 3, as Primate is regarded a specific kind of Mammal; it's just a Mammal with possibly some primate-specific properties or methods.

Note that this means that there cannot be any overlap in ids between instances of Mammal and Primate, as the Primate with id 3 will be the Mammal with id 3.

subModelTypeAttribute

Value: a string. Default: "type".

The subModelTypeAttribute is a references an attribute on the data used to instantiate relatedModel. The attribute that will be checked to determine the type of model that should be built when a raw object of attributes is set as the related value, and if the relatedModel has one or more submodels.

See subModelTypes for more information.

Example

paul = new Person({
 id: 'person-1',
 name: 'Paul',
 user: { id: 'user-1', login: 'dude', email: 'me@gmail.com' }
});
// A User object is automatically created from the JSON; so 'login' returns 'dude'.
paul.get('user').get('login');
ourHouse = new House({
 id: 'house-1',
 location: 'in the middle of the street',
 occupants: ['person-1', 'person-2', 'person-5']
});
// 'ourHouse.occupants' is turned into a Backbone.Collection of Persons.
// The first person in 'ourHouse.occupants' will point to 'paul'.
ourHouse.get('occupants').at(0); // === paul
// If a collection is created from a HasMany relation, it contains a reference
// back to the originator of the relation
ourHouse.get('occupants').livesIn; // === ourHouse
// the relation from 'House.occupants' to 'Person' has been defined as a bi-directional HasMany relation,
// with a reverse relation to 'Person.livesIn'. So, 'paul.livesIn' will automatically point back to 'ourHouse'.
paul.get('livesIn'); // === ourHouse
// You can control which relations get serialized to JSON (when saving), using the 'includeInJSON'
// property on a Relation. Also, each object will only get serialized once to prevent loops.
paul.get('user').toJSON();
 /* result:
 {
 email: "me@gmail.com",
 id: "user-1",
 login: "dude",
 person: {
 id: "person-1",
 name: "Paul",
 livesIn: {
 id: "house-1", 
 location: "in the middle of the street",
 occupants: ["person-1"] // just the id, since 'includeInJSON' references the 'idAttribute'
 },
 user: "user-1" // not serialized because it is already in the JSON, so we won't create a loop
 }
 }
 */
// Load occupants 'person-2' and 'person-5', which don't exist yet, from the server
ourHouse.fetchRelated( 'occupants' );
// Use the 'add' and 'remove' events to listen for additions/removals on HasMany relations (like 'House.occupants').
ourHouse.bind( 'add:occupants', function( model, coll ) {
 // create a View?
 console.debug( 'add %o', model );
 });
ourHouse.bind( 'remove:occupants', function( model, coll ) {
 // destroy a View?
 console.debug( 'remove %o', model );
 });
// Use the 'update' event to listen for changes on a HasOne relation (like 'Person.livesIn').
paul.bind( 'update:livesIn', function( model, attr ) {
 console.debug( 'update to %o', attr );
 });
// Modifying either side of a bi-directional relation updates the other side automatically.
// Make paul homeless; triggers 'remove:occupants' on ourHouse, and 'update:livesIn' on paul
ourHouse.get('occupants').remove( paul.id ); 
paul.get('livesIn'); // yup; nothing.
// Move back in; triggers 'add:occupants' on ourHouse, and 'update:livesIn' on paul
paul.set( { 'livesIn': 'house-1' } );

This is achieved using the following relations and models:

House = Backbone.RelationalModel.extend({
 // The 'relations' property, on the House's prototype. Initialized separately for each instance of House.
 // Each relation must define (as a minimum) the 'type', 'key' and 'relatedModel'. Options are
 // 'includeInJSON', 'createModels' and 'reverseRelation', which takes the same options as the relation itself.
 relations: [
 {
 type: Backbone.HasMany, // Use the type, or the string 'HasOne' or 'HasMany'.
 key: 'occupants',
 relatedModel: 'Person',
 includeInJSON: Backbone.Model.prototype.idAttribute,
 collectionType: 'PersonCollection',
 reverseRelation: {
 key: 'livesIn'
 }
 }
 ]
});
Person = Backbone.RelationalModel.extend({
 relations: [
 { // Create a (recursive) one-to-one relationship
 type: Backbone.HasOne,
 key: 'user',
 relatedModel: 'User',
 reverseRelation: {
 type: Backbone.HasOne,
 key: 'person'
 }
 }
 ],
 initialize: function() {
 // do whatever you want :)
 }
});
PersonCollection = Backbone.Collection.extend({
 url: function( models ) {
 // Logic to create a url for the whole collection, or a set of models.
 // See the tests, or Backbone-tastypie, for an example.
 return '/person/' + ( models ? 'set/' + _.pluck( models, 'id' ).join(';') + '/' : '' );
 }
});
User = Backbone.RelationalModel.extend();

Known problems and solutions

Q: (Reverse) relations or submodels don't seem to be initialized properly (and I'm using CoffeeScript!)

A: You're probably using the syntax class MyModel extends Backbone.RelationalModel instead of MyModel = Backbone.RelationalModel.extend. This has advantages in CoffeeScript, but it also means that Backbone.Model.extend will not get called. Instead, CoffeeScript generates piece of code that would normally achieve roughly the same. However, extend is also the method that Backbone-relational overrides to set up relations and other things as you're defining your Backbone.RelationalModel subclass.

For exactly this scenario where you're not using .extend, Backbone.RelationalModel has the .setup method, that you can call manually after defining your subclass CoffeeScript-style. For example:

class MyModel extends Backbone.RelationalModel
 relations: [
 // etc
 ]
MyModel.setup()

See issue #91 for more information.

Q: After a fetch, I don't get add:<key> events for nested relations.

A: This is due to Backbone.Collection.reset silencing add events. Pass fetch( {add: true} ) to bypass this problem. You may want to override Backbone.Collection.fetch for this, and also trigger an event when the fetch has finished while you're at it. Example:

var _fetch = Backbone.Collection.prototype.fetch;
Backbone.Collection.prototype.fetch = function( options ) {
 options || ( options = {} );
 _.defaults( options, { add: true } );
 // Remove old models
 this.reset();
 // Call 'fetch', and trigger an event when done.
 var dit = this,
 request = _fetch.call( this, options );
 request.done( function() {
 if ( !options.silent ) {
 dit.trigger( 'fetch', dit, options );
 }
 });
 return request;
};

Under the hood

Each Backbone.RelationalModel registers itself with Backbone.Store upon creation (and is removed from the Store when destroyed). When creating or updating an attribute that is a key in a relation, removed related objects are notified of their removal, and new related objects are looked up in the Store.

Backbone app skeleton

Just clone this repo and use it as a starting point for your new Backbone.js based voyages.

Assumptions

Skeletons like these can work well only if there are certain assumptions/conventions.

1. We assume that you use CoffeeScript for all your scripting.
2. We assume that you use SASS for your styling.
3. We assume that you use HAML for your base DOM.
4. We assume that you use HAML(c) for your templates for Backbone views.

What gives

It provides:

• directory structure
• stubs for important foundation files
• application-wide events
• sophisticated and customizable init process
• compilation of CoffeeScript/SASS/HAML to native JS/CSS/HTML via Guard
• concatenation and compression of assets via Jammit
• self contained Ruby web server through Sinatra

The skeleton

Let's take a look at the actual structure. Inspired by Rails, I've created a skeleton Backbone application, for which the code was extracted from my latest production app.

So if we get down to business, this is the gist of it, or the skeleton of the skeleton:

.
├── Gemfile
├── Guardfile
├── config/
| └── assets.yml
├── public/
| ├── assets/
| ├── css/
| └── js/
| ├── _lib
| └── templates
├── server
└── src
 ├── coffeescript
 | ├── App.js.coffee 
 | ├── Events.js.coffee
 | ├── init.js.coffee
 | ├── log.js.coffee
 | ├── ns.js.coffee
 | ├── Router.js.coffee
 | ├── models
 | | └── Model.js.coffee
 | └── views
 | └── ModelView.js.coffee 
 ├── haml
 | └── index.html.haml
 ├── sass
 | └── application.css.sass
 └── templates

Let's examine all of these and learn about what they do and why they're important.

Gemfile

The Gemfile is simply instructions to the Ruby Bundler about which libraries we need. We're installing only Guard and its dependencies like HAML, SASS and CoffeeScript.

Guardfile

The Guardfile are instructions for Guard so it knows which files to watch for changes and what to do with them.

It's basically just using various Guard plugins that just need to know the input and output directories and an optional watch statement.

guard 'haml', :input => 'src/haml', :output => 'public/' do
 watch %r{^.+(\.html\.haml)\Z}
end
guard 'haml-coffee', :input => 'src/templates', :output => 'public/js/templates' do
 watch %r{^.+(\.js\.hamlc)\Z}
end
guard 'sass', :input => 'src/sass', :output => 'public/css'
guard 'coffeescript', :input => 'src/coffeescript', :output => 'public/js'
guard :jammit, :config_path => 'config/assets.yml' do
 watch %r{^public/js/(.*)\.js$}
 watch %r{^public/css/(.*)\.css$}
end

You can learn a lot about the structure, by just examining these lines.

config/ and assets.yml

Config houses configuration and in the skeleton, the only configuration is for the Jammit library.

It lists which JavaScript and CSS files to concatenate together, in which order to do it and where to deposit the result.

public/

This is the "root" where you'll point your web server in production (in the included server, this is done already).

These files are ignored from Git, because they should always be reconstructed from source files in the src/ directory.

Oh, and Guard also compiles HTML files directly into public/.

public/assets/

Jammit puts in all the concatenated and compressed code. This is your actual end product.

public/css/

Guard compiles SASS into this directory.

public/js/

Guard compiles CoffeeScript into this directory.

public/js/_lib/

There is one special sub-directory here _lib. It's special because it's not ignored from Git. Inside you put whatever JavaScript libraries you'd like to use, such as jquery.cookie for cookie management.

public/js/templates/

Into templates/ Guard compiles your HAML Coffee templates, that you use in Backbone views.

server/

This irectory houses the Ruby/Sinatra web server. Consult the main app.rb file, where you can play with your server-side, mock up and API, etc.

src/

The heart and soul (i mean source) of your app.

src/coffeescript/

This is where all the JavaScript is concieved.

App.js.coffee

App is the main class. It holds critical initialization code and application wide events.

Backbone has an Events module, that can be plugged into your own classes.

# Use Backbone's events in your master class.
events: _.extend(BBNS.Events, Backbone.Events)

Events.js.coffee

Defines our own BBNS.Events class, that I use here to define s shorthand for the Events#trigger method.

init.js.coffee

This is the file that boots us up. It first makes an instance of the App class from App.js.coffee, then wires in the DOM load and other events.

log.js.coffee

A custom logging function. Nothing fancy here, just outputs the timestamp and ensures that things don't break even if window.console isn't defined.

It features also logging at different levels. For example, if you set debug to 6 in App.js.coffee, you will see all the app-wide events that are being triggered:

ns.js.coffee

Here we declare our root name space. All other files declare properties of this root name space.

In the skeleton app this is window.BBNS, which stands for Backbone Name Space. You should change this for your own needs.

Router.js.coffee

Defines the root Backbone router class. For my purposes I never needed more than one router until now. When I do, I'll put them under a separate routers/ directory like models and views.

src/models/

Define Backbone models here that will hold, manipulate, load and persist your data.

src/views/

Define Backbone views here and name them <model_or_functionality>View.js.coffee. Just append View to all files for consistency's sake.

haml/

Here we define the root file that the browser needs to load our app. index.html.haml from here becomes public/index.html when Guard is done with it.

It's unusual to need more than one file here, but depends on the complexity of the app.

sass/

Style your app here. I usually use just one main application.css.sass file and then use SASS @import statements to modularize code.

Why? If you try to compile partial stylesheets with Guard and you're using some helpers defined in the main file, Guard will complain.

templates/

Put in here your templates for use in Backbone Views and written in HAML Coffee. They get compiled into public/js/templates/.

Usage

Getting started with a new app using my skeleton is trivial. It uses Ruby in several critical places, so be sure you have a working installation of Ruby, preferably of the 1.9 kind.

Start by cloning my backbone-skeleton repo.

$ git clone https://github.com/mihar/backbone-skeleton.git my-new-backbone-app

Then use the bundle command that comes with Ruby Bundler to install the necessary dependencies for guard. Guard will compile our HAML, SASS and CoffeeScript to their native counterparts.

$ cd my-new-backbone-app
$ bundle

Once Bundler completes the installation, we can try starting Guard, to immediately start watching files for changes.

$ bundle exec guard

While leaving guard running, go to another terminal and let's fire up a simple, bundled Ruby web server, that we'll use for development. The server will install all of it's dependencies by itself.

$ rake server
[1/1] Isolating sinatra (>= 0).
Fetching: rack-1.4.1.gem (100%)
Fetching: rack-protection-1.2.0.gem (100%)
Fetching: tilt-1.3.3.gem (100%)
Fetching: sinatra-1.3.3.gem (100%)
[2012-12-05 18:17:05] INFO WEBrick 1.3.1
[2012-12-05 18:17:05] INFO ruby 1.9.3 (2012-02-16) [x86_64-darwin11.3.0]
[2012-12-05 18:17:05] INFO WEBrick::HTTPServer#start: pid=39675 port=9292

Now our server is listening on http://localhost:9292, so go ahead, and open that.

If you see "Skeleton closet", everything is go.

Go check out the JavaScript console for more information.

Vertebrae front-end framework built with Backbone.js and RequireJS using AMD

Vertebrae provides AMD structure and additional objects for extending Backbone.js as an application framework.

Project / Goals

The project goals included... dynamic script loading, AMD module format, dependency management, build with mostly open source libraries, organize code in packages, optimize and build for one or many single page apps, host on fully cached server, e.g. no server-side scripting using only an API for data, and the funnest for me, use behaviour driven development for the project. There is a description on the project at : www.hautelooktech.com - Vertebrae post

The Problem:

Selected libraries for the framework (jQuery, Underscore.js, Backbone.js, RequireJS, Mustache) provide module loading, dependency management, application structure (for models, collections, views and routes), asynchronous interactions with API, various utilities and objects to manage asynchronous behaviors, e.g. (Promises) Deferreds, Callbacks. The remaining logic needed to complete the framework includes:

• An object (model) to manage state of the single-page application;
• A layout manager to present, arrange/transition and clear views, and
• Controllers which respond to routes, get/set application state, and hand off work to layout manager.

Our Solutions (implemented in Vertebrae):

Application State Manager -

The application manager stores data in memory and also persists data in browser storage to provide a resource for common data/metadata. Also provides data (state) to reconstruct the page views based on previous interactions (e.g. selected tab, applied filters). The application state manager provides a strategy for resources to retrieve state. Meant to act as a state machine.

Layout Manager -

The layout manager has one or many views as well as document (DOM) destinations for each (rendered) view. A page may transition between many views, so the layout manager keeps track of view states, e.g. rendered, not-rendered, displayed, not-displayed. You may use the layout manager to lazy load and render (detached) views that a site visitor is very likely to request, e.g. tab changes on a page. The transition between view states is managed by this object. An entire layout may be cleared so that view objects and their bindings are removed, preparing these objects for garbage collection (preventing memory leaks). The layout manager also communicates view state with controller(s).

Controller -

A controller object is called by a route handler function, and is responsible for getting relevant state (application models) to generate a page (layout), (also responsible for setting state when routes change). The controller passes dependent data (models/collections) and constructed view objects for a requested page to the layout manager. As a side-effect the use of controllers prevents the routes object from becoming bloated and tangled. A route should map to a controller which then kicks off the page view, keeping the route handling functions lean.

The Todos app is hosted both in dev mode and optimized on Heroku...

Many of the concepts in the frameworks are borrowed, e.g. the need to destroy views to prevent memory leaks, as pointed out by Derick Bailey - http://lostechies.com/derickbailey/ ; the Layout Manager by Tim Branyen http://tbranyen.github.com/backbone.layoutmanager/

Backbone.js is meant to be a tool in an application; the Backbone.js library does not provide the architecture needed to build a complete application, however does provide great interactions with an API and solid code structure for... Views (which act like controllers too), Models and Collections (the data layer), and finally* Routes*. We built the Vertebrae framework to meat the goals of our project, and decided to extract the code as a framework for others to use, learn, or whatever.

Build and optimize using:

r.js -o build.js

To launch (Node.js) server

node app.js

Based on the setting in app.js the server runs from either the src or public directory at : http://localhost:4242/

docroot = path.join(application_root, "src"), // "src" for dev, or "public" for built version

The build.js file is configured to build to the "public" directory.

So after you run r.js -o build.js to populate the "public" directory then you can use node app.js to view the site at : http://localhost:4242

Testing Framework using Jasmine, Sinon, Jasmine-jQuery

Views:

BaseView, CollectionView, SectionView, LayoutView (Manages Sections)

Base View

A view object to construct a standard view with common properties and utilties The base view extends Backbone.View adding methods for resolving deferreds, rendering, decorating data just in time for rendering, adding child views to form a composite of views under one view object, add a destroy method.

Collection View

Manages rendering many views with a collection

The CollectionView extends BaseView and is intended for rendering a collection. A item view is required for rendering withing each iteration over the models. See: http://liquidmedia.ca/blog/2011/02/lib-js-part-3/

Section View States

Mixin object to track view's state 'not-rendered', 'rendered', 'not-displayed', 'displayed'

A section view is the required view object for a layout view which expects views to track their own state. This view may be extended as need. to use in a layout, perhaps adding the Section prototype properties to another view.

Layout Manager View

Presents, arranges, transitions and clears views

The layout manager has one or many views as well as document (DOM) destinations for each (rendered) view. A page may transition between many views, so the layout manager keeps track of view states, e.g. 'not-rendered', 'rendered', 'not-displayed', 'displayed'.

The layout manager can be utilized to lazy load and render (detached) views. that a site visitor is very likely to request, e.g. tab changes on a page. The transition between view states is managed by this object. An entire layout may be cleared so that view objects and their bindings are removed, preparing these objects for garbage collection (preventing memory leaks). The layout manager also communicates view state with controller(s).

Models:

BaseModel, ApplicationState

Application state model

A model object to manage state within the single-page application Attributes: {String} name, {Object} data, {String} storage, {Date} expires

Collections:

BaseCollection, ApplicationStates

Application state collection

A collection object to reference various states in the application.

The application manager stores data in memory and also persists data in browser storage to provide a resource for common data/metadata. Also provides data (state) to reconstruct the page views based on previous interactions (e.g. selected tab, applied filters). The application state manager provides a strategy for resources to retrieve state.

Syncs:

syncFactory, application-state, storageFactory

Utils:

ajax-options, docCookies, debug, storage, shims, lib [checkType, duckTypeCheck, Channel (pub/sub), loadCss, formatCase, formatMoney]

Controller

A controller object should called withing a route handler function, and may be responsible for getting relevant state (application models) to generate a page (layout), (also responsible for setting state when routes change). The controller passes dependent data (models/collections) and constructed view objects for a requested page to the layout manager. As a side-effect the use of controllers prevents the routes object from becoming bloated and tangled. A route should map to a controller which then kicks off the page view, keeping the route handling functions lean.

Facade

Vendor libraries and specific methods used in the framework are required in the facade, and referenced from the facade module in the views, models, collections, lib and other objects in the framework.

AMD - Asynchronous Module Definition

Using RequireJS script loader and AMD there are a couple options for managing dependencies:

The the examples below the facade module has it's own dependencies for loading vendor libraries and maps them to an object. So vendor libraries Should only be required using the facade module which provides references to the libraries.

define(['facade','utils'], function (facade, utils) {
 var ModuleName,
 // References to objects nested in dependencies
 Backbone = facade.Backbone,
 $ = facade.$,
 _ = facade._,
 lib = utils.lib;
 ModuleName = DO SOMETHING HERE
 return ModuleName;
});
define(['require','facade','utils'], function (require) {
 var ModuleName,
 // Dependencies
 facade = require('facade'),
 utils = require('utils'),
 // References to objects nested in dependencies
 Backbone = facade.Backbone,
 $ = facade.$,
 _ = facade._,
 lib = utils.lib;
 ModuleName = DO SOMETHING HERE
 return ModuleName;
});

References:

Code examples included in framework: application.js

The application.js has a few routes defined which handle a couple example code packages: products and hello. the chrome package has the Twitter bootstrap markup for rendering header component on the page.

App = Backbone.Router.extend({
 routes: {
 '': 'defaultRoute',
 'products': 'showProducts',
 'hello': 'showHello',
 'hello/': 'showHello',
 'hello/:name': 'showHello'
 },

The default route above links to the products route handler loading a list of products on the default page.

Hello World example using a the Layout Manager (View)

Routes in the hello package

/hello 
/hello/:name 

without the name parameter only one the 'about' view is rendered in the layout; with the parameter e.g. /hello/bill two views are rendered in the layout a 'welcome' and an 'about' view

Part 1: welcome section

Using a Layout view involves: adding a route, route handler function in App, new "hello" package with a template and view. The package controller file hello.js extends the Controller.prototype and is based on a (template) copy of the Controller.prototype in src/controller.js. The WelcomeSectionView prototype extends the SectionView prototype (class) and requries both name and destination properties when instantiated. The application.js method 'showHello' is mapped to the route '/hello/:name' and the showHello method instantiates a controller object

Files edited in the application:

src/application.js 
src/main.js 

Files added as a new package:

src/packages/hello.js [returns: HelloController] 
src/packages/hello/models/welcome.js 
src/packages/hello/templates/layout.html [HTML used by layout, has section element] 
src/packages/hello/templates/welcome.html 
src/packages/hello/views/welcome.js [returns: WelcomeSectionView, with article element] 
src/packages/hello/welcome.css

New Route added in src/application.js

 'hello/:name': 'showHello'

New Package added in src/main.js

 // ** Packages **
 'hello' : HL.prependBuild('/packages/hello'),

Add dependency to application.js

define([ /*... ,*/ "hello" ], function ( /*... ,*/ HelloController ) { 
 // BTW this is the AMD module format with "hello" file as dependecy 
});

Add Method for new '/hello/:name' route handler

 showHello: function (name) { 
 controller = new HelloController({ 
 "params": { "name": name }, 
 "route": "/hello/" + name, 
 "appStates" : this.states
 });
 },

The parameters hash is added as an option above for the controller object to deal with.

Code to add in your hello package for a welcome section:

src/packages/hello/templates/layout.html
src/packages/hello.js
src/packages/hello/views/welcome.js
src/packages/hello/templates/welcome.html
src/packages/hello/views/welcome.js
src/packages/hello/welcome.css

Part 2: Use JSON data for new about section

To get the 'about' section data a fixture (JSON file) was added in the test directory.

src/test/fixtures/hello/101:

{
 "_links": {
 "self": "/test/fixtures/hello/101",
 "shop": "http://www.hautelook.com/"
 },
 "title": "About HauteLook",
 "content": "Welcome to HauteLook, where you will discover thousands of the top fashion and lifestyle brands at amazing savings. Each day at 8 AM Pacific, shop new sale events featuring the best names in women's and men's fashion and accessories, beauty, kids' apparel and toys, and home décor at up to 75% off. Membership is free and everyone is welcome!",
 "callToAction": "To start shopping, go to: <a href=\"www.hautelook.com\">www.hautelook.com</a>"
}

The above object is added as a server response in the Node.js app.js as well, so you can simulate using an api for data.

application.js updated with...

 routes: {
 'hello': 'showHello',
 'hello/': 'showHello',
 'hello/:name': 'showHello'
 },

 showHello: function (name) {
 controller = new HelloController({
 "params": { "name": name },
 "route": (name) ? "/hello/" + name : "/hello",
 "appStates" : this.states,
 "useFixtures" : true
 });
 },

Files added for a about section:

See the source code in the files below for how the new "About" section view is added to the layout (in addition to the simple hello name view created by the welcome view)...

src/packages/hello/templates/about.html
src/packages/hello/views/about.js
src/packages/hello/models/about.js

Files changed to support the additional section:

Some files should have changed when working with the Hello World Part 2 example, and others need to be added for the about section...

src/packages/hello.js
src/packages/hello/templates/layout.html
src/packages/hello/templates/welcome.html
src/packages/hello/views/welcome.js
src/packages/hello/welcome.css

Documentation:

Using docco annotated source code documentation is found in these directories:

/docs/
/models/docs/
/collections/docs/
/syncs/docs/
/utils/docs/
/views/docs/

View docs at:

http://localhost:4242/docs/
http://localhost:4242/models/docs/
http://localhost:4242/collections/docs/
http://localhost:4242/syncs/docs/
http://localhost:4242/utils/docs/
http://localhost:4242/views/docs/

Or, view docs on the demo site hosted on heroku at:

http://vertebrae-framework.herokuapp.com/docs/
http://vertebrae-framework.herokuapp.com/models/docs/
http://vertebrae-framework.herokuapp.com/collections/docs/
http://vertebrae-framework.herokuapp.com/syncs/docs/
http://vertebrae-framework.herokuapp.com/utils/docs/
http://vertebrae-framework.herokuapp.com/views/docs/

To generate the docs:

cd src/
docco application.js facade.js controller.js
cd models 
docco *.js 
cd ../collections 
docco *.js 
cd ../syncs 
docco *.js 
cd ../utils 
docco *.js 
cd ../views 
docco *.js
cd ../ 
rm docs/docco.css collections/docs/docco.css models/docs/docco.css syncs/docs/docco.css utils/docs/docco.css views/docs/docco.css 

References:

Thorax

An opinionated, battle tested Backbone + Handlebars framework to build large scale web applications.

Standalone Open the index.html file from the downloaded project in your browser.	Run npm start from the downloaded project.	Mobile Run npm start from the downloaded project.	Rails Run rails server from the downloaded project.
Download 2.0.0b5	Download 2.0.0b5	Download 2.0.0b5	Download 2.0.0b5

Thorax 2 is presently in beta, the stable source and documentation are still available.

Thorax can be used standalone in any JavaScript environment in addition the boilerplate projects provided above.

var view = new Thorax.View({
 template: "Hello world!"
})
view.render()
$("body").append(view.el)

Registry

Thorax creates a special hash for each type of class to store all subclasses in your application. The use of Thorax.Views and Thorax.templates is required to allow the view, template and other helper methods to operate, but the use of the others are optional and provided for consitency.

Class	Registry
Thorax.View	Thorax.Views
Thorax.Model	Thorax.Models
Thorax.Collection	Thorax.Collections
Thorax.Router	Thorax.Routers
templates	Thorax.templates

name klass.prototype.name

If a name property is passed to any Thorax classes' extend method the resulting class will be automatically set in the corresponding registry.

Thorax.View.extend({
 name: "my-view"
});
Thorax.Views["my-view"]

templates Thorax.templates

A hash of templates, used by various Thorax helpers. If using the node or Rails boilerplate projects this hash will be automatically generated from the files in your templates directories. To manually add a template to the hash:

Thorax.templates['my-template-name'] = Handlebars.compile('template string');

If a View has the same name as a template in the templates hash, it's `template' property will be automatically assigned.

Thorax.View

The base Thorax.View implementation is concerned only with Handlebars + Backbone integration. A variety of additional functionality is provided by the various included plugins. The boilerplate projects have a build of Thorax with all plugins included.

var view = new Thorax.View({
 template: "{{key}}",
 key: "value"
});
view.render();
$('body').append(view.el);

children view.children

A hash of child view's indexed by cid. Child views may become attached to the parent with the view helper or may be automatically attached HelperView instanced created by helpers created with regsterViewHelper.

parent view.parent

If a view was embedded inside another with the view helper, or is a HelperView created by a helper creted with registerViewHelper the view will have a parent attribute.

template view.template

Assign a template to a view. This may be a string or a function which recieves a single context argument and returns a string. If the view has a name and a template of the same name is available the template will be auto-assigned.

new Thorax.View({
 template: "{{key}}"
});

destroy view.destroy([options])

By default this will only call destroy on all child views. Other plugins override this method to implement custom cleanup behaviors. Your own behaviors can be added with the destroyed event. Pass children: false to this method to prevent the view's children from being destroyed.

render view.render([content])

Renders the view's template updating the view's el with the result, triggering the rendered event. content may be empty (render the template) or a function that will be called with the response from context or a string.

view.render()
view.render('custom html')

context view.context()

Used by render to determine what attributes are available in the view's template. The default context function returns this. If the model plugin is used, this + model.attributes will be the context.

Render a template with the view's context plus any optional extraContext parameters passed in.

ensureRendered view.ensureRendered()

Ensure that the view has been rendered at least once.

html view.html([content])

Get or set the innerHTML of the view, without triggering the rendered event.

View Helpers

super {{super}}

Embed the template from the parent view within the child template.

{{super}}

template {{template name [options]}}

Embed a template inside of another, as a string. An associated view (if any) will not be initialized. By default the template will be called with the current scope but extra options may be passed which will be added to the context.

{{template "path/to/template" key="value"}}

If a block is used, the template will have a variable named yield available that will contain the contents of the block.

{{#template "child"}}
 content in the block will be available in a variable 
 named "yield" inside the template "child"
{{/template}}

This is useful when a child template will be called from multiple different parents.

view {{view name [options]}}

Embed one view in another. The first argument may be the name of a new view to initialize or a reference to a view that has already been initialized.

{{view "path/to/view" key="value"}}
{{view viewInstance}}

element {{element name [options]}}

Embed a DOM element in the view. This uses a placeholder technique to work, if the placeholder must be of a certain type in order to work (for instance a tbody inside of a table) specify a tag option.

{{element domElement tag="tbody"}}

registerViewHelper Handlebars.registerViewHelper(name [,viewClass] ,callback)

Note that this differs from Handlebars.registerHelper. Registers a helper that will create and append a new HelperView instance, with it's template attribute set to the value of the captured block. callback will recieve any arguments passed to the helper followed by a HelperView instance. Named arguments to the helper will be present on options attribute of the HelperView instance.

A HelperView instance differs from a regular view instance in that it has a parent attribute which is always set to the declaring view, and a context which always returns the value of the parent's context method. The collection, empty and other built in block view helpers are created with registerViewHelper.

A helper that re-rendered a HelperView every time an event was triggered on the declaring view could be implemented as:

Handlebars.registerViewHelper('on', function(eventName, helperView) {
 //register a handler on the parent view, which will be automatically
 //unregistered when helperView is destroyed
 helperView.on(helperView.parent, eventName, function() {
 helperView.render();
 });
});

An example use of this would be to have a counter that would incriment each time a button was clicked. In Handlebars:

{{#on "incrimented"}}{{i}}{/on}}
{{#button trigger="incrimented"}}Add{{/button}}

And the corresponding view class:

new Thorax.View({
 events: {
 incrimented: function() {
 ++this.i;
 }
 },
 initialize: function() {
 this.i = 0;
 },
 template: ...
});

Util

tag Thorax.Util.tag(name, htmlAttributes [,content] [,context])

Generate an HTML string. All built in HTML generation uses this method. If context is passed any Handlebars references inside of the htmlAttributes values will rendered with the context.

Thorax.Util.tag("div", {
 id: "div-{{number}}"
}, "content of the div", {
 number: 3
});

$

$.view $(event.target).view([options])

Get a reference to the nearest parent view. Pass helper: false to options to exclude HelperViews from the lookup. $.model and $.collection will also be available if you include the model and collection plugins.

$(event.target).view()

Events

destroyed destroyed ()

Triggered when the destroy method is called.

rendered rendered ()

Triggered when the rendered method is called.

child child (instance)

Triggered every time a child view is inserted into the view with the view helper. Will not be triggered from view instances created by helper view helpers.

helper helper (name [,args...] ,helperView)

Triggered when a view helper (such as collection, empty, etc) create a new HelperView instance.

helper:name helper:name [,args...] ,helperView)

Triggered when a given view helper creates a new HelperView instance.

{{
view.on('helper:collection', function(collection, collectionView) {
});

HTML Attributes

Thorax and it's view helpers generate a number of custom HTML attributes that may be useful in debugging or generating CSS selectors to be used as arguments to $ or to create CSS. The *-cid attributes are generally used only internally. See $.model, $.collection and $.view to get a reference to objects directly from the DOM. The *-name attributes will only be present if the given objects have a name property.

Attribute Name	Attached To
data-view-cid	Every view instances' el
data-view-name	Same as above, only present on named views
data-collection-cid	Element generated by the collection helper
data-collection-name	Same as above, only present when the bound collection is named
data-collection-empty	Set to "true" or "false" depending on wether the bound collection isEmpty
data-model-cid	A view's el if a model was bound to the view or each item element inside of elements generated by the collection helper
data-model-name	Same as above, only present if the model is named
data-layout-cid	The element generated by the layout helper or el inside of a LayoutView or ViewController instance
data-view-helper	Elements generated by various helpers including collection and empty from the collection plugin
data-call-method	Elements generated by the link and button helpers
data-trigger-event	Elements generated by the link and button helpers

When creating CSS selectors it's recommended to use the generated attributes (especially data-view-name) rather than assigning custom IDs or class names for the sole purpose of styling.

[data-view-name="my-view-name"] {
 border: 1px solid #ccc;
}

Command Line

To use the command line utilities:

npm install -g thorax

build thorax build target [plugin] [plugin...]

Build a custom version of Thorax using a list of any of the given plugins:

• mixin
• event
• model
• collection
• helpers
• form
• view-controller
• loading
• mobile

Not specifying any plugins will build a version with all plugins except mobile. To build a version of Thorax with all plugins including the mobile plugin run:

thorax build ./thorax-mobile.js 

templates thorax templates ./templates ./templates.js

If using Thorax outside of the provided node or Rails downloads you can inline a directory of templates into a single file by running the thorax templates command.

npm install -g thorax
thorax templates ./templates-dir ./templates.js

Error Handling

onException Thorax.onException(name, error)

Bound DOM event handlers in Thorax are wrapped with a try / catch block, calling this function if an error is caught. This hook is provided primarily to allow for easier debugging in Android environments where it is difficult to determine the source of the error. The default error handler is simply:

function(name, error) {
 throw error;
}

Override this function with your own logging / debugging handler. name will be the event name where the error was thrown.

Copyright 2012 @WalmartLabs

Backbone.Syphon - serialize the forms in your Backbone.Views into a JSON object for use with Backbone's models.

Backbone.Syphon

Working with form elements in a Backbone view can become very tedious very quickly. You will either end up writing a lot of repetitive code to read values from the form, or end up using a key-value-observer or data-binding solution that automatically populates your model for you. While these are valid options and I highly recommend understanding how they work, there are times when these options are not the best choice for your application.

Backbone.Syphon aims to make it easy to serialize the form inputs of a Backbone.View in to a simple JSON object that contains all of the values from the form.

Source Code And Downloads

You can download the raw source code from the "src" folder above, or grab one of the builds from the "lib" folder.

To get the latest stable release, use these links which point to the 'master' branch's builds:

Standard Builds

Development: backbone.syphon.js

Production: backbone.syphon.min.js

AMD/RequireJS Builds

Development: backbone.syphon.js

Production: backbone.syphon.min.js

Documentation

This readme file contains basic usage examples.

Extensibility / API Documentation

If you need to modify the behaviors of Syphon, see the API document. It contains the documentation for the core APIs that Syphon exposes, with examples on how to change the behaviors of Syphon.

Annotated Source Code

Syphon has annotated source code using the Docco tool to turn comments in to documentation. This provides an in-depth look at what each section of is doing.

Basic Usage : Serialize

When the data from a form is needed, you can call the serialize method of Backbone.Syphon to retrieve an object literal that contains the data from your view's form.

Backbone.View.extend({
 events: {
 "submit form": "formSubmitted"
 },
 formSubmitted: function(e){
 e.preventDefault();
 var data = Backbone.Syphon.serialize(this);
 this.model.set(data);
 this.model.save();
 },
 render: function(){
 // build the view's form, here
 }
});

Keys Retrieved By "name" Attribute

The default behavior for serializing fields is to use the field's "name" attribute as the key in the serialized object.

<form>
 <input name="a">
 <select name="b"></select>
 <textarea name="c"></textarea>
</form>

Backbone.Syphon.serialize(view);
// will produce => 
{
 a: "",
 b: "",
 c: ""
}

For information on how to change this behavior, see the Key Extractors section of the API Documentation.

Values Retrieved By jQuery .val() Call

The default behavior for serializing fields is to use jQuery's .val() to get the value of the input element.

<form>
 <input name="a" value="a-value">
 <textarea name="b">b-value</textarea>
</form>

Backbone.Syphon.serialize(view);
// will produce => 
{
 a: "a-value",
 b: "b-value",
}

For information on how to change this behavior, see the Input Readers section of the API Documentation.

Checkboxes

By default, a checkbox will return a boolean value signifying whether or not it is checked.

<form>
 <input type="checkbox" name="a">
 <input type="checkbox" name="b" checked>
</form>

Backbone.Syphon.serialize(view);
// will produce => 
{
 a: false,
 b: true
}

For information on how to change this behavior, see the Input Readers section of the API Documentation.

Radio Button Groups

Radio button groups (grouped by the input element "name" attribute) will produce a single value, from the selected radio button.

<form>
 <input type="radio" name="a" value="1">
 <input type="radio" name="a" value="2" checked>
 <input type="radio" name="a" value="3">
 <input type="radio" name="a" value="4">
</form>

Backbone.Syphon.serialize(view);
// will produce => 
{
 a: "2"
}

This behavior can be changed by registering a different set of Key Extractors, Input Readers, and Key Assignment Validators. See the full API Documentation. for more information on these.

Basic Usage : Deserialize

Syphon also allows you to deserialize an object's values back on to a form. It uses the same conventions and configuration as the serialization process, with the introduction of Input Writers to handle populating the form fields with the values. See the full API Documentation. for more information on Input Writers.

<form>
 <input type="text" name="a">
 <input type="text" name="b">
</form>

var data = {
 a: "foo",
 b: "bar"
};
Backbone.Syphon.deserialize(this, data);

This will populate the form input elements with the correct values from the data parameter.

Ignored Input Types

The following types of input are ignored, and not included in the resulting JavaScript object:

• <input type="submit"> buttons
• <input type="reset"> buttons
• standard <button> tags
• <fieldset> tags

If you need to get a value from the specific button that was clicked, you can either include it specifically (see below) or use a DOM event to listen for that element being manipulated (clicked, for example) and manually grab the data you need.

Ignoring Other Input Types

Syphon exposes the list of ignored input types as a raw array. You can push, pop, and manipulate this array as any other array, to specify which types of input fields you want to ignore.

This list is global to Syphon and there is no way to customize it for a specific call to serialize.

// ignore all <textarea> input elements
Backbone.Syphon.ignoredTypes.push("textarea");

Serializing Nested Attributes And Field Names

Syphon will parse nested attribute names and create a nested result object, using the Rails standard of name="foo[bar][baz]" by default.

<form>
 <input type="text" name="foo[bar]" value="a value">
 <input type="text" name="foo[baz][quux]" value="another value">
</form>

will produce

{
 foo: {
 bar: "a value",
 baz: {
 quux: "another value"
 }
 }
}

Include / Exclude Specific Fields

You can include or exclude specific fields as needed. Inclusion is given priority and specifying fields to include will force Syphon to exclude all other fields. Including a field that is ignore by it's type will also force the field to be included.

Examples

Given this HTML:

<form>
 <input name="a" value="a-value">
 <input name="b" value="b-value">
 <input name="c" value="c-value">
 <button name="d" value="d-value">
</form>

The following will occur:

// include a, b only
Backbone.Syphon.serialize(view, {
 include: ["a", "b"]
});
// will produce =>
{
 a: "a-value",
 b: "b-value"
}

// include the normally excluded (button) "d"
Backbone.Syphon.serialize(view, {
 include: ["a", "d"]
});
// will produce =>
{
 a: "a-value",
 d: "d-value"
}

// exclude a
Backbone.Syphon.serialize(view, {
 exclude: ["a"]
});
// will produce =>
{
 b: "b-value",
 c: "c-value"
}

// include a and b, exclude b and c
Backbone.Syphon.serialize(view, {
 include: ["a", "b"],
 exclude: ["b", "c"]
});
// will produce =>
{
 a: "a-value",
 b: "b-value"
}

Include / Exclude Based On Key Extractors

The include / exclude process uses the registered Key Extractors to determine which fields to include / exclude.

This means if you are only using the default Key Extractor which uses the "name" attribute, all fields will be included or excluded based on the name of the field.

If you have registered other Key Extractors, they will be used when determining which fields to include / exclude.

<form>
 <input id="a">
 <input type="radio" name="b">
 <input id="c">
 <input type="radio" name="d">
</form>

// By default, use the "id"
Backbone.Syphon.KeyExtractors.registerDefault(function($el){
 return $el.prop("id");
});
// For radio buttons, use the "name"
Backbone.Syphon.KeyExtractors.register("radio", function($el){
 return $el.prop("name");
});
// Serialize the form
Backbone.Syphon.serialize(view, {
 exclude: ["a", "b"]
});
// This will produce =>
{
 c: "",
 d: ""
}

For more information on Key Extractors, see the full API Documentation.

Other Options

There are a few other options that can be specified when calling the Syphon.serialize method, which allow the behavior of Syphon to be altered for a single call instead of for all calls.

Key Extractors

Key extractors are used to generate the "key" in the {key: "value"} result. You can specify a KeyExtractorSet as part of the options:

extractors = new Backbone.Syphon.KeyExtractorSet();
// configure it ...
Backbone.Syphone.serialize({
 keyExtractors: extractors
});

For more information on Key Extractors, see the full API Documentation.

Input Readers

Input Readers are used to generate the "value" in the {key: "value"} result. You can specify a InputReadetSet as part of the options:

readers = new Backbone.Syphon.InputReaderSet();
// configure it ...
Backbone.Syphone.serialize({
 inputReaders: readers
});

For more information on Input Readers, see the full API Documentation.

Input Writers

Input Writers are used to set the value of form elements to the "value" in the {key: "value"} data / object. At this time, you cannot specify input writers in the deserialize method. That will come soon, hopefully.

For more information on Input Writers, see the full API Documentation.

Key Assignment Validators

Input Readers are used to validate the assignment of a key to a value, in the context of an element. You can specify a InputReadetSet as part of the options:

validators = new Backbone.Syphon.KeyAssignmentValidators();
// configure it ...
Backbone.Syphone.serialize({
 keyAssignmentValidators: validators
});

For more information on Key Assignment Validators, see the full API Documentation.

Current Limitations

There some known limitations in Backbone.Syphon, partially by design and partially implemented as default behaivors.

• You must have a <form> within your view's $el
• An input of type checkbox will return a boolean value. This can be overriden by replacing the Input Reader for checkboxes.

Building Backbone.Syphon

If you wish to build Backbone.Syphon on your system, you will need Ruby to run the Jasmine specs, and NodeJS to run the grunt build.

To Run The Jasmine Specs

1. Be sure you have Bundler installed in your Ruby Gems. Then run bundle install from the project folder

2. Once this is done, you can run rake jasmine to run the Jasmine server

3. Point your browser at http://localhost:8888 and you will see all of the specs for Backbone.Syphon

To Build The Packages

1. Be sure you have NodeJS and NPM installed on your system

2. Run npm install -g grunt to install the grunt build system

3. From the project folder, run grunt to produce a build

Screencasts

I've recorded several screencasts on how I built Syphon.

Release Notes

See the changelog.md file.

Legal Mumbo Jumbo (MIT License)

Copyright (c) 2012 Derick Bailey, Muted Solutions, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Backbone.LayoutManager

v0.7.3

Created by Tim Branyen @tbranyen, with help from awesome contributors

Provides a logical structure for assembling layouts with Backbone Views. Designed to be adaptive and configurable for painless integration. Well tested, with over 140 assertions and 100% code coverage!

Tested with Underscore & Lo-Dash, Backbone and jQuery. You can swap out jQuery with a custom configuration or substitute Underscore with Lo-Dash.

Documentation

Refer to: http://tbranyen.github.com/backbone.layoutmanager/

Migration guide: https://github.com/tbranyen/backbone.layoutmanager/pull/184

Release notes

• Refactored _.extend to LayoutManager.augment to work with Lo-Dash and underscore.
• Normalized rendering order, when the parent has already rendered.
• Added better error handling for node.js build.
• Updated error message for node.js build.
• Added in Travis-CI and README updates.

Full Release Log

Donate

I do my very best to ensure top quality and continued progress with LayoutManager. Developers using, but not contributing, may want to consider leaving a small donation to show their appreciation.

All funds collected will find their way to the mspca organization. Thanks! :)

Features

URL-Action Mapping

According to Backbone's Router component, the hash fragments (#page) or a portion of the static url can be used for routing. It's the same for BackboneMVC's routing strategy. In this documentation, we will assume you use the hash fragment method.

Like CakePHP, the hash fragments are divided by slashes into three parts: controller name, method and optional parameters.

 URL_TO_ROUTE := CONTROLLER_NAME '/' METHOD_NAME (ADDITIONAL_PARAMETERS)
 ADDITIONAL_PARAMETERS := '/' LITERAL_VALUE (ADDITIONAL_PARAMETERS )
 CONTROLLER_NAME := LITERAL_VALUE
 METHOD_NAME : LITERAL_VALUE
 LITERAL_VALUE: [^/]+
 

Examples:

• controller1/method1
• my_controller/my-method/happy/birthday

The optional parameters can be 0 or many, which are also separated by slash(/). No matter how many parameters are in the url, they will all be tossed over to the method in the order of appearance.

BackboneMVC.Controller.extend({
 name: 'my_controller', /* the only mandatory field */
 'my-method': function(how, when){
 var phrase = how + ' ' + (when || 'unknown');
 this._output(phrase);
 },
 _output: function(string){
 $('#area1').append($('<div>' + string + '</div>'));
 }
})

Try it in action:

Trigger my-method() with 2 parameters:
#my_controller/my-method/happy/birthday

Trigger my-method() with 1 parameter:
#my_controller/my-method/happy

Private methods can't be triggered. This helps maintain your encapsulation.

Trigger a private method (this will fail): my_controller/_output/really?

Asynchronous Calling

The navigate() method of Backbone's Router component can trigger url routing programmatically. BackboneMVC further enhances this method, and the method now returns a JQuery Deferred object. You can use it to make sure the action method has finished. This is useful when making asynchronous calls.

See the following example:

var AsynchronousController = BackboneMVC.Controller.extend({
 name: 'asynchronous', /* the only mandatory field */
 'method': function(){
 var deferred = new $.Deferred();
 var colors = ['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'purple'];
 var index = 0;
 var instance = this;
 (function op(){
 if(index 
 
         
 
See it in action:
 
Trigger the procedure1() method: 
Click here to trigger
 procedure1()
 
Event Hooks
 
Like CakePHP, before and after invoking an action method, beforeFilter and
 afterRender event handlers can also be set.
 
For example:
 
 BackboneMVC.Controller.extend({
 name: 'event_hooks', /* the only mandatory field */
 beforeFilter: function(){
 this._report('beforeFilter invoked');
 },
 method1: function(){
 this._report('method1 invoked');
 },
 method2: function(){
 var index = 0;
 var instance = this;
 var deferred = new $.Deferred();
 (function op(){
 if(index ++ < 5){
 instance._report(index);
 setTimeout(op, 345);
 }else{
 deferred.resolve();
 }
 })();
 return deferred;
 },
 afterRender: function(){
 this._report('afterRender invoked');
 },
 _report: function(text){
 $('#area3').append('<div>' + text + '</div>');
 }
});
 
 

 
Trigger mehtod1() #event_hooks/method1
 
If your action method return a Deferred object, then the afterRender event hook will be
 deferred in execution
 
Trigger method2() #event_hooks/method2
 
Rules for the call chain of beforeFilter, afterRender and the action method 
 

• All of the beforeFilter, afterRender and the action method can opt to return a Deferred object. If either of them does, then its successor will wait on the predecessor's Deferred object. Unless the Deferred object is resolved, all the subsequent methods on the chain won't be executed.
• If a predecessor return a non-deferred value, and the value can be evaluated to true, the successor will run as it does normally, or otherwise the call chain will be interrupted.
• If a predecessor doesn't return a value, the successor will run as it does normally.
• If at any point, the call chain is interrupted, either by a rejected object or a false value, and the navigate() method is used to issue the call, the returned Deferred object from navigate() will be rejected.

See the following example:

var EventHooks1= BackboneMVC.Controller.extend({
 name: 'event_hooks1', /* the only mandatory field */
 beforeFilter: function(){
 this._report('beforeFilter invoked');
 //always successful (can also be achieved if return nothing)
 return true;
 },
 method1: function(){
 this._report('method1 invoked');
 var deferred = new $.Deferred();
 var colors = ['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'purple'];
 var index = 0;
 var instance = this;
 (function op(){
 if(index < colors.length){
 instance._changeColor(colors[index++]);
 setTimeout(op, 234);
 }else{
 deferred.resolve();
 }
 })();
 return deferred;
 },
 method2: function(){
 this._changeColor('MidnightBlue');
 this._report('method2 invoked');
 this._report('afterRender won\'t be executed');
 return false; // a false value, the subsequent method has no chance to be executed
 },
 method3: function(){
 this._changeColor('Indigo');
 this._report('method3 invoked');
 this._report('afterRender will be executed');
 // return nothing has the same effect as returning true
 },
 afterRender: function(){
 // reject, so the call chain will eventually fail even though the
 // main action method is executed
 this._report('afterRender invoked');
 return (new $.Deferred()).reject();
 },
 _report: function(text){
 $('#area4').append('<div>' + text + '</div>');
 },
 _changeColor: function(color){
 $('#area4').css('backgroundColor', color);
 }
});
window['procedure2'] = function(){
 var r = router.navigate('event_hooks1/method2', {trigger:true, replace: false});
 r.done(function(){
 (new EventHooks1())._report('procedure2 successful');
 }).fail(function(){
 (new EventHooks1())._report('procedure2 failed');
 });
};
window['procedure3'] = function(){
 var r = router.navigate('event_hooks1/method3', {trigger:true, replace: false});
 r.done(function(){
 (new EventHooks1())._report('procedure3 successful');
 }).fail(function(){
 (new EventHooks1())._report('procedure3 failed');
 });
};

Trigger method1() #event_hooks1/method1

Trigger procedure2() procedure2()

Trigger procedure3() procedure3()

When used with Deferred objects, the event hooks can be useful if you want to prepare templates for your actions to render views, or select the corresponding navigation entry for all the actions in the controller after their execution.

Session Checking

Similar to beforeFilter and afterRender methods, you can also define a checkSession method. Then all action methods with a prefix of 'user_' in their names, will be invoked only after the checkSession is called.

If checkSession returns false or a Deferred object, which will later be rejected, the action methods will not be invoked.

See example:

BackboneMVC.Controller.extend({
 name: 'session_enabled', /* the only mandatory field */
 beforeFilter: function(){
 this._report('beforeFilter invoked');
 return true;
 },
 checkSession: function(){
 this._report('checkSession invoked');
 var deferred = new $.Deferred();
 var instance = this;
 setTimeout(function(){
 instance._report('session is valid!');
 deferred.resolve();
 }, 2000);
 return deferred;
 },
 user_method1: function(){
 this._report('method1 invoked');
 },
 user_method2: function(){
 this._report('secure method2 invoked');
 this._changeColor('green');
 },
 method2: function(){
 this._report('normal method2 invoked');
 this._changeColor('DimGray');
 },
 _report: function(text){
 $('#area5').append('<div>' + text + '</div>');
 },
 _changeColor: function(color){
 $('#area5').css('backgroundColor', color);
 }
});

Trigger user_method1() #session_enabled/user_method1

You can even omit the 'user_' prefix:

Trigger method1() #session_enabled/method1

However if the method without the 'user_' prefix is already defined, then the shortcut will not overwrite the existing one, see example:

Trigger user_method2() #session_enabled/user_method2

Trigger method2() #session_enabled/method2

As you can see, the checkSession is invoked after beforeFilter, but before the action method.

Controllers Are Singletons

Controllers are all singletons. So no matter when and where you instantiate a controller, the instance always keeps the same state.

var Singleton = BackboneMVC.Controller.extend({
 name: 'singleton', /* the only mandatory field */
 value: 0,
 method: function(){
 this._report(this.value++);
 },
 _report: function(text){
 $('#area6').append('
' + text + '
');
 }
});
window['procedure4'] = function(){
 (new Singleton()).method();
};

Trigger method() #singleton/method

Call procedure4() procedure4()

Controller Inheritance

Controller.extend() can be used to do class inheritance. So your controllers are able to share functionality from their parent controller.

See example:

var Parent = BackboneMVC.Controller.extend({
 name: 'parent', /* the only mandatory field, even though the parent is not planned to be used,
 it will still need to be assigned a name. */
 method: function(){
 this._report('Parent method invoked');
 this._changeColor('#141F2E');
 },
 _report: function(text){
 $('#area7').append('<div>' + text + '</div>');
 },
 _changeColor: function(color){
 $('#area7').css('backgroundColor', color);
 }
});
var Child1 = Parent.extend({
 name: 'child1', /* the only mandatory field */
 method: function(){
 this._report('Child1 method invoked');
 this._changeColor('green');
 }
});
var Child2 = Parent.extend({
 name: 'child2' /* the only mandatory field */
 //this controller doesn't implement anything, so its parent's methods will be passed over.
});

Trigger Child1::method() #child1/method

Trigger Child2::method() #child2/method

Custom Routing Rules

When BackboneMVC's automatic routing doesn't suffice for your requirements, customized routing rules can be used to comply with backbone.js' convention. This can be achieved by further extending the BackboneMVC.Router class.

 var MyExtendedRouter = BackboneMVC.Router.extend({
 routes:{
 '' : 'index',
 'root/action/hardcoded_value': 'special_handling'
 },
 index: function(){
 // do customized logic, for example, launch a default controller's action
 router.navigate("root/index", {trigger:true, replace: true});
 },
 special_handling: function(){
 (new RootController())._report(
 "I just thought of something more important to do.";
 );
 (new RootController())._changeColor("purple");
 }
 });
 var RootController = BackboneMVC.Controller.extend({
 name: "root", /* the only mandatory field */
 index: function(){
 this._report("'index' method invoked");
 this._changeColor("blue");
 },
 action: function(param){
 this._report("'action' method triggered with " + param);
 this._changeColor("red");
 },
 _report: function(text){
 $("#area8").append("<div>' + text + '</div>");
 },
 _changeColor: function(color){
 $("#area8").css("backgroundColor", color);
 }
 });

Trigger routing for empty hash #

Some hash patterns that do not follow BackboneMVC's automatic routing can be dealt with this way, especially the empty hash which usually points to a default index page. The default controller's default action can be redirected to, as the example above shows, or any other code logic can be used.

If you define custom rules, they will always have higher priority than BackboneMVC's automatic routing. See examples:

Trigger special_handling() #root/action/hardcoded_value

Trigger RootController::method() #root/action/offer

# Backbone.ViewMaster Few **tested** opinions on how to handle deeply nested views in [Backbone.js][] focusing on encapsulation and reusability. This is implemented after writing several Backbone.js applications and by carefully picking the recurring patterns seen on them. Backbone.ViewMaster is a single View extended from Backbone.View. Views extended from it can be infinitely nested with each others using the four nesting methods [setView][], [appendView][], [prependView][] and [insertView][]. There is no separate concept of layouts or list views. It's just a humble Backbone View Class with versatile nesting capabilities. The main idea behind Backbone.ViewMaster is that views should be small and independent building blocks of application UI. Read the tutorial to see how it's encouraged. Created by [Esa-Matti Suuronen][esa] [@EsaMatti][]. # Download - [backbone.viewmaster.js][dev] **12K** with comments - [backbone.viewmaster.min.js][production] **2.7K** minified # API Docs [Here][api] # Tutorial In this tutorial we build the classic TODO app and go through the most important features of Backbone.ViewMaster while discussing the ideas behind them. ## Basics `Backbone.ViewMaster` is a View extended from `Backbone.View`. You start by extending your custom views from it. Lets define a layout for our app with some container elements for our nested views. ``` ``` ```javascript var TodoLayout = Backbone.ViewMaster.extend({ template: function(context){ return _.template($("#layout").html(), context); } }); ``` First thing you do for every ViewMaster view is set a [template][] function for it. It can be any function which takes a context object as the first argument and returns neither a HTML string or a DOM object. The context object is by default `this.model.toJSON()` or an empty object if your view does not have a model. You can customize this behavior by overriding the [context][] method. There is no need to define the [render][] method. ViewMaster already defines it and uses your template function to populate the `this.el` element. ## Nesting Now we create a nested view for the `addview-container`. ``` ``` ```javascript var AddTodoItem = Backbone.ViewMaster.extend({ template: function(context){ return _.template($("#addview").html(), context); }, events: { "click button": "addTodo" }, addTodo: function(e){ e.preventDefault(); this.collection.add(new Backbone.Model({ text: this.$("input").text() }); } }); ``` Nested views are also extended from `Backbone.ViewMaster`. Any ViewMaster view can be nested in any ViewMaster view and you can do as deep nesting as you want. Since we wanted this to be the view for the `addview-container` and because it's an element of `TodoLayout` it is the responsibility of `TodoLayout` to nest it. We do that in its constructor using the [setView][] method. ```javascript // TodoLayout constructor: function(){ Backbone.ViewMaster.prototype.constructor.apply(this, arguments); this.setView(".addview-container", new AddTodoItem({ collection: this.collection })); }, ``` Here it's important to notice that [setView][] and its friends, [appendView][], [prependView][], [insertView][] and [getViews][] should be considered in Java terms as protected methods. Which means you should use them only from within the view definition. This is because they all take a CSS selector as the first argument and because the CSS selectors are very implementation specific details of your view. If you need to set the view from the outside create a setter method for it to keep your views encapsulated and maintainable. ## Event management Event management is important part of view management in Backbone.js. Unfortunately the event callbacks start easily leaking memory if you don't remember to unbind them when you are done with the views. ViewMaster helps with this by introducing a [bindTo][] method which is bound to the view context. It will unbind all event callbacks automatically when you discard the view with [remove][]. ```javascript // TodoLayout constructor: function(){ ... snip ... this.bindTo(this.model, "change", this.render); }, ``` ## Rendering Now we are ready to create and render our nested view. We do that by calling the default render method. ```javascript var items = new Backbone.Collection(); var app = new Backbone.Model(); var layout = new TodoLayout({ model: app, collection: items }); layout.render(); $("body").append(layout.el); app.set("name", prompt("Your name")); ``` The render method takes care of rendering itself and the initial rendering of its child views. This means it will **render child views only once** unless `{ force: true }` is passed to the render method. This is because normally it should be the responsibility of the child view to know when it should render itself. The parent view only helps child views to get started. ### Child views We add new TodoItems to our layout whenever a todo model is added to the collection. When a new child view is added you need to call [render][] or [renderViews][] on the parent view to make them visible. ```javascript // TodoLayout constructor: function(){ ... snip ... this.bindTo(this.model, "change", this.render); this.bindTo(this.collection, "add", this.addItem); }, addItem: function(model){ this.appendView(".todo-container", new TodoItem({ model: model })); this.renderViews(); } ``` Here we use the [appendView][] method to append a view to `.todo-container` when a model is added to the collection. Every view container can contain multiple views. Just start adding more views to it if you need lists. The difference between [render][] and [renderViews][] is that the latter one renders only the new child views and adds them to the parent DOM tree leaving the parent untouched otherwise while the former renders the parent itself and the children. ## Removing views Any view, parent or child, can be discarded with the [remove][] method. It removes automatically all the Backbone and DOM event callbacks. If the view is a parent to other views it will call remove on them also. ``` ``` ```javascript var TodoItem = Backbone.ViewMaster.extend({ constructor: function(){ Backbone.ViewMaster.prototype.constructor.apply(this, arguments); this.bindTo(this.model, "change", this.render); }, template: function(context){ return _.template($("#item").html(), context); }, events: { "click .done": "done", "click .edit": "edit" }, done: function(){ this.model.destroy(); this.remove(); }, edit: function() { var newContent = prompt("Edit todo", this.$(".item").text()); if (newContent !== null) this.model.set("text", newContent); } }); ``` Views can be also removed by replacing them with [setView][]. ViewMaster automatically figures out which views was left out and calls [remove][] on them on the next [renderViews][] call. If you need to use the view and its children again some time later use the [detach][] method. It removes the view from in its parent view, but leaves the event callbacks untouched and children untouched. ## Event bubbling In order to keep views decoupled and resusable their implementation should not assume anything about their parents. When you need to communicate with the parent use events to send messages to them. Backbone.ViewMaster helps with this by implementing DOM like event bubbling: Event triggered in a child view is also seen on its parents all the way up to the view tree unless explicitly silenced. ```javascript // Bubbled event "refresh" to parents view.trigger("refresh"); // Do not bubble event "myevent" to parents view.trigger("myevent", { parent: false }); ``` ## Conclusion That's about it. Check out the full working todo app in the examples [directory][todo-example] or play with the live app [here][todo-live]. # FAQ ## How do I use jQuery plugins? Just override the render method, call the super method and then do your jQuery plugin stuff: ```javascript render: function(){ Backbone.ViewMaster.prototype.render.apply(this, arguments); this.$("element").jqueryPlugin(); } ``` ## Doesn't `Backbone.View#dispose()` unbind events already on remove? Some. It only works with events bound to `this.model` or `this.collection` and it also requires that the view is passed as the context object to the `on` method. To make sure that all events are always unbound on remove I recommend that you use always `view.bindTo(...)` with Backbone.ViewMaster. *DISCLAIMER: `dispose()` is a feature of unreleased Backbone.js version and it might change before actual release.* # License The MIT License. See LICENSE. [Backbone.js]: http://backbonejs.org/ [@EsaMatti]: https://twitter.com/EsaMatti [esa]: http://esa-matti.suuronen.org/ [dev]: http://epeli.github.com/backbone.viewmaster/lib/backbone.viewmaster.js [production]: http://epeli.github.com/backbone.viewmaster/lib/backbone.viewmaster.min.js [api]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html [setView]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_setView [appendView]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_appendView [prependView]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_prependView [insertView]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_insertView [bindTo]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_bindTo [template]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_template [render]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_render [renderViews]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_renderViews [context]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_context [rendered]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#property_rendered [getViews]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_getViews [detach]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_detach [remove]: http://epeli.github.com/backbone.viewmaster/classes/Backbone.ViewMaster.html#method_remove [todo-example]: https://github.com/epeli/backbone.viewmaster/tree/master/examples/todos [todo-live]: http://epeli.github.com/backbone.viewmaster/examples/todos