readme.md

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

Compatibility And Requirements

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.

Marionette.Async Add-on

Marionette.Async has officially been removed from the core Marionette
repository. See the Marionette.Async repository
for downloads, documentation, and more information.

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 peice of Marionette.

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.

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.

Release Notes

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.