Chaplin is an architecture for JavaScript applications using the Backbone.js library. The code is derived from moviepilot.com, a large single-page application.
- Upcoming Version: Chaplin as a Library
- Support and Help
- Commercial Support and Training
- Key Features
- Motivation
- Dependencies
- Building Chaplin
- Running the Tests
- Boilerplate
- Examples
- Documentation
- The Cast
- The Producers
While the initial release of Chaplin was merely an example application structure, Chaplin is being rewritten into a reusable and fully unit-tested library. The master branch already reflects these changes. We’re almost done, the code is already stable and successfully used in production. We don’t expect breaking API changes until version 1.0. There are only a few things to polish up before the 1.0 release:
- A comprehensive documentation and class reference
- Easier configurability of the default behavior
- Flexibility, like use in non-CoffeeScript and non-AMD environments
How about joining us? You might have a look at the issue discussions.
- For general support and discussion, there’s a Google Group and a forum on ost.io.
- 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, 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: [email protected].
- 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
- Controllers for managing individual UI views
- Rails-style routes which 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. While Backbone is fine at what it’s doing, it’s not a framework for single-page applications. Yet it’s often used for this purpose.
Chaplin is mostly derived and generalized from the codebase of moviepilot.com, a real-world single-page application. Chaplin tries to draw the attention to top-level application architecture. “Application” means everything above simple routing, individual models, views and their binding.
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 example” is not an application in the strict sense nor does it teach best practices how to structure Backbone code.
To be fair, Backbone doesn’t intend to be an all-round framework so it wouldn’t be appropriate to blame Backbone for this deliberate limitations. Nonetheless, most Backbone use cases clearly need a sophisticated application architecture. This is where Chaplin enters the stage.
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
The individual source files of Chaplin are originally written in the CoffeeScript meta-language. However, the Chaplin library file is a compiled JavaScript file which defines a single chaplin module.
There’s a build script which compiles the CoffeeScripts and bundles them into one file. To run the script, follow these steps:
-
Download and install Node.js.
-
Install the Node packages for CoffeeScript and UglifierJS globally. Open a shell (aka terminal aka command prompt) and run these commands:
sudo npm install -g coffee-script sudo npm install -g uglify-jsThis assumes you’re working on a Unix machine (Linux, Mac OS, BSD…). On Windows, you can omit the
sudocommand at the beginning. -
Install the Node package ShellJS normally. On the shell, run this command:
npm install shelljs -
On the shell, start the build by typing:
cake build
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-VERSION.coffee– The Chaplin library as a CoffeeScript file.chaplin-VERSION.js– The library as a compiled JavaScript file.chaplin-VERSION-min.js– Minified. For production use you should pick this.chaplin-VERSION-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.
To run the tests, the source files and the specs need to be compiled using the CoffeeScript compiler first. Run cake test in the repository’s root directory, then open the test runner (test/index.html) in a browser.
Chaplin Boilerplate is a base application project for Chaplin. You can use it freely as a skeleton for your chaplin project.
If you’re not a CoffeeScript user, there’s also a plain JavaScript boilerplate: Chaplin Boilerplate-Plain
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, frontend is completely decoupled from the backend which gives the ability to work on both projects in parallel and increases scalability, speed & mainbtability 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.
All docs are located in docs/ subdirectory.
