README.md in ember-rails-lite-0.11.1 vs README.md in ember-rails-lite-0.12.0

- old
+ new

@@ -5,34 +5,64 @@ The gem will also pre-compile your handlebars templates when building your asset pipeline. It includes development and production copies of Ember. You can see an example of how to use the gem [here](https://github.com/keithpitt/ember-rails-example). There is also a great tutorial by [Dan Gebhardt](https://twitter.com/#!/dgeb) called "[Beginning Ember.js on Rails](http://www.cerebris.com/blog/2012/01/24/beginning-ember-js-on-rails-part-1/)" which is a great read if you're just starting out with Rails and Ember.js ## Getting started +1. Add the gem to your application Gemfile: +```ruby +gem 'ember-rails' +gem 'ember-source', '1.0.0.rc4' # or the version you need +gem 'handlebars-source', '1.0.0.rc4' # or the version you need +``` -Add the gem to your application Gemfile: +2. Run `bundle install` - gem "ember-rails" +3. [Optional] Configure the ember variant in your environment files (i.e. development.rb, production.rb). If you don't configure this, the version of Ember used defaults to development when the Rails environment is development, and similarly for production. +```ruby + config.ember.variant = :development # or :production +``` -Run `bundle install` and use the ember-rails generator to add the necessary dependencies. +4. Next, generate the application structure: +```shell +bundle exec rails generate ember:bootstrap +``` -Ember-rails will use the production build of Ember.js when Rails is running in -production mode, and the development build otherwise. +5. Restart your server (if it's running) + +Notes: + +To install the latest builds of ember and ember-data: +```shell +bundle exec rails generate ember:install --head +``` + +## For CoffeeScript support +1. Add coffee-rails to the Gemfile +```ruby +gem 'coffee-rails' +``` + +2. Run the bootstrap generator in step 4 with an extra flag instead: +```sh +rails g ember:bootstrap -g --javascript-engine coffee +``` + ## Architecture -Ember does not require an organized file structure. However, ember-rails allows you +Ember does not require an organized file structure. However, ember-rails allows you to use `rails g ember:bootstrap` to create the following directory structure under `app/assets/javascripts`: controllers/ helpers/ models/ routes/ templates/ views/ Additionally, it will add the following lines to `app/assets/javascripts/application.js`. -By default, it uses the Rails Application's name and creates an `rails_app_name.js` +By default, it uses the Rails Application's name and creates an `rails_app_name.js` file to setup application namespace and initial requires: //= require handlebars //= require ember //= require ember-data @@ -78,11 +108,11 @@ Default behavior for ember-rails is to precompile handlebars templates. If you don't want this behavior you can turn it off in your application configuration (or per environment in: `config/environments/development.rb`) block: config.handlebars.precompile = false - + _(Note: you must clear the local sprockets cache if you disable precompilation, stored by default in `tmp/cache/assets`)_ Bundle all templates together thanks to Sprockets, e.g create `app/assets/javascripts/templates/all.js` with: @@ -93,43 +123,52 @@ <%= javascript_include_tag "templates/all" %> If you use Slim or Haml templates, you can use handlebars filter : handlebars: - {{#view Ember.Button}}OK{{/view}} + <button {{action anActionName}}>OK</button> It will be translated as : <script type="text/x-handlebars"> - {{#view Ember.Button}}OK{{/view}} + <button {{action anActionName}}>OK</button> </script> ## Specifying Different Versions of Ember/Handlebars/Ember-Data -By default, ember-rails ships with the latest version of -[Ember](https://rubygems.org/gems/ember-source/versions) (rc1), -[Handlebars](https://rubygems.org/gems/handlebars-source/versions) (rc3), -and [Ember-Data](https://rubygems.org/gems/ember-data-source/versions). +![Ember Data Warning](ember-data-in-progress.png) +By default, ember-rails ships with the latest version of +[Ember](https://rubygems.org/gems/ember-source/versions), +[Handlebars](https://rubygems.org/gems/handlebars-source/versions), +and [Ember-Data](https://rubygems.org/gems/ember-data-source/versions). To specify a different version that'll be used for both template precompilation and serving to the browser, you can specify the desired version of one of the above-linked gems in the Gemfile, e.g.: gem 'ember-source', '1.0.0.pre4.2' You can also specify versions of 'handlebars-source' and 'ember-data-source', but note that an appropriate 'handlebars-source' will be automatically chosen depending on the version of 'ember-source' -that's specified. +that's specified. You can also override the specific ember.js, handlebars.js, and ember-data.js files that'll be `require`d by the Asset pipeline by placing these files in `vendor/assets/ember/development` and `vendor/assets/ember/production`, depending on the `config.ember.variant` you've specified in your app's configuration, e.g.: config.ember.variant = :production #config.ember.variant = :development + +## Updating Ember + +If at any point you need to update Ember.js from master, you can do that with + + rails generate ember:install --head + +This will fetch both Ember.js and Ember Data from [http://builds.emberjs.com/](http://builds.emberjs.com/) and copy to the right directory. ## Note on Patches/Pull Requests 1. Fork the project. 2. Make your feature addition or bug fix.