• Stars
    star
    238
  • Rank 169,306 (Top 4 %)
  • Language
    Ruby
  • License
    MIT License
  • Created about 11 years ago
  • Updated almost 7 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Ember Appkit for Rails

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.

Build Status Dependency Status Code Climate

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
  • Sublime/TextMate

  • Emacs:

    • Add (add-to-list 'auto-mode-alist '("\\.es6\\'" . javascript-mode)) to your .emacs.

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 files
  • app/mixins names Ember mixins
  • app/routes route files go here
  • app/templates your .hbs files go here
  • app/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. (replaces app/assets/javascripts/application.js)
  • config/adapter.js.erb configure the ember-data adapter. Pre-set for ActiveModelAdapter and will set the API version to Rails.application.config.ember.api_version
  • config/router.js your Ember Router. The actual routes will go in app/routes
  • config/initializers any files that compile to JavaScript in this directory will be automatically required.
  • config/initializers/csrf.js sets up the CSRF token for doing POST 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 of Rails.env. Settings added to these files will overwrite settings in config/environment.js
  • config/environments/development.js development environment settings
  • config/environments/production.js production environment settings
  • config/environments/test.js test environment settings
  • config/serializers/ where Rails and Ember serializers will go

The following is added to your test/ directory:

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, removes turbolinks from Gemfile and app/views/layouts/application.html.erb. The app/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 an Ember.ArrayController.
    • --object - Used to generate an Ember.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 in app/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 an Ember.ArrayController.
    • --object - Used to generate an Ember.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 where X = the values of ::Rails.application.config.ember.api_version

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:

EnvironmentEmberEmber DataHandlebars
developmentember.jsember-data.jshandlebars.js
testember.jsember-data.jshandlebars.js
productionember.prod.jsember-data.prod.jshandlebars.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

@dockyard

Licensed under the MIT license

More Repositories

1

client_side_validations

Client Side Validations made easy for Ruby on Rails
Ruby
2,686
star
2

ember-validations

Validations for Ember Objects
JavaScript
832
star
3

postgres_ext

Adds support for missing PostgreSQL data types to ActiveRecord
Ruby
643
star
4

ember-easy-form

Easily build semantic forms in Ember
JavaScript
565
star
5

party_foul

Use GitHub to track your application errors!
Ruby
517
star
6

ruby-destroyed_at

ActiveRecord Mixin for Safe Destroys
Ruby
349
star
7

capybara-email

Test your ActionMailer and Mailer messages with Capybara
Ruby
339
star
8

postgres_ext-serializers

Ruby
324
star
9

client_side_validations-simple_form

Simple Form plugin for ClientSideValidations
JavaScript
254
star
10

ember-suave

Make your Ember App Stylish
JavaScript
179
star
11

ember-one-way-controls

Native one way input
JavaScript
176
star
12

ember-data-route

Common teardown scenario for ember routes backed by a data model
JavaScript
120
star
13

ember-cli-i18n

Simple Internationalization support for ember-cli apps
JavaScript
112
star
14

dismissible_helpers

Ruby
96
star
15

es6_module_transpiler-rails

Transpile ES6 Modules in the Rails Asset Pipeline
JavaScript
87
star
16

capybara-extensions

Complements Capybara with additional finders and matchers.
Ruby
66
star
17

ruby-context_validations

Context Aware Validations for Rails
Ruby
65
star
18

pg_array_parser

Ruby
61
star
19

pages

Easy pages in Rails
Ruby
49
star
20

ember-skeleton

Show fast-loading temporary images in place of an eventual slow-loading image
JavaScript
41
star
21

ember-cli-proxy-fixtures

Ember CLI Proxy Fixtures
JavaScript
38
star
22

client_side_validations-mongoid

Mongoid plugin for ClientSideValidations
Ruby
28
star
23

ruby-easy_auth

Dead simple drop-in identity based Rails authentication
Ruby
28
star
24

ember-admin-bootstrap

Ember Admin with a Twitter Bootstrap Theme
CSS
25
star
25

client_side_validations-formtastic

Formtastic plugin for ClientSideValidations
Ruby
18
star
26

ember-wuphf

JavaScript
17
star
27

postgres_ext-postgis

Ruby
14
star
28

ember-cli-one-script

This addon combines your `vendor.js` and `<your-app-name>.js` into a single file called `app.js`
JavaScript
14
star
29

client_side_validations-turbolinks

Turbolinks Plugin for ClientSideValidations
Ruby
9
star
30

fixtory

Not quite fixtures, not quite factories
Ruby
9
star
31

ember-new-modules-shim

JavaScript
6
star
32

client_side_validations-backbone

Backbone plugin for ClientSideValidations
JavaScript
6
star
33

ember-cli-test-interactions

Ember acceptance test helpers.
JavaScript
3
star
34

minitest-moar

Moar Minitest Pluzsh!
Ruby
3
star
35

ruby-easy_auth-password

Password plugin for EasyAuth
Ruby
3
star
36

mail_congress

Ruby
2
star
37

ruby-easy_auth-oauth2

Ruby
1
star
38

ruby-easy_auth-twitter

Ruby
1
star
39

ruby-easy_auth-linked_in

Ruby
1
star
40

comet

Elixir
1
star