Make your Backbone.js apps dance!
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 applications.
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 the framework for building a 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. This allows you to work with other Backbone frameworks and plugins easily. It also means that you are not required to engage in an all-or-nothing migration to begin using Marionette.
Find us on gitter or on IRC in the FreeNode.net #marionette channel.
We're happy to discuss design patterns and learn how you're using Marionette.
- Scalable: applications are built in modules, and with event-driven architecture
- Sensible defaults: Underscore templates are used for view rendering
- Easily modifiable: 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 the
RegionandLayoutViewobjects - Nested views and layouts within visual regions
- Built-in memory management and zombie-killing in views, regions and layoutViews
- Event-driven architecture with
Backbone.Wreqr.EventAggregator - Flexible, "as-needed" architecture allowing you to pick and choose what you need
- And much, much more
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 visit the downloads section on the website.
Marionette is available via bower, npm, and component.io. There are other channels that are maintained by the community.
Changelog: For change logs and release notes, see the changelog file.
Upgrade Guide: Be sure to read the upgrade guide for information on upgrading to the latest version of Marionette.
The primary documentation is split up into multiple files, due to the size of the overall 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.
In addition to this readme, the source code is documented heavily and run through Docco as part of the build process.
You can read the annotations for all the details of how Marionette works, and advice on which methods to override.
Views
- Marionette.ItemView: A view that renders a single item
- Marionette.CollectionView: A view that iterates over a collection, and renders individual
ItemViewinstances for each model - Marionette.CompositeView: A collection view and item view, for rendering leaf-branch/composite model hierarchies
- Marionette.LayoutView: A view that renders a layout and creates region managers to manage areas within it
- Marionette.View: The base View type that other Marionette views extend from (not intended to be used directly)
Behaviors
- Marionette.Behavior: an encapsulated
Viewinteraction layer that can be mixed into anyview, helping to DRY up your view code. - Marionette.Behaviors: A helper class to glue your behaviors to your views.
View Management
- Marionette.Region: Manage visual regions of your application, including display and removal of content
- Marionette.RegionManager: Manage a group of related Regions
- Marionette.Renderer: Render templates with or without data, in a consistent and common manner
- Marionette.TemplateCache: Cache templates that are stored in
<script>blocks, for faster subsequent access - [→] Backbone.BabySitter: Manage child views for your Backbone.View (and other parents)
Application Infrastructure
- Marionette.Application: An application object that starts your app via initializers, and more
- Marionette.Module: Create modules and sub-modules within the application
- Marionette.Controller: A general purpose object for controlling modules, routers, view, and implementing a mediator pattern
- Marionette.Commands: An extension of Backbone.Wreqr.Commands, a simple command execution framework
- Marionette.RequestResponse: An extension of Backbone.Wreqr.RequestResponse, a simple request/response framework
- [→] 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
Other
- Marionette.AppRouter: Reduce your routers to nothing more than configuration
- Marionette.Callbacks: Manage a collection of callback methods, and execute them as needed
- Marionette.functions: A suite of helper functions and utilities for implementing common Marionette behavior in your objects
MarionetteJS currently works with the following libraries:
- jQuery v1.8+
- Underscore v1.4.4 - 1.6.0
- Backbone v1.0.0 - 1.1.2 are preferred. v0.9.9 and v0.9.10 should work still
- Backbone.Wreqr Comes automatically with the bundled build.
- Backbone.BabySitter Comes automatically with the bundled build.
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.
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 into the next release.
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).
Copyright (c) 2012-2014 Derick Bailey; Muted Solutions, LLC
Distributed under MIT license.