ember-rails-lite 0.12.0 → 0.18.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5acffc3e20012e7fc795e19984e9b91c353ac820
+  data.tar.gz: cd1a0aef3ffc856aed8ded04fafeed9ce4193b62
+SHA512:
+  metadata.gz: f355b6562ad79ed46cd716928c4cb8c9b6f60c695268425d146cb5fc770092a3d47b49de19ca3f7d16748673c41d1d24e94e2b43639107aa863a7d9ac33a1d5e
+  data.tar.gz: 6bf2c080ca4f1b8dc6076fd0dc80a0d37e169c4e6996fc399314fa853870e184fce8ee0f5ce76c7b914ba05c79076841b1705f441b937338ddfa3198294f517b

data/README.md

@@ -1,74 +1,183 @@
-# ember-rails  [![Build Status](https://secure.travis-ci.org/emberjs/ember-rails.png?branch=master)](http://travis-ci.org/emberjs/ember-rails) [![Dependency Status](https://gemnasium.com/emberjs/ember-rails.png)](https://gemnasium.com/emberjs/ember-rails)
+# ember-rails  [![Build Status](https://secure.travis-ci.org/emberjs/ember-rails.svg?branch=master)](http://travis-ci.org/emberjs/ember-rails) [![Dependency Status](https://gemnasium.com/emberjs/ember-rails.png)](https://gemnasium.com/emberjs/ember-rails)
 
-ember-rails allows you to include [Ember.JS](http://emberjs.com/) into your Rails 3.1+ application.
+ember-rails makes developing an [Ember.JS](http://emberjs.com/) application much easier in Rails 3.1+.
 
-The gem will also pre-compile your handlebars templates when building your asset pipeline. It includes development and production copies of Ember.
+The following functionalities are included in this gem:
+- Pre-compiling of your handlebars templates when building your asset pipeline.
+- Inclusion of development and production copies of Ember, [Ember Data](https://github.com/emberjs/data) and [Handlebars](https://github.com/wycats/handlebars.js).
+- Inclusion of [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers) for integration with Ember Data.
 
-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
+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:
+* 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
+gem 'ember-source', '~> 1.9.0' # or the version you need
 ```
 
-2. Run `bundle install`
+* Run `bundle install`
+* Next, generate the application structure:
 
-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
-```
-
-4. Next, generate the application structure:
 ```shell
-bundle exec rails generate ember:bootstrap
+rails generate ember:bootstrap
 ```
 
-5. Restart your server (if it's running)
+* Restart your server (if it's running)
+
+## Building a new project from scratch
+
+Rails supports the ability to build projects from a template source ruby file.
+
+To build an Ember centric Rails project you can simply type the following into your command line:
+
+```
+rails new my_app -m http://emberjs.com/edge_template.rb
+```
 
+Read more about [Rails application templates](http://edgeguides.rubyonrails.org/rails_application_templates.html) and take a look at the edge_template.rb [source code](https://github.com/emberjs/website/blob/master/source/edge_template.rb).
 
 Notes:
 
-To install the latest builds of ember and ember-data:
+To install the latest builds of ember and ember-data. It should be noted that the
+examples in the [getting started guide](http://emberjs.com/guides/getting-started/)
+have been designed to use the released version of ember:
+
 ```shell
-bundle exec rails generate ember:install --head
+rails generate ember:install
 ```
 
+You'll probably need to clear out your cache after doing this with:
+
+```shell
+rake tmp:clear
+```
+
+Also, ember-rails includes some flags for the bootstrap generator:
+
+```
+--ember-path or -d   # custom ember path
+--skip-git or -g     # skip git keeps
+--javascript-engine  # engine for javascript (js, coffee or em)
+--app-name or -n     # custom ember app name
+```
+
+
 ## For CoffeeScript support
-1. Add coffee-rails to the Gemfile
+
+Add coffee-rails to the Gemfile
 ```ruby
 gem 'coffee-rails'
 ```
 
-2. Run the bootstrap generator in step 4 with an extra flag instead:
+Run the bootstrap generator in step 4 with an extra flag instead:
 ```sh
 rails g ember:bootstrap -g --javascript-engine coffee
 ```
 
+## For EmberScript support
+
+[EmberScript](http://www.emberscript.com) is a dialect of CoffeeScript
+with extra support for computed properties (which do not have to be
+explicitly declared), the `class` / `extends` syntax, and extra syntax
+to support observers and mixins.
+
+To get EmberScript support, make sure you have the following in your
+Gemfile:
+
+```ruby
+gem 'ember_script-rails', :github => 'ghempton/ember-script-rails'
+```
+
+You can now use the flag `--javascript-engine=em` to specify EmberScript
+assets in your generators, but all of the generators will default to
+using an EmberScript variant first.
+
+Note:
+
+Ember-rails include some flags options for bootstrap generator:
+
+```
+--ember-path or -d # custom ember path
+--skip-git or -g # skip git keeps
+--javascript-engine  # engine for javascript (js, coffee or em)
+--app-name or -n # custom ember app name
+```
+
+## Configuration Options
+
+The following options are available for configuration in your application or environment-level
+config files (`config/application.rb`, `config/environments/development.rb`, etc.):
+
+| Configuration Option                         | Description                                                                                                         |
+|----------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
+| `config.ember.variant`                       | Determines which Ember variant to use. Valid options: `:development`, `:production`. Defaults to `:production` in production, and `:development` everywhere else.                               |
+| `config.ember.app_name`                      | Specificies a default application name for all generators.                                                          |
+| `config.ember.ember_path`                    | Specifies a default custom root path for all generators.                                                            |
+| `config.handlebars.precompile`               | Enables or disables precompilation. Default value: `true`.                                                          |
+| `config.handlebars.templates_root`           | Sets the root path (under `app/assets/javascripts`) for templates to be looked up in. Default value: `"templates"`. |
+| `config.handlebars.templates_path_separator` | The path separator to use for templates. Default value: `'/'`.                                                      |
+| `config.handlebars.output_type`              | Configures the style of output (options are `:amd` and `:global`). Default value: `:global`.                        |
+| `config.handlebars.amd_namespace`            | Configures the module prefix for AMD formatted output. Default value: `nil`.                        |
+| `config.handlebars.ember_template`           | Default which Ember template type to compile. Valid options: `'Handlebars', `HTMLBars`. Defaults to 'Handlebars`' when `Ember::VERSION` is under 1.10.0, `HTMLBars` when `Ember::VERSION` is over 1.10.0. |
+
+Note:
+
+In a mountable engine, ember-rails will not recognize any configurations.
+Instead, use command line options.
+
+## Enabling Features with Feature Flags
+See [the guide](http://emberjs.com/guides/configuring-ember/feature-flags/#toc_flagging-details) and check [features.json](https://github.com/emberjs/ember.js/blob/master/features.json) for the version of Ember you're using.
+
+If a feature is set to false, you will need to compile ember from source yourself to include it.
+
+### Important note for projects that render JSON responses
+
+ember-rails includes [active_model_serializers](https://github.com/rails-api/active_model_serializers) which affects how ActiveModel and ActiveRecord objects get serialized to JSON, such as when using `render json:` or `respond_with`. By default active_model_serializers adds root elements to these responses (such as adding `{"posts": [...]}` for `render json: @posts`) which will affect the structure of your JSON responses.
+
+To disable this effect on your JSON responses, put this in an initializer:
+```Ruby
+# Stop active_model_serializers from adding root elements to JSON responses.
+ActiveModel::Serializer.root = false
+ActiveModel::ArraySerializer.root = false
+```
+
+See the [active_model_serializers](https://github.com/rails-api/active_model_serializers) documentation for a more complete understanding of other effects this dependency might have on your app.
+
 ## Architecture
 
 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/
+```
+├── adapters
+├── components
+├── controllers
+├── helpers
+├── mixins
+├── models
+├── practicality.js.coffee
+├── router.js.coffee
+├── routes
+├── store.js.coffee
+├── templates
+│   └── components
+└── 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`
-file to setup application namespace and initial requires:
-
-    //= require handlebars
-    //= require ember
-    //= require ember-data
-    //= require_self
-    //= require rails_app_name
-    RailsAppName = Ember.Application.create();
+file to set up application namespace and initial requires:
+
+```javascript
+//= require handlebars
+//= require ember
+//= require ember-data
+//= require_self
+//= require rails_app_name
+RailsAppName = Ember.Application.create();
+```
 
 *Example:*
 
@@ -82,8 +191,16 @@ file to setup application namespace and initial requires:
       create  app/assets/javascripts/views/.gitkeep
       create  app/assets/javascripts/helpers
       create  app/assets/javascripts/helpers/.gitkeep
+      create  app/assets/javascripts/components
+      create  app/assets/javascripts/components/.gitkeep
       create  app/assets/javascripts/templates
       create  app/assets/javascripts/templates/.gitkeep
+      create  app/assets/javascripts/templates/components
+      create  app/assets/javascripts/templates/components/.gitkeep
+      create  app/assets/javascripts/mixins
+      create  app/assets/javascripts/mixins/.gitkeep
+      create  app/assets/javascripts/adapters
+      create  app/assets/javascripts/adapters/.gitkeep
       create  app/assets/javascripts/app.js
 
 If you want to avoid `.gitkeep` files, use the `skip git` option like
@@ -96,8 +213,7 @@ and including the assets in your layout:
 
     <%= javascript_include_tag "templates/admin_panel" %>
 
-If you want to strip template root from template names, add `templates_root` option to your application configuration block.
-By default, `templates_root` is `'templates'`.
+If you want to avoid the `templates` prefix, set the `templates_root` option in your application configuration block:
 
     config.handlebars.templates_root = 'ember_templates'
 
@@ -122,20 +238,47 @@ Now a single line in the layout loads everything:
 
     <%= javascript_include_tag "templates/all" %>
 
-If you use Slim or Haml templates, you can use handlebars filter :
+### Note about ember components
+
+When necessary, ember-rails adheres to a conventional folder structure. To create an ember component you must define the handlebars file *inside* the *components* folder under the templates folder of your project to properly register your handlebars component file.
+
+*Example*
+
+Given the following folder structure:
 
-    handlebars:
-        <button {{action anActionName}}>OK</button>
+```
+├── adapters
+├── components
+├── controllers
+├── helpers
+├── mixins
+├── models
+├── practicality.js.coffee
+├── router.js.coffee
+├── routes
+├── store.js.coffee
+├── templates
+│   └── components
+│       └── my-component.handlebars
+└── views
+```
+
+and a `my-component.handlebars` file with the following contents:
 
-It will be translated as :
+    <h1>My Component</h1>
 
-    <script type="text/x-handlebars">
-        <button {{action anActionName}}>OK</button>
+It will produce the following handlebars output:
+
+    <script type="text/x-handlebars" id="components/my-component">
+      <h1>My Component</h1>
     </script>
 
+You can reference your component inside your other handlebars template files by the handlebars file name:
+
+     {{ my-component }}
+
 ## Specifying Different Versions of Ember/Handlebars/Ember-Data
 
-![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),
@@ -145,7 +288,7 @@ 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'
+    gem 'ember-source', '1.7.0'
 
 You can also specify versions of 'handlebars-source' and
 'ember-data-source', but note that an appropriate 'handlebars-source'
@@ -163,11 +306,41 @@ you've specified in your app's configuration, e.g.:
 
 ## Updating Ember
 
-If at any point you need to update Ember.js from master, you can do that with
+If at any point you need to update Ember.js from any of the release channels, you can do that with
+
+    rails generate ember:install --channel=<channel>
+
+This will fetch both Ember.js and Ember Data from [http://builds.emberjs.com/](http://builds.emberjs.com/) and copy to the right directory. You can choose between the following channels:
+* canary - This references the 'master' branch and is not recommended for production use.
+* beta - This references the 'beta' branch, and will ultimately become the next stable version. It is not recommended for production use.
+* release - This references the 'stable' branch, and is recommended for production use.
+
+When you don't specify a channel, the release channel is used.
 
-    rails generate ember:install --head
+It is also possible to download a specific tagged release. To do this, use the following syntax:
 
-This will fetch both Ember.js and Ember Data from [http://builds.emberjs.com/](http://builds.emberjs.com/) and copy to the right directory.
+
+    rails generate ember:install --tag=v1.2.0-beta.2 --ember
+
+or for ember-data
+
+    rails generate ember:install --tag=v1.0.0-beta.2 --ember-data
+
+## CSRF Token
+
+Rails [`protect_from_forgery`](http://api.rubyonrails.org/classes/ActionController/RequestForgeryProtection/ClassMethods.html#method-i-protect_from_forgery) requires CSRF token for every XHR except GET.
+The CSRF token is normally found in `app/views/layouts/application.html.*` inserted with the rails helper: [`csrf_meta_tags`](http://api.rubyonrails.org/classes/ActionView/Helpers/CsrfHelper.html#method-i-csrf_meta_tags).
+
+When you use [jquery-ujs](https://github.com/rails/jquery-ujs),
+the CSRF token will be sent to the rails application on every XHR automatically.
+If not so, the following JavaScript is required in your code.
+
+``` javascript
+$.ajaxPrefilter(function(options, originalOptions, xhr) {
+  var token = $('meta[name="csrf-token"]').attr('content');
+  xhr.setRequestHeader('X-CSRF-Token', token);
+});
+```
 
 ## Note on Patches/Pull Requests
 

data/lib/ember/rails/engine.rb

@@ -1,13 +1,18 @@
 require 'ember/handlebars/template'
+require 'sprockets/railtie'
 
 module Ember
   module Rails
     class Engine < ::Rails::Engine
-      config.handlebars = ActiveSupport::OrderedOptions.new
+      Ember::Handlebars::Template.configure do |handlebars_config|
+        config.handlebars = handlebars_config
 
-      config.handlebars.precompile = true
-      config.handlebars.templates_root = "templates"
-      config.handlebars.templates_path_separator = '/'
+        config.handlebars.precompile = true
+        config.handlebars.templates_root = 'templates'
+        config.handlebars.templates_path_separator = '/'
+        config.handlebars.output_type = :global
+        config.handlebars.ember_template = Ember::VERSION =~ /\A1.[0-9]\./ ? 'Handlebars' : 'HTMLBars'
+      end
 
       config.before_initialize do |app|
         Sprockets::Engines #force autoloading

data/lib/ember/rails/version.rb

@@ -1,5 +1,5 @@
 module Ember
   module Rails
-    VERSION = '0.12.0'
+    VERSION = '0.18.0'
   end
 end

data/lib/ember_rails.rb

@@ -1,9 +1,15 @@
 require 'rails'
-require 'ember/rails/version'
-require 'ember/rails/engine'
 require 'ember/source'
 require 'ember/data/source'
-require 'handlebars/source'
+require 'ember/rails/version'
+require 'ember/rails/engine'
+
+# Use handlebars if it possible. Because it is an optional feature.
+begin
+  require 'handlebars/source'
+rescue LoadError => e
+  raise e unless e.message == 'cannot load such file -- handlebars/source'
+end
 
 module Ember
   module Rails
@@ -20,34 +26,39 @@ module Ember
         require "generators/ember/resource_override"
       end
 
-      initializer "ember_rails.setup_vendor", :after => "ember_rails.setup", :group => :all do |app|
-        if variant = app.config.ember.variant
-          # Copy over the desired ember, ember-data, and handlebars bundled in
-          # ember-source, ember-data-source, and handlebars-source to a tmp folder. 
-          tmp_path = app.root.join("tmp/ember-rails")
-          ext = variant == :production ? ".prod.js" : ".js"
-          FileUtils.mkdir_p(tmp_path)
-          FileUtils.cp(::Ember::Source.bundled_path_for("ember#{ext}"), tmp_path.join("ember.js"))
-          FileUtils.cp(::Ember::Data::Source.bundled_path_for("ember-data#{ext}"), tmp_path.join("ember-data.js"))
-          app.assets.append_path(tmp_path)
-
-          # Make the handlebars.js and handlebars.runtime.js bundled
-          # in handlebars-source available.
-          app.assets.append_path(File.expand_path('../', ::Handlebars::Source.bundled_path))
-
-          # Allow a local variant override
-          ember_path = app.root.join("vendor/assets/ember/#{variant}")
-          app.assets.prepend_path(ember_path.to_s) if ember_path.exist?
+      initializer "ember_rails.setup_vendor_on_locale", :after => "ember_rails.setup", :group => :all do |app|
+        variant = app.config.ember.variant || (::Rails.env.production? ? :production : :development)
 
+        # Allow a local variant override
+        ember_path = app.root.join("vendor/assets/ember/#{variant}")
+        app.assets.prepend_path(ember_path.to_s) if ember_path.exist?
+      end
+
+      initializer "ember_rails.copy_vendor_to_local", :after => "ember_rails.setup", :group => :all do |app|
+        variant = app.config.ember.variant || (::Rails.env.production? ? :production : :development)
+
+        # Copy over the desired ember and ember-data bundled in
+        # ember-source and ember-data-source to a tmp folder.
+        tmp_path = app.root.join("tmp/ember-rails")
+        FileUtils.mkdir_p(tmp_path)
+
+        if variant == :production
+          ember_ext = ".prod.js"
         else
-          warn "No ember.js variant was specified in your config environment."
-          warn "You can set a specific variant in your application config in "
-          warn "order for sprockets to locate ember's assets:"
-          warn ""
-          warn "    config.ember.variant = :development"
-          warn ""
-          warn "Valid values are :development and :production"
+          ember_ext = ".debug.js"
+          ember_ext = ".js" unless File.exist?(::Ember::Source.bundled_path_for("ember#{ember_ext}")) # Ember.js 1.9.0 or earlier has no "ember.debug.js"
         end
+        FileUtils.cp(::Ember::Source.bundled_path_for("ember#{ember_ext}"), tmp_path.join("ember.js"))
+        ember_data_ext = variant == :production ? ".prod.js" : ".js"
+        FileUtils.cp(::Ember::Data::Source.bundled_path_for("ember-data#{ember_data_ext}"), tmp_path.join("ember-data.js"))
+
+        app.assets.append_path(tmp_path)
+      end
+
+      initializer "ember_rails.setup_vendor", :after => "ember_rails.copy_vendor_to_local", :group => :all do |app|
+        app.assets.append_path(::Ember::Source.bundled_path_for(nil))
+        app.assets.append_path(::Ember::Data::Source.bundled_path_for(nil))
+        app.assets.append_path(File.expand_path('../', ::Handlebars::Source.bundled_path)) if defined?(::Handlebars::Source)
       end
 
       initializer "ember_rails.es5_default", :group => :all do |app|