BackboneDiorama is everything you need to build client-side web applications. Optimised for developer happiness, it builds on the components of Backbone.js and aims to be the easiest and the fastest way to build for the browser.
diorama new projectNamebuilds you a new project with:
diorama generate <lots-of-stuff>- Rails-style code generators which provide convention and structure to your projects, assist you with proven patterns and allow you to rapidly prototype. Run
diorama generatefor the full list.
We've been using BackboneDiorama to build applications for a little while now, but this is just the first public release. There's lots more planned (AMD support, testing defaults, minification, coffeescript source maps and more generators...) and if you've got any feedback or suggestions, we'd love to hear from you!
Install Backbone Diorama (and its handlebars dependency) as an NPM package:
npm install -g handlebars backbone-diorama
To view the available commands, run:
Running most commands without arguments will give you the usage.
diorama new <ProjectName>
This will create a new diorama project inside a directory of the same
name. It creates an
index.html file containing starting instructions.
Use generators to scaffold your code, for example:
diorama generate collection Tasks diorama generate view TaskIndex
For a complete list of generators available, run:
diorama compile watch
This command watches your src/ folder for changes then concatenates and compiles the files specified in src/compile_manifest.json to js/application.js. The files should be specified in the order you require them, in this format:
When you run a generator, it will print the includes you need to add to this file.
To run the compile once (without watching for changes), omit the 'watch' argument:
TodoMVC-style app, built by @amulligan:
An attempt to create Ableton-like music remixing in the browser, built by @th3james:
Used diorama in a project you want to share? Let us know and we'll add it here.
BackboneDiorama is ready to drop straight into your server side framework.
in Rails), include the the compiled js/application.js in your app, then use
Diorama as normal.
If you're using Rails or another framework with built in coffeescript
compilation, just include the coffeescripts in your src/ directly. Your
templates will still need to be compiled, which you can do by inserting only
the handlebars templates into compile_manifest.json, then using
diorama compile watch to compile them to js/application.js
BackboneDiorama comes with a few extra classes to compliment the backbone stack for building complete web applications:
Creates a DOM element designed for swapping views in and out of, with helper methods to manage unbinding events.
Diorama controllers are designed to coordinate views and data, and provide entry points to certain 'states' of your application. Routers in BackboneDiorama projects only handle URL reading and setting, but defer to controllers for the actual behavior.
A common pattern for Backbone applications is to nest views inside each other. For example a collection index view where each model in the collection gets a sub view. The advantage of this approach is that each sub view can listen for and respond to events about a particular model, removing the need for the collection view to be re-rendered.
Backbone.Diorama.NestingView makes it easy to stack views like this.
BackboneDiorama is released under the MIT License
BackboneDiorama is written in coffeescript and is packaged as an NPM module. To install the package locally, in the project directory run:
npm install -g
This will install the diorama command onto your system. On my node setup, this wasn't added to my PATH correctly, so check the output for a line like:
npm info linkStuff firstname.lastname@example.org /usr/local/share/npm/bin/diorama -> /usr/local/share/npm/lib/node_modules/backbone-diorama/bin/diorama.coffee
Tests are written using mocha, and in the test/ folder (somewhat unsurprisingly). Run the diorama command tests with:
There are integrations tests for the Diorama libraries in test/libTests, open index.html in that folder to run them.