Make your Backbone.js apps dance!
App Architecture On Backbone's Building Blocks
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.
- 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 application's specific needs
- Reduce boilerplate for views, with specialized view types
- Build on a modular architecture with an
Applicationand modules that attach to it
- Compose your application's visuals at runtime, with
- Nested views and layouts within visual regions
- Built-in memory management and zombie killing in views, regions and layouts
- Event-driven architecture with
- Flexible, "as-needed" architecture allowing you to pick and choose what you need
- And much, much more
Compatibility And Requirements
MarionetteJS currently works with the following libraries:
- jQuery v1.8.x or v1.9.x
- Underscore v1.4.3
- Backbone v0.9.9 or v0.9.10
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 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.
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.
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
ItemViewinstances 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.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:
- Backbone.Wreqr.EventAggregator: An event aggregator, to facilitate pub/sub and event architecture. Part of a suite of messaging based patterns
- Backbone.Wreqr.Commands: A simple command execution system
- Backbone.Wreqr.RequestResponse: A simple request/response system
The following have been deprecated w/ Backbone v0.9.9+
- Backbone.EventBinder: An event binding manager for Backbone v0.9.2, to facilitate binding and unbinding of events
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 documentation file.
You can read the annotated for all the detail of how Marionette works, and advice on which methods to override when.
Marionette needs your support, but not everyone can offer assistance 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
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
#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 And Upgrade Guide
For change logs and release notes, see the changelog file.
Be sure to read the upgrade guide for information on upgrading to the latest version of Marionette.
Legal Mumbo Jumbo (MIT License)
Copyright (c) 2012 Derick Bailey; Muted Solutions, LLC
Distributed under MIT license.