Skip to content
This repository has been archived by the owner on Mar 20, 2021. It is now read-only.

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
eriktrom authored and kpdecker committed Sep 3, 2014
1 parent 4fea24b commit 3220cf1
Showing 1 changed file with 26 additions and 36 deletions.
62 changes: 26 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
**The [Thorax Yeoman generator](https://github.com/walmartlabs/generator-thorax) is presently under active development and is the best way to get started with Thorax. The docs here will be updated shortly to reflect this.**

# Thorax

[![Selenium Test Status](https://saucelabs.com/buildstatus/thorax)](https://saucelabs.com/u/thorax)
Expand All @@ -8,7 +6,7 @@ An opinionated, battle tested [Backbone](http://backbonejs.org/) + [Handlebars](

# Quick Start

- Clone the [Seed Project](http://github.com/walmartlabs/thorax-seed) and start building your own application.
- Generate your application using the [Thorax Yeoman Generator](https://github.com/walmartlabs/generator-thorax)
- Read about how Thorax works in the new [Backbone Fundamentals Book](http://addyosmani.github.com/backbone-fundamentals/#thorax).
- Install the [Thorax Inspector](https://chrome.google.com/webstore/detail/thorax-inspector/poioalbefcopgeaeaadelomciijaondk) Chrome extension.
- Building something smaller? Just link the [core library](http://github.com/walmartlabs/thorax) as a [single file from cdnjs](http://cdnjs.cloudflare.com/ajax/libs/thorax/2.0.0rc6/thorax.js) compiled with all of its dependencies and use it anywhere or play with our [Hello World fiddle](http://jsfiddle.net/KRuPZ/) or [Todos fiddle](http://jsfiddle.net/mZzhy/).
Expand Down Expand Up @@ -157,20 +155,20 @@ Then in your template:
})
layout.setView(view);

## Server Side Render
## 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 cacheable, content. The client can then augment this data with any user specific data on restoration.
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

### [From zero to todos](https://github.com/walmartlabs/thorax-seed/blob/master/README.md)
### [Thorax Yeoman Generator](https://github.com/walmartlabs/generator-thorax)

Did you enjoy the [screencast](http://vimeo.com/60230630)? Learn how to build your own simple todos app from scratch, with [step by step explanations](https://github.com/walmartlabs/thorax-seed/blob/master/README.md) of how the app was built.
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](http://addyosmani.github.com/backbone-fundamentals/#thorax)

Expand All @@ -185,15 +183,11 @@ See the [TodoMVC Thorax implementation](http://addyosmani.github.com/todomvc/lab

## Resources

### Seeds
### Thorax Yeoman Generator

Cloning a seed is the easiest way to get started building your own project.
The [Thorax Generator](https://github.com/walmartlabs/generator-thorax) will ask you questions before generating a new blank or predefined base project. This is the recommended way to get started.

- [Root Seed](https://github.com/walmartlabs/thorax-seed)
- [with Mocha test harness](https://github.com/eastridge/thorax-seed-mocha)
- [with simple Todos](https://github.com/eastridge/thorax-seed-todos)
- [Rails Seed (zip)](https://github.com/walmartlabs/thorax-boilerplate/blob/master/rails.zip?raw=true)
- [Standalone / HTML only Seed (zip)](https://github.com/walmartlabs/thorax-boilerplate/blob/master/standalone.zip?raw=true)
The [Thorax Generator](https://github.com/walmartlabs/generator-thorax) 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

Expand All @@ -220,10 +214,6 @@ Thorax is available on [cdnjs](http://cdnjs.com/), each build includes jQuery 1.
- [Thorax Mobile](http://cdnjs.cloudflare.com/ajax/libs/thorax/2.0.0rc6/thorax-mobile.js)
- [Thorax Mobile (compressed)](http://cdnjs.cloudflare.com/ajax/libs/thorax/2.0.0rc6/thorax-mobile.min.js)

### Chrome Inspector Extension

Chrome users can install the [Thorax Inspector](https://chrome.google.com/webstore/detail/thorax-inspector/poioalbefcopgeaeaadelomciijaondk) Chrome extension which will allow you to inspect any element and see the associated Thorax views, models and collections that may be bound. The [Thorax Seed](https://github.com/walmartlabs/thorax-seed) also integrates the [thorax-inspector](https://npmjs.org/package/thorax-inspector) npm package which allows you to open files in your project that relate to a given element, directly from Chrome.

### 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](http://jsfiddle.net/). 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:
Expand Down Expand Up @@ -270,7 +260,7 @@ If a `name` property is passed to any Thorax classes' `extend` method the result

### templates *Handlebars.templates*

A hash of templates, used by various Thorax helpers. If using the Lumbar or Rails boilerplate projects or the [Thorax Seed](http://github.com/walmartlabs/thorax-seed) this hash will be automatically generated from the files in your `templates` directories. To manually add a template to the hash:
A hash of templates, used by various Thorax helpers. If using the Lumbar or Rails boilerplate projects or the [Thorax Generator](https://github.com/walmartlabs/generator-thorax) this hash will be automatically generated from the files in your `templates` directories. To manually add a template to the hash:

Handlebars.templates['my-template-name'] = Handlebars.compile('template string');

Expand Down Expand Up @@ -1378,7 +1368,7 @@ By default this calls `Thorax.onException` when an exception is thrown but imple

Immediately executed version of `bindSection`. The default implementation delegates to `bindSection`.

# Server Rendering
## Server Rendering

Server side rendering relies can be performed in any environment that supports the `$` API as well as a few core APIs used to control the page life cycle.

Expand All @@ -1388,7 +1378,7 @@ Server side rendering relies can be performed in any environment that supports t

[Fruit Loops][fruit-loops] provides this functionality out of the box but this can be added to other environments with relative ease.

## Restore Process
### Restore Process

The restore process involves walking the DOM hierarchy looking for nodes that are annotated with the `data-view-restore` attribute. When such a node is found Thorax will attempt to restore based on a variety of steps discussed in the [Restore Methods](#restore-methods) section below.

Expand All @@ -1407,7 +1397,7 @@ The application restore process might look something like:

Followed by normal controller execution, ultimately culminating in `setView` call, which will restore the rendered child.

## Restore Methods
### Restore Methods

There is no definitive algorithm for restoring views, instead the following heuristics are used. In the event of a mismatch the `restore:fail` event will be emitted on the candidate view with additional debugging information regarding what portion of the heuristic failed.

Expand Down Expand Up @@ -1484,57 +1474,57 @@ Since pending fetch operations might rerender the content of a just restored vie

Note that there are issues that might arise if a different model data source is used on the client vs. the server, a personalized vs public data source for example. When such data is loaded prior to the restore operation, it might be necessary to provide a custom restore step that checks if this data has changed and rerender as there is no clean way for Thorax to determine if a model's data has changed between the two states.

# Error Codes
## Error Codes

## button-trigger
### button-trigger

`button` helper must have a method name as the first argument or a 'trigger', or a 'method' attribute specified.

## link-href
### link-href

`link` helper requires an href as the first argument or an `href` attribute.

## collection-element-helper
### collection-element-helper

`collection-element` helper must be declared inside of a `CollectionView`

## super-parent
### super-parent

Cannot use `super` helper when parent has no name or template.

## view-helper-hash-args
### view-helper-hash-args

Hash arguments are not allowed in the `view` helper as templates should not introduce side effects to view instances.

## layout-element-helper
### layout-element-helper

`layout-element` helper must be used within a `LayoutView`.

## mixed-fetch
### mixed-fetch

Both `set` and `reset` were passed to `fetch`, must use one or the other.

## nested-render
### nested-render

`render` was called which triggered an event handler which in turn called `render`. Infinite recursion was halted.

## handlebars-no-data
### handlebars-no-data

Handlebars template compiled without data, use: `Handlebars.compile(template, {data: true})`

## insert-destroyed
### insert-destroyed

A helper view that has been destroyed was inserted into the view.

## void-tag-content
### void-tag-content

A void tag such as `img` was rendered with `content` in `Thorax.Util.tag`.

## server-marshal-object
### server-marshal-object

A complex object was serialized without a proper context path to lookup the object on the client side. See [Thorax.ServerMarshal](#thoraxservermarshal) for more discussion on context paths.

## fn-view-unregistered
### fn-view-unregistered

`$.view` found a view element that was inserted manually into the DOM and was not registered with `_addChild` or `retain`. Call `parent._addChild(view)` or `view.retain()` on view insertion or instantiation.

Expand Down

0 comments on commit 3220cf1

Please sign in to comment.