Batman.js is no longer in production at Shopify and is not actively maintained.

This website is left for reference (and for old times' sake).

batman.js

One of the conventions that batman.js shares with Rails is that of a consistent and organized directory structure. Whenever you sit down at any batman.js or Rails project, you should immediately know in which folder and file any given class will live. Here's what the directory structure looks like for a default batman.js app:

MyApp
├── index.html
├── my_app.coffee
├── controllers
|   ├── application_controller.coffee
|   └── products_controller.coffee
├── models
|   └── product.coffee
├── html
|   └── products
|       ├── index.html
|       ├── show.html
|       └── new.html
├── views
|   └── products
|       ├── products_index_view.coffee
|       ├── products_show_view.coffee
|       └── products_new_view.coffee
├── lib
|   └── my_helper.coffee
├── vendor
|   ├── jquery.js
|   └── batman.js
└── resources

An overview of what each of these does:

File / Directory Description

index.html

The browser's entry point for your application. Your index file should include everything in vendor (like batman.js), have enough of your layout HTML so that the browser can display something immediately, and then load my_app.coffee.

my_app.coffee

The main entry point for your application. It should include everything else in your app directory (like controllers and models), declare all the routes that your application will handle, do any other initial setup or preloading, and finally call App.run().

controllers

Holds all of your controller classes. Every controller should represent exactly one resource or model or type of data in your system. Another way of looking at it is every page or piece of distinct functionality can have its own controller. Controller names should be the plural of their resource type followed by the word "Controller", i.e. MyApp.ProductsController. File names should be the snake-cased version of the class name, i.e. products_controller.coffee.

models

Holds all of your model classes. Every model should also represent exactly one resource. Model names should be the singular of their resource type, i.e. MyApp.Product. File names should be the snake-cased version of the class name, i.e. product.coffee.

html

Holds the individual blocks of HTML that will be rendered when a controller action is dispatched. The HTML directory is further subdivided into directories for every controller. Inside every controller directory is an HTML file with the name of the corresponding action, i.e. products/index.html.

views

Holds your custom CoffeeScript view classes that can either be rendered implicitly or explicitly by your app. Follows a similar naming convention to the HTML files, but the class names are ControllerName + ActionName + View, i.e. MyApp.ProductsIndexView.

lib

A dumping ground for all the other little snippets of code your app collects. Things like helpers, mixins, events, or plugins can all be safely left in lib.

vendor

All of the external dependencies that your app has, such as batman.js, jQuery, or jQuery plugins if you're using those.

resources

A convenient place to leave things like images and css files.

Help us improve our documentation!

Contributions to this page are welcome on Github. If you find a problem but you cannot fix it, please open an issue.

Discussion regarding batman.js documentation is also welcome on our mailing list.