<commit_before>![Chaplin](http://s3.amazonaws.com/imgly_production/3401027/original.png)

# An Application Architecture Using Backbone.js

## Introduction

Chaplin is an architecture for JavaScript applications using the [Backbone.js](http://documentcloud.github.com/backbone/) library. The code is derived from [moviepilot.com](http://moviepilot.com/), a large single-page application.

* [Upcoming Version: Chaplin as a Library](#upcoming-version-10-chaplin-as-a-library)
* [Stay Tuned for Updates](#stay-tuned-for-updates)
* [Key Features](#key-features)
* [Motivation](#motivation)
* [Dependencies](#dependencies)
* [Building Chaplin](#building-chaplin)
* [Running the Tests](#running-the-tests)
* [Boilerplate and Examples](#boilerplate-and-examples)
* [The Architecture in Detail](#the-architecture-in-detail)
* [Application](#application)
* [Mediator and Publish/Subscribe](#mediator-and-publishsubscribe)
* [Router](#router)
* [Dispatcher](#dispatcher)
* [Layout](#layout)
* [Controllers](#controllers)
* [Models and Collections](#models-and-collections)
* [Views](#views)
* [Event Handling Overview](#event-handling-overview)
* [Memory Management and Object Disposal](#memory-management-and-object-disposal)
* [Handling Asynchronous Dependencies](#handling-asynchronous-dependencies)
* [The Cast](https://github.com/chaplinjs/chaplin/blob/master/AUTHORS.md#the-cast)
* [The Producers](https://github.com/chaplinjs/chaplin/blob/master/AUTHORS.md#the-producers)

## Upcoming Version 1.0: Chaplin as a Library

While the [initial release of Chaplin](https://github.com/chaplinjs/chaplin/tree/0.3) was merely an example application structure, our goal is to generalize Chaplin into a separate, reusable and unit-tested library.

There’s a major rewrite going on and the `master` branch already reflects these changes. This includes several topics:

- Improving and generalizing the Chaplin architecture
- Writing unit-tests for all Chaplin components
- Creating a [boilerplate app](https://github.com/chaplinjs/chaplin-boilerplate) and [application examples](#boilerplate-and-examples)
- Writing an up-to-date documentation and writing a class & method reference

Most of this is already done, so the code is already quite stable and successfully used in production. We don’t expect breaking API changes since version 1.0. There are only a few things to polish up before the 1.0 release:

- [A comprehensive documentation](http://chaplinjs.github.com/)
- Flexibility, like use in non-CoffeeScript and non-AMD environments
- Easier configurability of the default behavior

How about joining us? You might have a look at the [issue discussions](https://github.com/chaplinjs/chaplin/issues). There is also a [forum](http://ost.io/chaplinjs/chaplin) and [mailing list for discussion on Google Groups](https://groups.google.com/forum/?hl=en&fromgroups#!forum/chaplin-js
).

## Stay tuned for updates

[Follow Chaplin.js on Twitter](https://twitter.com/chaplinjs) to get updates on new versions, major changes and the ongoing development.

---

## Key Features

* 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

## Motivation

![Modern Times](http://s3.amazonaws.com/imgly_production/3359809/original.jpg)

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](http://stackoverflow.com/questions/148747/what-is-the-difference-between-a-framework-and-a-library) for single-page applications. Yet it’s often used for this purpose.

Chaplin is mostly derived and generalized from the codebase of [moviepilot.com](http://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.

## Dependencies

Chaplin depends on the following libraries:

* [Underscore](http://documentcloud.github.com/underscore/)
* [Backbone](http://documentcloud.github.com/backbone/)
* [jQuery](http://jquery.com/) or [Zepto](http://zeptojs.com)
* An AMD module loader like [RequireJS](http://requirejs.org/), [Almond](https://github.com/jrburke/almond) or [curl](https://github.com/cujojs/curl) to load Chaplin and lazy-module application modules

## Building Chaplin

The individual source files of Chaplin are originally written in the [CoffeeScript](http://coffeescript.org/) meta-language. However, the Chaplin library file is a compiled JavaScript file which defines the `chaplin` AMD module.

There’s a Ruby build script in `build/build.rb` which compiles the CoffeeScripts and bundles them into one file. Before running the script, please make sure you have installed a [Ruby interpreter](http://www.ruby-lang.org/en/downloads/) and [Node.js with NPM](http://nodejs.org/#download).

Also, you need to install the Node packages for CoffeeScript and UglifierJS globally:

```
sudo npm install -g coffee 
sudo npm install -g uglify-js
```

If you’re using Ruby 1.8, you need to install the JSON gem:

```
gem install json
```

After that, run the Ruby script `build.rb` in the `build` directory:

```
cd build
./build.rb
```

This creates several files in ./build/:

* `chaplin.coffee` – The Chaplin library in one CoffeeScript file.
* `chaplin.js` – The same as a compiled JavaScript file. Normally you want to pick this.
* `chaplin-min.js` – Minified
* `chaplin-min.js.gz` – Minified and GZip-compressed
<commit_msg>Correct node coffeescript installation instructions<commit_after>![Chaplin](http://s3.amazonaws.com/imgly_production/3401027/original.png)

# An Application Architecture Using Backbone.js

## Introduction

Chaplin is an architecture for JavaScript applications using the [Backbone.js](http://documentcloud.github.com/backbone/) library. The code is derived from [moviepilot.com](http://moviepilot.com/), a large single-page application.

* [Upcoming Version: Chaplin as a Library](#upcoming-version-10-chaplin-as-a-library)
* [Stay Tuned for Updates](#stay-tuned-for-updates)
* [Key Features](#key-features)
* [Motivation](#motivation)
* [Dependencies](#dependencies)
* [Building Chaplin](#building-chaplin)
* [Running the Tests](#running-the-tests)
* [Boilerplate and Examples](#boilerplate-and-examples)
* [The Architecture in Detail](#the-architecture-in-detail)
* [Application](#application)
* [Mediator and Publish/Subscribe](#mediator-and-publishsubscribe)
* [Router](#router)
* [Dispatcher](#dispatcher)
* [Layout](#layout)
* [Controllers](#controllers)
* [Models and Collections](#models-and-collections)
* [Views](#views)
* [Event Handling Overview](#event-handling-overview)
* [Memory Management and Object Disposal](#memory-management-and-object-disposal)
* [Handling Asynchronous Dependencies](#handling-asynchronous-dependencies)
* [The Cast](https://github.com/chaplinjs/chaplin/blob/master/AUTHORS.md#the-cast)
* [The Producers](https://github.com/chaplinjs/chaplin/blob/master/AUTHORS.md#the-producers)

## Upcoming Version 1.0: Chaplin as a Library

While the [initial release of Chaplin](https://github.com/chaplinjs/chaplin/tree/0.3) was merely an example application structure, our goal is to generalize Chaplin into a separate, reusable and unit-tested library.

There’s a major rewrite going on and the `master` branch already reflects these changes. This includes several topics:

- Improving and generalizing the Chaplin architecture
- Writing unit-tests for all Chaplin components
- Creating a [boilerplate app](https://github.com/chaplinjs/chaplin-boilerplate) and [application examples](#boilerplate-and-examples)
- Writing an up-to-date documentation and writing a class & method reference

Most of this is already done, so the code is already quite stable and successfully used in production. We don’t expect breaking API changes since version 1.0. There are only a few things to polish up before the 1.0 release:

- [A comprehensive documentation](http://chaplinjs.github.com/)
- Flexibility, like use in non-CoffeeScript and non-AMD environments
- Easier configurability of the default behavior

How about joining us? You might have a look at the [issue discussions](https://github.com/chaplinjs/chaplin/issues). There is also a [forum](http://ost.io/chaplinjs/chaplin) and [mailing list for discussion on Google Groups](https://groups.google.com/forum/?hl=en&fromgroups#!forum/chaplin-js
).

## Stay tuned for updates

[Follow Chaplin.js on Twitter](https://twitter.com/chaplinjs) to get updates on new versions, major changes and the ongoing development.

---

## Key Features

* 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

## Motivation

![Modern Times](http://s3.amazonaws.com/imgly_production/3359809/original.jpg)

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](http://stackoverflow.com/questions/148747/what-is-the-difference-between-a-framework-and-a-library) for single-page applications. Yet it’s often used for this purpose.

Chaplin is mostly derived and generalized from the codebase of [moviepilot.com](http://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.

## Dependencies

Chaplin depends on the following libraries:

* [Underscore](http://documentcloud.github.com/underscore/)
* [Backbone](http://documentcloud.github.com/backbone/)
* [jQuery](http://jquery.com/) or [Zepto](http://zeptojs.com)
* An AMD module loader like [RequireJS](http://requirejs.org/), [Almond](https://github.com/jrburke/almond) or [curl](https://github.com/cujojs/curl) to load Chaplin and lazy-module application modules

## Building Chaplin

The individual source files of Chaplin are originally written in the [CoffeeScript](http://coffeescript.org/) meta-language. However, the Chaplin library file is a compiled JavaScript file which defines the `chaplin` AMD module.

There’s a Ruby build script in `build/build.rb` which compiles the CoffeeScripts and bundles them into one file. Before running the script, please make sure you have installed a [Ruby interpreter](http://www.ruby-lang.org/en/downloads/) and [Node.js with NPM](http://nodejs.org/#download).

Also, you need to install the Node packages for CoffeeScript and UglifierJS globally:

```
sudo npm install -g coffee-script
sudo npm install -g uglify-js
```

If you’re using Ruby 1.8, you need to install the JSON gem:

```
gem install json
```

After that, run the Ruby script `build.rb` in the `build` directory:

```
cd build
./build.rb
```

This creates several files in ./build/:

* `chaplin.coffee` – The Chaplin library in one CoffeeScript file.
* `chaplin.js` – The same as a compiled JavaScript file. Normally you want to pick this.
* `chaplin-min.js` – Minified
* `chaplin-min.js.gz` – Minified and GZip-compressed

{'fraction_non_alphanumeric': 0.10025687518887881, 'fraction_numerical': 0.005137503777576307, 'mean_word_length': 5.1826249416160675, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 18, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6140967', 'n_tokens_mistral': 3821, 'n_tokens_neox': 3636, 'n_words': 1382}