thorax

NOTICE:

This repository has been archived and is not supported.

NOTICE: SUPPORT FOR THIS PROJECT HAS ENDED

This projected was owned and maintained by Walmart. This project has reached its end of life and Walmart no longer supports this project.

We will no longer be monitoring the issues for this project or reviewing pull requests. You are free to continue using this project under the license terms or forks of this project at your own risk. This project is no longer subject to Walmart's bug bounty program or other security monitoring.

Actions you can take

We recommend you take the following action:

• Review any configuration files used for build automation and make appropriate updates to remove or replace this project
• Notify other members of your team and/or organization of this change
• Notify your security team to help you evaluate alternative options

Forking and transition of ownership

For security reasons, Walmart does not transfer the ownership of our primary repos on Github or other platforms to other individuals/organizations. Further, we do not transfer ownership of packages for public package management systems.

If you would like to fork this package and continue development, you should choose a new name for the project and create your own packages, build automation, etc.

Please review the licensing terms of this project, which continue to be in effect even after decommission.

Thorax

An opinionated, battle tested Backbone + Handlebars framework to build large scale web applications.

Quick Start

• Generate your application using the Thorax Yeoman Generator
• Read about how Thorax works in the new Backbone Fundamentals Book.
• Install the Thorax Inspector Chrome extension.
• Building something smaller? Just link the core library as a single file from cdnjs compiled with all of its dependencies and use it anywhere or play with our Hello World fiddle or Todos fiddle.

Features

Hello World

Thorax is used to build some of the biggest Backbone applications in the world but it's easy to get started.

var view = new Thorax.View({
  greeting: "Hello",
  template: Handlebars.compile("{{greeting}} world!")
});
view.appendTo('body');

Easy Data Binding

By default every property of your view is automatically available in the template. If a model is bound its attributes will also be made available.

var view = new Thorax.View({
  greeting: 'Hello',
  model: new Thorax.Model({
    location: 'world!'
  }),
  template: ...
});

Then in your template:

{{greeting}} {{location}}

Context Control

Don't like every property in your view being available in your template, or need to modify some model attributes? Just specify a context method to control what your template sees:

var view = new Thorax.View({
  model: new Thorax.Model({
    greeting: 'hello'
  }),
  context: function() {
    return {
      greeting: this.model.get('greeting').toUpperCase()
    };
  },
  template: ...
});

Then in your template:

{{greeting}}

Collection Rendering

Easily render collections with the collection helper. Thorax will make sure that your view stays current as models in your collection are added, removed or updated.

var view = new Thorax.View({
  collection: new Thorax.Collection([{
    title: 'Finish screencast',
    done: true
  }]),
  template: ...
});

Then in your template:

{{#collection tag="ul"}}
  

    
{{else}}

No todos yet.

{{/collection}}

jQuery and Zepto Integration

Thorax extends the jQuery or Zepto $ object to allow you to get a reference to the nearest bound model, collection, or view.

var view = new Thorax.View({
  events: {
    'change input[type=checkbox]': function(event) {
      var model = $(event.target).model();
      model.set({done: event.target.checked});
    }
  }
});

Event Enhancements

Thorax extends the events hash to let you listen to view events in addition to DOM events, and let's you pass a hash of model or collection events to listenTo when a model or collection is bound to your view.

var view = new Thorax.View({
  events: {
    rendered: function() {}
    model: {
      change: function() {}
    }
  },
  model: new Thorax.Model()
});

Thorax also adds inheritable events to view classes, just call on on any class to listen for a DOM, view, model or collection event on any view.

Thorax.View.on('eventName', handler);

Form Handling

Easily capture entered form data with the serialize method which also provides event hooks for form validation. Models bound to the view will also automatically populate your forms.

var view = new Thorax.View({
  events: {
    'submit form': function(event) {
      event.preventDefault();
      var attrs = this.serialize();
      this.collection.add(attrs);
    }
  },
  collection: new Thorax.Collection()
});

Embeddable Views

Easily embed one view within another with the view helper.

var view = new Thorax.View({
  child: new Thorax.View(...),
  template: ...
});

Then in your template:

{{view child}}

Layouts and Lifecycle

Thorax.LayoutView provides a container to place your views, and triggers lifecycle events on views placed within them. Layouts can be embedded in other views as well.

var layout = new Thorax.LayoutView();
layout.appendTo('body');
var view = new Thorax.View({
  events: {
    ready: function() {},
    destroyed: function() {}
  }
})
layout.setView(view);

Server Side Rendering

Thorax allows for rendering outside of the normal browser context using environments such as [Fruit Loops][fruit-loops] or [PhantomJS][phantomjs] to render content in the initial server response and then restore the view hierarchy on the client render. Rendering in such a manner allows for Thorax applications to expose their content for SEO purposes as well as speed up the perceived initial page load.

The restore process is well suited for handling distinctions between user and public data, allowing for the server response to include only public, long cache-able, content. The client can then augment this data with any user specific data on restoration.

Getting Started

Tutorials/Examples

Thorax Yeoman Generator

Using the Thorax Generator, you can generate a Todos example application. You can also generate a blank application and build it out to match the Todos example app. This is a great way to learn by doing.

Thorax in Backbone Fundamentals

Read an overview of the features of Thorax, as well as some of the theory behind some of the implementation details.

Route Based Module Loading

Backbone Fundamentals also covers Lumbar's approach to modular application development and routing, which is used in all of the seed projects except the standalone and Rails seeds.

Thorax Seed

Thorax seed provides an example of a Lumber and Server-Side JavaScript project in action. This commit shows an example of converting an existing Thorax+Lumbar application to support SSJS.

TodoMVC

See the TodoMVC Thorax implementation and its source code. There is also a Lumbar flavored version of the implementation.

kenwheeler has an example Parse-Todos implementation of Thorax combined with Parse.

Examples

• mulderp/thorax-movies
• colinmegill/thorax-contacts-list-require-tutorial

Resources

Thorax Yeoman Generator

The Thorax Generator will ask you questions before generating a new blank or predefined base project. This is the recommended way to get started.

The Thorax Generator also provides it's own extensive documentation and aims to help you understand how to setup a full stack Thorax application, including a minimal node express server and deployment instructions.

Bower component

Thorax is available as a Bower component. Just run bower install thorax in your project.

Thorax is tested against these dependencies (you can paste this in your bower.json:

"dependencies": {
  "jquery": "1.9.0",
  "underscore": "1.4.4",
  "zepto": "1.0.0",
  "handlebars": "1.0.0",
  "backbone": "1.0.0"
}

Note that either jQuery or Zepto is required, but not both.

cdnjs

Thorax is available on cdnjs, each build includes jQuery 1.9.0 (or Zepto 1.0.0rc1 on mobile), Backbone 0.9.9, Underscore 1.4.2 and Handlebars 1.0.0rc6.

• Thorax
• Thorax (compressed)
• Thorax Mobile
• Thorax Mobile (compressed)

Playground

When combined with CoffeeScript small Thorax apps can be written in a single file. This is ideal for creating small test apps within JSFiddle. Thorax can be selected as a framework (near the bottom of the list) in any fiddle, or you can try out any of the fiddles below:

• Hello World
• Todos
• $
• HelperView
• LayoutView & Lifecycle
• Embedding

API Reference

Registry

Thorax creates a special hash for each type of class to store all subclasses in your application. The use of Thorax.Views and Handlebars.templates (usually defined by Handlebars) is required to allow the view, template and other helper methods to operate, but the use of Thorax.Models and Thorax.Collections are optional and provided for consistency.

  Class
  Registry

Thorax.ViewThorax.Views

Thorax.ModelThorax.Models

Thorax.CollectionThorax.Collections

templatesHandlebars.templates

name klass.prototype.name

If a name property is passed to any Thorax classes' extend method the resulting class will be automatically set in the corresponding registry.

//set class
Thorax.View.extend({
  name: "my-view"
});

//get class
Thorax.Views["my-view"]

templates Handlebars.templates

A hash of templates, used by various Thorax helpers. If using the Lumb