Chaplin is an architecture for JavaScript applications using the Backbone.js library.
- Documentation and Support
- Commercial Support and Training
- Key Features
- Motivation
- Dependencies
- Download Chaplin
- Building Chaplin
- Running the Tests
- Boilerplates
- Examples
- The Cast
- The Producers
- We’re working on a comprehensive documentation and class reference on Github.
- For general support and discussion, there’s a Google Group, a forum on ost.io and an IRC channel
#chaplinjs
on Freenode. - If you’d like to report a bug or propose a feature, please use the Github issues. The issue tracker can also be used for general questions and task management.
- Follow Chaplin.js on Twitter to get updates on new versions, major changes and the ongoing development.
9elements — Berlin/Bochum, Germany
One of the creators of Chaplin, is offering commercial support and training for Chaplin and Backbone-based JavaScript applications. 9elements is a software and design agency located in Berlin and Bochum, Germany. Send us a mail for more information: contact@9elements.com.
Paul Miller — Kharkiv, Ukraine
Chaplin & Brunch maintainer is offering consulting & training for all Backbone-related stuff. Contact him: paul+chaplin@paulmillr.com.
Concordus Applications — Sacramento, CA, USA
Offering commerical support and training for Chaplin and Backbone-based JavaScript applications. Concordus Applications is an enterprise integration and software development firm. Email us for more information: support@concordusapps.com.
- CoffeeScript class hierarchies as well as object composition
- Module encapsulation and lazy-loading using AMD modules
- Cross-module communication using the Mediator and Publish/Subscribe patterns
- Introducing Controllers that represent UI screens
- Rails-style declarative routes that map URLs to controller actions
- A route dispatcher and a top-level view manager
- Extended model, view and collection classes to avoid repetition and enforce conventions
- Strict memory management and object disposal
- A collection view for easy and intelligent list rendering
While developing several web applications using Backbone.js, we felt the need for conventions on how to structure such applications. Backbone is an easy starting point, but provides only basic, low-level patterns. Especially, Backbone provides little to structure an actual application. For example, the famous “Todo list” is not an application in the strict sense nor does it teach best practices how to structure Backbone code.
Backbone doesn’t intend to be an all-round framework so it’s not appropriate to blame Backbone for these deliberate limitations. Nonetheless, most Backbone use cases need a sophisticated application architecture.
This is where Chaplin enters the stage. Chaplin is derived from the codebase of moviepilot.com, a real-world single-page application. It draws attention to the top-level architecture: everything above simple routing, individual models, views and their binding.
Chaplin depends on the following libraries:
- Backbone (> 0.9.2)
- Underscore (> 1.4.2) or lodash (> 0.8.2)
- jQuery (> 1.8.2) or Zepto (> 1.0rc1)
If you’ll be using AMD version, you will also need an AMD module loader like RequireJS, Almond or curl to load Chaplin and lazy-module application modules
-
Install the Node package for the Bower package manager.
sudo npm install -g bower
-
Install chaplin via bower.
bower install chaplin
Specific versions may be requested as follows:
bower install chaplin#0.6.0
This will also download the required version of backbone but will not download the required DOM manipulation or utility libraries. These can be installed separately via
bower install underscore
,bower install jquery
,bower install lodash
, etc.
Download the latest release on chaplinjs.org. See below on how to compile from source manually.
The Chaplin source files are originally written in the CoffeeScript meta-language. However, the Chaplin library file is a compiled JavaScript file which defines the chaplin
module.
Our build script compiles the CoffeeScripts and bundles them into one file. To run the script, follow these steps:
-
Download and install Node.js.
-
Open a shell (aka terminal aka command prompt) and type in the commands in the following steps.
-
Install the Node package for the grunt command line interface globally.
sudo npm install -g grunt-cli
On Windows, you can omit the
sudo
command at the beginning. -
Change into the Chaplin root directory.
-
Start the build (will install dependencies and build).
npm install
This creates two directories:
./build/amd/
with a build using the AMD module style./build/commonjs/
with a build using the CommonJS module style
These directories contain four files each:
chaplin.js
– The library as a compiled JavaScript file.chaplin.min.js
– Minified. For production use you should pick this.chaplin.min.js.gz
– Minified and GZip-compressed.
Chaplin aims to be fully unit-tested. At the moment most of the modules are covered by Mocha tests.
How to run the tests:
-
Follow the steps for building chaplin.
-
Open a shell (aka terminal aka command prompt) and type in the commands in the following steps.
-
Change into the Chaplin root directory.
-
Start the test runner.
npm test
Note that you can now additionally open test/index.html
to run the tests in your browser (instead of in node).
Furthermore code coverage reports are generated and may be viewed by opening test/coverage/index.html
in your browser.
Chaplin needs a simple skeleton to start up and configure the core modules. We provide several boilerplates to make the start easier.
Chaplin Boilerplate is a “Hello world” example project using Chaplin. If you’re not a CoffeeScript user, there’s also a plain JavaScript boilerplate.
For Ruby on Rails users, we’ve compiled a Boilerplate Rails Application with Backbone, Chaplin and Require.js.
github.com/paulmillr/brunch-with-chaplin
Brunch with Chaplin is a skeleton application, where brunch is used for assembling files & assets. It has ready-to-use classes for session management, html5boilerplate and stylus / handlebars.js as app languages.
Several example applications are available today:
github.com/chaplinjs/facebook-example
This example uses Facebook client-side authentication to display the user’s Likes.
github.com/paulmillr/ostio is a forum for GitHub projects and a modern replacement for mailing lists.
Ost.io serves as a good example of a fast service-based application, using Ruby on Rails as a lightweight backend (which is open-sourced too) that only handles authentication / server-side logic & talks JSON to clients. In this way, the frontend is completely decoupled from the backend which gives the ability to work on both projects in parallel and increases scalability, speed & maintainability quite a lot.
github.com/brunch/twitter is a simple twitter client. It uses Twitter client-side authentication to display user’s feed and to create new tweets.