We have sunset this gem. Patches will continue to be applied but no new features will be added. If you wish to fork and maintain please feel free.
EmberAppkitRails
Ember Appkit for the Asset Pipeline
This gem is still pre-1.0 and as such its public API will likely change over the course of heading towards 1.0
Upgrade Notes
If you are upgrading from a previous version of this gem because of the high probability of a breaking API change in some of the generated files you already have you should re-run rails g ember:bootstrap
and do a diff
on the files that are being generated vs what you have.
Prerequisites
Node.js is required. You can either download the
package from the website or run brew install node
(for Mac users
only).
Syntax Highlighting
It's recommended to turn on syntax highlighting for ES6 modules. There are numerous ways to do so. Here are a few suggestions.
-
Vim:
- Add
au BufNewFile,BufRead *.es6 set filetype=javascript
inside your~/.vimrc
- Add
-
Sublime/TextMate
- Check out the JavaScript.tmLanguage project.
-
Emacs:
- Add
(add-to-list 'auto-mode-alist '("\\.es6\\'" . javascript-mode))
to your.emacs
.
- Add
Installation
Include the gem in your Gemfile
gem 'ember-appkit-rails'
You should not need to specify any additional core Ember dependencies.
EmberAppkitRails
includes all you need to get going.
Run the bootstrap generator to prepare your application:
rails g ember:bootstrap
Then run your Rails server and visit http://localhost:3000
. If you see Welcome to Ember!
then you are good to go!
What do you get?
ember-appkit-rails
will add the app/
and config/
directories in
your Rails application to the asset pipeline. We want you to
think of your Ember application files with as much precedence as your
Rails application files.
ember-appkit-rails
completely removes app/assets/javascripts
from
the asset loadpath. Any files put into this directory will be ignored
during asset compilation. All business logic
you need should be added to app/
. If you need to add a 3rd party
library these should go into vendor/assets/javascripts/
.
Testing
Testing is built-in with Teaspoon and QUnit.
By default Teaspoon runs within the development environment.
If you want to run on test
you'll have to set it up explicitly e.g.
RAILS_ENV=test rake teaspoon
.
Resolving
In order for the resolver to work properly Ember application files need to go into
the correct directories. For example, models must go into
app/models
, controllers must go into app/controllers
, routes
must go into app/routes
, etc... The transpiler makes use of the
logical path for those files when creating the AMD namespace. The Ember
Appkit Resolver relies upon this namespacing for the lookups.
jquery-ujs
and turbolinks
will be removed from your application.
Any files in the app/
directory that compile to JavaScript will be
automatically required.
You must use es6
modules in your application files.
ember-appkit-rails
handles the transpiling for you via the
es6_module_transpiler-rails
gem as long as you add the .es6
extension to the end of the file. The generators will create these
files for you.
Directory Structure
The following is added to your app/
directory:
app/components
your component filesapp/mixins
names Ember mixinsapp/routes
route files go hereapp/templates
your.hbs
files go hereapp/templates/components
any component templates go here
The following is added to your config/
directory:
config/application.js
the main loader referenced in your Rails layout view. (replacesapp/assets/javascripts/application.js
)config/adapter.js.erb
configure the ember-data adapter. Pre-set forActiveModelAdapter
and will set the API version toRails.application.config.ember.api_version
config/router.js
your Ember Router. The actual routes will go inapp/routes
config/initializers
any files that compile to JavaScript in this directory will be automatically required.config/initializers/csrf.js
sets up theCSRF
token for doingPOST
requests back to the Rails backend via AJAX.config/initializers/teaspoon.rb
teaspoon's configuration file (https://github.com/modeset/teaspoon#configuration).config/environment.js
the general environment settings object. You should put settings in here that will be common across all environments.config/environments/
hold environment specific settings. The correct environment file will be loaded. Name matches value ofRails.env
. Settings added to these files will overwrite settings inconfig/environment.js
config/environments/development.js
development environment settingsconfig/environments/production.js
production environment settingsconfig/environments/test.js
test environment settingsconfig/serializers/
where Rails and Ember serializers will go
The following is added to your test/
directory:
test/test_helper.js
require the application for testing and declare helpers.test/teaspoon_env.rb
configuration directives used when running teaspoon via the rake task or command line (https://github.com/modeset/teaspoon#console-runner-specific-teaspoon-env).test/integration/
where integration test will go.
The lib/
directory is also mounted into the asset load path. You
should use lib/
to write any custom code that does not belong in
app/
or config/
but is not 3rd part software.
Any 3rd party software should be put into vendor/assets/javascripts
(this may change)
Usage
Generators
Ember Appkit Rails provides the following generators:
-
ember:bootstrap
Initializes Ember Appkit Rails into your project by creating the required files (
router.es6
,ember-app.es6
, and the directory structure). Also, removesturbolinks
fromGemfile
andapp/views/layouts/application.html.erb
. Theapp/assets/javascripts/
directory from your app is removed.The following options are supported:
--app-path
- This is the root path to be used for your Ember application. Default value:app/
.--config-path
- This is the root path for your configuration files used by your Ember Application. Default value:config/
--app-name
- This will be used to name the global variable referencing your application. Default value:App
.--skip-teaspoon
,-T
- This will skip the generation of Teaspoon.
-
ember:route NAME
Creates a route using the provided name in
app/routes/
. -
ember:controller NAME
Creates a controller using the provided name in
app/controllers/
.The following options are supported:
--array
- Used to generate anEmber.ArrayController
.--object
- Used to generate anEmber.ObjectController
.
-
ember:view NAME
Creates a view using the provided name in
app/views/
.The following options are supported:
--without-template
- Used to prevent creating a template for the generated view.
-
ember:component NAME
Creates a component in
app/components/
and a template inapp/templates/components/
. -
ember:template NAME
Creates a template using the provided name in
app/templates/
. -
ember:model NAME [ATTRIBUTES]
Creates a model using the provided name in
app/models/
.Accepts a list of a attributes to setup on the generated model.
Test is also added automatically under
test/models/model_name_test.es6
. -
ember:resource NAME
Creates a route, controller, and template for the provided name.
The following options are supported:
--array
- Used to generate anEmber.ArrayController
.--object
- Used to generate anEmber.ObjectController
.--skip-route
- When present a route will not be generated.
-
ember:scaffold NAME [ATTRIBUTES]
Creates the following:
- Model of type name with the attributes provided
edit
,index
,new
,show
routes and templates- Injected the named resource into
router.es6
along with the correct nested routes.
-
ember:helper NAME
Creates a helper using the provided name in
app/helpers/
.
Rails Generators
The regular Rails generators resource
and scaffold
can also generate
the matching ember templates if you provide the --ember
switch to the
command:
rails g resource post title:string --ember
The default behavior of the following Rails generators have been modified:
-
scaffold NAME [ATTRIBUTES]
- Will generate a controller with only
json
response types. - Controller and route are namespaced under
api/vX
whereX
= the values of::Rails.application.config.ember.api_version
- Will generate a controller with only
Configuration
Environments
The bootstrap will add environment specific files to
config/environemnts
that are only loaded in those environments. In
these files the correct versions of Ember, Ember Data, and Handlebars
are required. Any configuration settings you want passed into the
creation of your Ember app should be added to the config
object:
config.LOG_TRANSITIONS = true
The window.config
option is mixed into your application. Likewise, any
other environment specific settings should be made in these files.
API Versioning
Ember Data expect to work with a namespace of api/vX
where X
is the
current version of the backend API. To update this value you can
override the the value of config.ember.api_version
in
config/application.rb
.
The routing to the API endpoints in your application need to match
api/vX
. For example, you can do the following in config/routes.rb
namespace :api do
namespace :v1 do
resources :users
resources :documents
end
end
Then the controller files need to be under app/controllers/api/v1
and
the classes should be namespaced properly:
class Api::V1::UsersController < ApplicationController
...
end
Using the rails scaffold
generator will automatically inject resource
route into the correct versioned api namespace.
Asset Path
The default file asset path for eak-rails
files is app/
. The
generators will write files to that directory by default instead of
app/assets/javascripts
. To change this you'll have to modify the
configuration:
config.ember.paths.app = 'app/assets/javascripts'
Adding this to your config/application.rb
file will generate your
assets into app/assets/javascripts
instead of app/
AMD Module Namespacing
The default AMD namespace is app
. Modify this in your
config/application.rb
config.ember.namespaces.app = 'ember'
The AMD namespace for the router is config/
you can change this in
your config/application.rb
file as well:
config.ember.namespaces.config = 'ember_config'
Custom Ember Builds
By default Ember Appkit Rails will serve up the proper builds of Ember, Ember Data, and Handlebars depending upon the environment from their gems. However, you can add custom builds of each library to your project to override the default builds. The files you add must match a particular file name to override properly:
Environment | Ember | Ember Data | Handlebars |
---|---|---|---|
development | ember.js | ember-data.js | handlebars.js |
test | ember.js | ember-data.js | handlebars.js |
production | ember.prod.js | ember-data.prod.js | handlebars.runtime.js |
For example, if you wanted to build a new copy of Ember.js you should
add the files ember.js
and ember.prod.js
to
vendor/assets/javascripts
. The file of the same name will override the
copy in the gem.
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/ 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.
It is also possible to download a specific tagged release. To do this, use the following syntax:
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
Authors
A lot of the "real work" was done by Stefan Penner with the original Ember Appkit project.
We are very thankful for the many contributors
Versioning
This gem follows Semantic Versioning
Want to help?
Please do! We are always looking to improve this gem.
Legal
DockYard Inc. © 2014