rails 4.2.6.rc1 → 5.2.8.1

data/guides/source/engines.md

@@ -1,1412 +0,0 @@
-Getting Started with Engines
-============================
-
-In this guide you will learn about engines and how they can be used to provide
-additional functionality to their host applications through a clean and very
-easy-to-use interface.
-
-After reading this guide, you will know:
-
-* What makes an engine.
-* How to generate an engine.
-* Building features for the engine.
-* Hooking the engine into an application.
-* Overriding engine functionality in the application.
-
---------------------------------------------------------------------------------
-
-What are engines?
------------------
-
-Engines can be considered miniature applications that provide functionality to
-their host applications. A Rails application is actually just a "supercharged"
-engine, with the `Rails::Application` class inheriting a lot of its behavior
-from `Rails::Engine`.
-
-Therefore, engines and applications can be thought of almost the same thing,
-just with subtle differences, as you'll see throughout this guide. Engines and
-applications also share a common structure.
-
-Engines are also closely related to plugins. The two share a common `lib`
-directory structure, and are both generated using the `rails plugin new`
-generator. The difference is that an engine is considered a "full plugin" by
-Rails (as indicated by the `--full` option that's passed to the generator
-command). We'll actually be using the `--mountable` option here, which includes
-all the features of `--full`, and then some. This guide will refer to these
-"full plugins" simply as "engines" throughout. An engine **can** be a plugin,
-and a plugin **can** be an engine.
-
-The engine that will be created in this guide will be called "blorgh". This
-engine will provide blogging functionality to its host applications, allowing
-for new articles and comments to be created. At the beginning of this guide, you
-will be working solely within the engine itself, but in later sections you'll
-see how to hook it into an application.
-
-Engines can also be isolated from their host applications. This means that an
-application is able to have a path provided by a routing helper such as
-`articles_path` and use an engine also that provides a path also called
-`articles_path`, and the two would not clash. Along with this, controllers, models
-and table names are also namespaced. You'll see how to do this later in this
-guide.
-
-It's important to keep in mind at all times that the application should
-**always** take precedence over its engines. An application is the object that
-has final say in what goes on in its environment. The engine should
-only be enhancing it, rather than changing it drastically.
-
-To see demonstrations of other engines, check out
-[Devise](https://github.com/plataformatec/devise), an engine that provides
-authentication for its parent applications, or
-[Forem](https://github.com/radar/forem), an engine that provides forum
-functionality. There's also [Spree](https://github.com/spree/spree) which
-provides an e-commerce platform, and
-[RefineryCMS](https://github.com/refinery/refinerycms), a CMS engine.
-
-Finally, engines would not have been possible without the work of James Adam,
-Piotr Sarnacki, the Rails Core Team, and a number of other people. If you ever
-meet them, don't forget to say thanks!
-
-Generating an engine
---------------------
-
-To generate an engine, you will need to run the plugin generator and pass it
-options as appropriate to the need. For the "blorgh" example, you will need to
-create a "mountable" engine, running this command in a terminal:
-
-```bash
-$ rails plugin new blorgh --mountable
-```
-
-The full list of options for the plugin generator may be seen by typing:
-
-```bash
-$ rails plugin --help
-```
-
-The `--mountable` option tells the generator that you want to create a
-"mountable" and namespace-isolated engine. This generator will provide the same
-skeleton structure as would the `--full` option. The `--full` option tells the
-generator that you want to create an engine, including a skeleton structure
-that provides the following:
-
-  * An `app` directory tree
-  * A `config/routes.rb` file:
-
-    ```ruby
-    Rails.application.routes.draw do
-    end
-    ```
-
-  * A file at `lib/blorgh/engine.rb`, which is identical in function to a
-    standard Rails application's `config/application.rb` file:
-
-    ```ruby
-    module Blorgh
-      class Engine < ::Rails::Engine
-      end
-    end
-    ```
-
-The `--mountable` option will add to the `--full` option:
-
-  * Asset manifest files (`application.js` and `application.css`)
-  * A namespaced `ApplicationController` stub
-  * A namespaced `ApplicationHelper` stub
-  * A layout view template for the engine
-  * Namespace isolation to `config/routes.rb`:
-
-    ```ruby
-    Blorgh::Engine.routes.draw do
-    end
-    ```
-
-  * Namespace isolation to `lib/blorgh/engine.rb`:
-
-    ```ruby
-    module Blorgh
-      class Engine < ::Rails::Engine
-        isolate_namespace Blorgh
-      end
-    end
-    ```
-
-Additionally, the `--mountable` option tells the generator to mount the engine
-inside the dummy testing application located at `test/dummy` by adding the
-following to the dummy application's routes file at
-`test/dummy/config/routes.rb`:
-
-```ruby
-mount Blorgh::Engine => "/blorgh"
-```
-
-### Inside an Engine
-
-#### Critical Files
-
-At the root of this brand new engine's directory lives a `blorgh.gemspec` file.
-When you include the engine into an application later on, you will do so with
-this line in the Rails application's `Gemfile`:
-
-```ruby
-gem 'blorgh', path: "vendor/engines/blorgh"
-```
-
-Don't forget to run `bundle install` as usual. By specifying it as a gem within
-the `Gemfile`, Bundler will load it as such, parsing this `blorgh.gemspec` file
-and requiring a file within the `lib` directory called `lib/blorgh.rb`. This
-file requires the `blorgh/engine.rb` file (located at `lib/blorgh/engine.rb`)
-and defines a base module called `Blorgh`.
-
-```ruby
-require "blorgh/engine"
-
-module Blorgh
-end
-```
-
-TIP: Some engines choose to use this file to put global configuration options
-for their engine. It's a relatively good idea, so if you want to offer
-configuration options, the file where your engine's `module` is defined is
-perfect for that. Place the methods inside the module and you'll be good to go.
-
-Within `lib/blorgh/engine.rb` is the base class for the engine:
-
-```ruby
-module Blorgh
-  class Engine < ::Rails::Engine
-    isolate_namespace Blorgh
-  end
-end
-```
-
-By inheriting from the `Rails::Engine` class, this gem notifies Rails that
-there's an engine at the specified path, and will correctly mount the engine
-inside the application, performing tasks such as adding the `app` directory of
-the engine to the load path for models, mailers, controllers and views.
-
-The `isolate_namespace` method here deserves special notice. This call is
-responsible for isolating the controllers, models, routes and other things into
-their own namespace, away from similar components inside the application.
-Without this, there is a possibility that the engine's components could "leak"
-into the application, causing unwanted disruption, or that important engine
-components could be overridden by similarly named things within the application.
-One of the examples of such conflicts is helpers. Without calling
-`isolate_namespace`, the engine's helpers would be included in an application's
-controllers.
-
-NOTE: It is **highly** recommended that the `isolate_namespace` line be left
-within the `Engine` class definition. Without it, classes generated in an engine
-**may** conflict with an application.
-
-What this isolation of the namespace means is that a model generated by a call
-to `bin/rails g model`, such as `bin/rails g model article`, won't be called `Article`, but
-instead be namespaced and called `Blorgh::Article`. In addition, the table for the
-model is namespaced, becoming `blorgh_articles`, rather than simply `articles`.
-Similar to the model namespacing, a controller called `ArticlesController` becomes
-`Blorgh::ArticlesController` and the views for that controller will not be at
-`app/views/articles`, but `app/views/blorgh/articles` instead. Mailers are namespaced
-as well.
-
-Finally, routes will also be isolated within the engine. This is one of the most
-important parts about namespacing, and is discussed later in the
-[Routes](#routes) section of this guide.
-
-#### `app` Directory
-
-Inside the `app` directory are the standard `assets`, `controllers`, `helpers`,
-`mailers`, `models` and `views` directories that you should be familiar with
-from an application. The `helpers`, `mailers` and `models` directories are
-empty, so they aren't described in this section. We'll look more into models in
-a future section, when we're writing the engine.
-
-Within the `app/assets` directory, there are the `images`, `javascripts` and
-`stylesheets` directories which, again, you should be familiar with due to their
-similarity to an application. One difference here, however, is that each
-directory contains a sub-directory with the engine name. Because this engine is
-going to be namespaced, its assets should be too.
-
-Within the `app/controllers` directory there is a `blorgh` directory that
-contains a file called `application_controller.rb`. This file will provide any
-common functionality for the controllers of the engine. The `blorgh` directory
-is where the other controllers for the engine will go. By placing them within
-this namespaced directory, you prevent them from possibly clashing with
-identically-named controllers within other engines or even within the
-application.
-
-NOTE: The `ApplicationController` class inside an engine is named just like a
-Rails application in order to make it easier for you to convert your
-applications into engines.
-
-Lastly, the `app/views` directory contains a `layouts` folder, which contains a
-file at `blorgh/application.html.erb`. This file allows you to specify a layout
-for the engine. If this engine is to be used as a stand-alone engine, then you
-would add any customization to its layout in this file, rather than the
-application's `app/views/layouts/application.html.erb` file.
-
-If you don't want to force a layout on to users of the engine, then you can
-delete this file and reference a different layout in the controllers of your
-engine.
-
-#### `bin` Directory
-
-This directory contains one file, `bin/rails`, which enables you to use the
-`rails` sub-commands and generators just like you would within an application.
-This means that you will be able to generate new controllers and models for this
-engine very easily by running commands like this:
-
-```bash
-$ bin/rails g model
-```
-
-Keep in mind, of course, that anything generated with these commands inside of
-an engine that has `isolate_namespace` in the `Engine` class will be namespaced.
-
-#### `test` Directory
-
-The `test` directory is where tests for the engine will go. To test the engine,
-there is a cut-down version of a Rails application embedded within it at
-`test/dummy`. This application will mount the engine in the
-`test/dummy/config/routes.rb` file:
-
-```ruby
-Rails.application.routes.draw do
-  mount Blorgh::Engine => "/blorgh"
-end
-```
-
-This line mounts the engine at the path `/blorgh`, which will make it accessible
-through the application only at that path.
-
-Inside the test directory there is the `test/integration` directory, where
-integration tests for the engine should be placed. Other directories can be
-created in the `test` directory as well. For example, you may wish to create a
-`test/models` directory for your model tests.
-
-Providing engine functionality
-------------------------------
-
-The engine that this guide covers provides submitting articles and commenting
-functionality and follows a similar thread to the [Getting Started
-Guide](getting_started.html), with some new twists.
-
-### Generating an Article Resource
-
-The first thing to generate for a blog engine is the `Article` model and related
-controller. To quickly generate this, you can use the Rails scaffold generator.
-
-```bash
-$ bin/rails generate scaffold article title:string text:text
-```
-
-This command will output this information:
-
-```
-invoke  active_record
-create    db/migrate/[timestamp]_create_blorgh_articles.rb
-create    app/models/blorgh/article.rb
-invoke    test_unit
-create      test/models/blorgh/article_test.rb
-create      test/fixtures/blorgh/articles.yml
-invoke  resource_route
- route    resources :articles
-invoke  scaffold_controller
-create    app/controllers/blorgh/articles_controller.rb
-invoke    erb
-create      app/views/blorgh/articles
-create      app/views/blorgh/articles/index.html.erb
-create      app/views/blorgh/articles/edit.html.erb
-create      app/views/blorgh/articles/show.html.erb
-create      app/views/blorgh/articles/new.html.erb
-create      app/views/blorgh/articles/_form.html.erb
-invoke    test_unit
-create      test/controllers/blorgh/articles_controller_test.rb
-invoke    helper
-create      app/helpers/blorgh/articles_helper.rb
-invoke  assets
-invoke    js
-create      app/assets/javascripts/blorgh/articles.js
-invoke    css
-create      app/assets/stylesheets/blorgh/articles.css
-invoke  css
-create    app/assets/stylesheets/scaffold.css
-```
-
-The first thing that the scaffold generator does is invoke the `active_record`
-generator, which generates a migration and a model for the resource. Note here,
-however, that the migration is called `create_blorgh_articles` rather than the
-usual `create_articles`. This is due to the `isolate_namespace` method called in
-the `Blorgh::Engine` class's definition. The model here is also namespaced,
-being placed at `app/models/blorgh/article.rb` rather than `app/models/article.rb` due
-to the `isolate_namespace` call within the `Engine` class.
-
-Next, the `test_unit` generator is invoked for this model, generating a model
-test at `test/models/blorgh/article_test.rb` (rather than
-`test/models/article_test.rb`) and a fixture at `test/fixtures/blorgh/articles.yml`
-(rather than `test/fixtures/articles.yml`).
-
-After that, a line for the resource is inserted into the `config/routes.rb` file
-for the engine. This line is simply `resources :articles`, turning the
-`config/routes.rb` file for the engine into this:
-
-```ruby
-Blorgh::Engine.routes.draw do
-  resources :articles
-end
-```
-
-Note here that the routes are drawn upon the `Blorgh::Engine` object rather than
-the `YourApp::Application` class. This is so that the engine routes are confined
-to the engine itself and can be mounted at a specific point as shown in the
-[test directory](#test-directory) section. It also causes the engine's routes to
-be isolated from those routes that are within the application. The
-[Routes](#routes) section of this guide describes it in detail.
-
-Next, the `scaffold_controller` generator is invoked, generating a controller
-called `Blorgh::ArticlesController` (at
-`app/controllers/blorgh/articles_controller.rb`) and its related views at
-`app/views/blorgh/articles`. This generator also generates a test for the
-controller (`test/controllers/blorgh/articles_controller_test.rb`) and a helper
-(`app/helpers/blorgh/articles_controller.rb`).
-
-Everything this generator has created is neatly namespaced. The controller's
-class is defined within the `Blorgh` module:
-
-```ruby
-module Blorgh
-  class ArticlesController < ApplicationController
-    ...
-  end
-end
-```
-
-NOTE: The `ApplicationController` class being inherited from here is the
-`Blorgh::ApplicationController`, not an application's `ApplicationController`.
-
-The helper inside `app/helpers/blorgh/articles_helper.rb` is also namespaced:
-
-```ruby
-module Blorgh
-  module ArticlesHelper
-    ...
-  end
-end
-```
-
-This helps prevent conflicts with any other engine or application that may have
-an article resource as well.
-
-Finally, the assets for this resource are generated in two files:
-`app/assets/javascripts/blorgh/articles.js` and
-`app/assets/stylesheets/blorgh/articles.css`. You'll see how to use these a little
-later.
-
-By default, the scaffold styling is not applied to the engine because the
-engine's layout file, `app/views/layouts/blorgh/application.html.erb`, doesn't
-load it. To make the scaffold styling apply, insert this line into the `<head>`
-tag of this layout:
-
-```erb
-<%= stylesheet_link_tag "scaffold" %>
-```
-
-You can see what the engine has so far by running `rake db:migrate` at the root
-of our engine to run the migration generated by the scaffold generator, and then
-running `rails server` in `test/dummy`. When you open
-`http://localhost:3000/blorgh/articles` you will see the default scaffold that has
-been generated. Click around! You've just generated your first engine's first
-functions.
-
-If you'd rather play around in the console, `rails console` will also work just
-like a Rails application. Remember: the `Article` model is namespaced, so to
-reference it you must call it as `Blorgh::Article`.
-
-```ruby
->> Blorgh::Article.find(1)
-=> #<Blorgh::Article id: 1 ...>
-```
-
-One final thing is that the `articles` resource for this engine should be the root
-of the engine. Whenever someone goes to the root path where the engine is
-mounted, they should be shown a list of articles. This can be made to happen if
-this line is inserted into the `config/routes.rb` file inside the engine:
-
-```ruby
-root to: "articles#index"
-```
-
-Now people will only need to go to the root of the engine to see all the articles,
-rather than visiting `/articles`. This means that instead of
-`http://localhost:3000/blorgh/articles`, you only need to go to
-`http://localhost:3000/blorgh` now.
-
-### Generating a Comments Resource
-
-Now that the engine can create new articles, it only makes sense to add
-commenting functionality as well. To do this, you'll need to generate a comment
-model, a comment controller and then modify the articles scaffold to display
-comments and allow people to create new ones.
-
-From the application root, run the model generator. Tell it to generate a
-`Comment` model, with the related table having two columns: a `article_id` integer
-and `text` text column.
-
-```bash
-$ bin/rails generate model Comment article_id:integer text:text
-```
-
-This will output the following:
-
-```
-invoke  active_record
-create    db/migrate/[timestamp]_create_blorgh_comments.rb
-create    app/models/blorgh/comment.rb
-invoke    test_unit
-create      test/models/blorgh/comment_test.rb
-create      test/fixtures/blorgh/comments.yml
-```
-
-This generator call will generate just the necessary model files it needs,
-namespacing the files under a `blorgh` directory and creating a model class
-called `Blorgh::Comment`. Now run the migration to create our blorgh_comments
-table:
-
-```bash
-$ rake db:migrate
-```
-
-To show the comments on an article, edit `app/views/blorgh/articles/show.html.erb` and
-add this line before the "Edit" link:
-
-```html+erb
-<h3>Comments</h3>
-<%= render @article.comments %>
-```
-
-This line will require there to be a `has_many` association for comments defined
-on the `Blorgh::Article` model, which there isn't right now. To define one, open
-`app/models/blorgh/article.rb` and add this line into the model:
-
-```ruby
-has_many :comments
-```
-
-Turning the model into this:
-
-```ruby
-module Blorgh
-  class Article < ActiveRecord::Base
-    has_many :comments
-  end
-end
-```
-
-NOTE: Because the `has_many` is defined inside a class that is inside the
-`Blorgh` module, Rails will know that you want to use the `Blorgh::Comment`
-model for these objects, so there's no need to specify that using the
-`:class_name` option here.
-
-Next, there needs to be a form so that comments can be created on an article. To
-add this, put this line underneath the call to `render @article.comments` in
-`app/views/blorgh/articles/show.html.erb`:
-
-```erb
-<%= render "blorgh/comments/form" %>
-```
-
-Next, the partial that this line will render needs to exist. Create a new
-directory at `app/views/blorgh/comments` and in it a new file called
-`_form.html.erb` which has this content to create the required partial:
-
-```html+erb
-<h3>New comment</h3>
-<%= form_for [@article, @article.comments.build] do |f| %>
-  <p>
-    <%= f.label :text %><br>
-    <%= f.text_area :text %>
-  </p>
-  <%= f.submit %>
-<% end %>
-```
-
-When this form is submitted, it is going to attempt to perform a `POST` request
-to a route of `/articles/:article_id/comments` within the engine. This route doesn't
-exist at the moment, but can be created by changing the `resources :articles` line
-inside `config/routes.rb` into these lines:
-
-```ruby
-resources :articles do
-  resources :comments
-end
-```
-
-This creates a nested route for the comments, which is what the form requires.
-
-The route now exists, but the controller that this route goes to does not. To
-create it, run this command from the application root:
-
-```bash
-$ bin/rails g controller comments
-```
-
-This will generate the following things:
-
-```
-create  app/controllers/blorgh/comments_controller.rb
-invoke  erb
- exist    app/views/blorgh/comments
-invoke  test_unit
-create    test/controllers/blorgh/comments_controller_test.rb
-invoke  helper
-create    app/helpers/blorgh/comments_helper.rb
-invoke  assets
-invoke    js
-create      app/assets/javascripts/blorgh/comments.js
-invoke    css
-create      app/assets/stylesheets/blorgh/comments.css
-```
-
-The form will be making a `POST` request to `/articles/:article_id/comments`, which
-will correspond with the `create` action in `Blorgh::CommentsController`. This
-action needs to be created, which can be done by putting the following lines
-inside the class definition in `app/controllers/blorgh/comments_controller.rb`:
-
-```ruby
-def create
-  @article = Article.find(params[:article_id])
-  @comment = @article.comments.create(comment_params)
-  flash[:notice] = "Comment has been created!"
-  redirect_to articles_path
-end
-
-private
-  def comment_params
-    params.require(:comment).permit(:text)
-  end
-```
-
-This is the final step required to get the new comment form working. Displaying
-the comments, however, is not quite right yet. If you were to create a comment
-right now, you would see this error:
-
-```
-Missing partial blorgh/comments/_comment with {:handlers=>[:erb, :builder],
-:formats=>[:html], :locale=>[:en, :en]}. Searched in:   *
-"/Users/ryan/Sites/side_projects/blorgh/test/dummy/app/views"   *
-"/Users/ryan/Sites/side_projects/blorgh/app/views"
-```
-
-The engine is unable to find the partial required for rendering the comments.
-Rails looks first in the application's (`test/dummy`) `app/views` directory and
-then in the engine's `app/views` directory. When it can't find it, it will throw
-this error. The engine knows to look for `blorgh/comments/_comment` because the
-model object it is receiving is from the `Blorgh::Comment` class.
-
-This partial will be responsible for rendering just the comment text, for now.
-Create a new file at `app/views/blorgh/comments/_comment.html.erb` and put this
-line inside it:
-
-```erb
-<%= comment_counter + 1 %>. <%= comment.text %>
-```
-
-The `comment_counter` local variable is given to us by the `<%= render
-@article.comments %>` call, which will define it automatically and increment the
-counter as it iterates through each comment. It's used in this example to
-display a small number next to each comment when it's created.
-
-That completes the comment function of the blogging engine. Now it's time to use
-it within an application.
-
-Hooking Into an Application
----------------------------
-
-Using an engine within an application is very easy. This section covers how to
-mount the engine into an application and the initial setup required, as well as
-linking the engine to a `User` class provided by the application to provide
-ownership for articles and comments within the engine.
-
-### Mounting the Engine
-
-First, the engine needs to be specified inside the application's `Gemfile`. If
-there isn't an application handy to test this out in, generate one using the
-`rails new` command outside of the engine directory like this:
-
-```bash
-$ rails new unicorn
-```
-
-Usually, specifying the engine inside the Gemfile would be done by specifying it
-as a normal, everyday gem.
-
-```ruby
-gem 'devise'
-```
-
-However, because you are developing the `blorgh` engine on your local machine,
-you will need to specify the `:path` option in your `Gemfile`:
-
-```ruby
-gem 'blorgh', path: "/path/to/blorgh"
-```
-
-Then run `bundle` to install the gem.
-
-As described earlier, by placing the gem in the `Gemfile` it will be loaded when
-Rails is loaded. It will first require `lib/blorgh.rb` from the engine, then
-`lib/blorgh/engine.rb`, which is the file that defines the major pieces of
-functionality for the engine.
-
-To make the engine's functionality accessible from within an application, it
-needs to be mounted in that application's `config/routes.rb` file:
-
-```ruby
-mount Blorgh::Engine, at: "/blog"
-```
-
-This line will mount the engine at `/blog` in the application. Making it
-accessible at `http://localhost:3000/blog` when the application runs with `rails
-server`.
-
-NOTE: Other engines, such as Devise, handle this a little differently by making
-you specify custom helpers (such as `devise_for`) in the routes. These helpers
-do exactly the same thing, mounting pieces of the engines's functionality at a
-pre-defined path which may be customizable.
-
-### Engine setup
-
-The engine contains migrations for the `blorgh_articles` and `blorgh_comments`
-table which need to be created in the application's database so that the
-engine's models can query them correctly. To copy these migrations into the
-application use this command:
-
-```bash
-$ rake blorgh:install:migrations
-```
-
-If you have multiple engines that need migrations copied over, use
-`railties:install:migrations` instead:
-
-```bash
-$ rake railties:install:migrations
-```
-
-This command, when run for the first time, will copy over all the migrations
-from the engine. When run the next time, it will only copy over migrations that
-haven't been copied over already. The first run for this command will output
-something such as this:
-
-```bash
-Copied migration [timestamp_1]_create_blorgh_articles.blorgh.rb from blorgh
-Copied migration [timestamp_2]_create_blorgh_comments.blorgh.rb from blorgh
-```
-
-The first timestamp (`[timestamp_1]`) will be the current time, and the second
-timestamp (`[timestamp_2]`) will be the current time plus a second. The reason
-for this is so that the migrations for the engine are run after any existing
-migrations in the application.
-
-To run these migrations within the context of the application, simply run `rake
-db:migrate`. When accessing the engine through `http://localhost:3000/blog`, the
-articles will be empty. This is because the table created inside the application is
-different from the one created within the engine. Go ahead, play around with the
-newly mounted engine. You'll find that it's the same as when it was only an
-engine.
-
-If you would like to run migrations only from one engine, you can do it by
-specifying `SCOPE`:
-
-```bash
-rake db:migrate SCOPE=blorgh
-```
-
-This may be useful if you want to revert engine's migrations before removing it.
-To revert all migrations from blorgh engine you can run code such as:
-
-```bash
-rake db:migrate SCOPE=blorgh VERSION=0
-```
-
-### Using a Class Provided by the Application
-
-#### Using a Model Provided by the Application
-
-When an engine is created, it may want to use specific classes from an
-application to provide links between the pieces of the engine and the pieces of
-the application. In the case of the `blorgh` engine, making articles and comments
-have authors would make a lot of sense.
-
-A typical application might have a `User` class that would be used to represent
-authors for an article or a comment. But there could be a case where the
-application calls this class something different, such as `Person`. For this
-reason, the engine should not hardcode associations specifically for a `User`
-class.
-
-To keep it simple in this case, the application will have a class called `User`
-that represents the users of the application (we'll get into making this
-configurable further on). It can be generated using this command inside the
-application:
-
-```bash
-rails g model user name:string
-```
-
-The `rake db:migrate` command needs to be run here to ensure that our
-application has the `users` table for future use.
-
-Also, to keep it simple, the articles form will have a new text field called
-`author_name`, where users can elect to put their name. The engine will then
-take this name and either create a new `User` object from it, or find one that
-already has that name. The engine will then associate the article with the found or
-created `User` object.
-
-First, the `author_name` text field needs to be added to the
-`app/views/blorgh/articles/_form.html.erb` partial inside the engine. This can be
-added above the `title` field with this code:
-
-```html+erb
-<div class="field">
-  <%= f.label :author_name %><br>
-  <%= f.text_field :author_name %>
-</div>
-```
-
-Next, we need to update our `Blorgh::ArticleController#article_params` method to
-permit the new form parameter:
-
-```ruby
-def article_params
-  params.require(:article).permit(:title, :text, :author_name)
-end
-```
-
-The `Blorgh::Article` model should then have some code to convert the `author_name`
-field into an actual `User` object and associate it as that article's `author`
-before the article is saved. It will also need to have an `attr_accessor` set up
-for this field, so that the setter and getter methods are defined for it.
-
-To do all this, you'll need to add the `attr_accessor` for `author_name`, the
-association for the author and the `before_save` call into
-`app/models/blorgh/article.rb`. The `author` association will be hard-coded to the
-`User` class for the time being.
-
-```ruby
-attr_accessor :author_name
-belongs_to :author, class_name: "User"
-
-before_save :set_author
-
-private
-  def set_author
-    self.author = User.find_or_create_by(name: author_name)
-  end
-```
-
-By representing the `author` association's object with the `User` class, a link
-is established between the engine and the application. There needs to be a way
-of associating the records in the `blorgh_articles` table with the records in the
-`users` table. Because the association is called `author`, there should be an
-`author_id` column added to the `blorgh_articles` table.
-
-To generate this new column, run this command within the engine:
-
-```bash
-$ bin/rails g migration add_author_id_to_blorgh_articles author_id:integer
-```
-
-NOTE: Due to the migration's name and the column specification after it, Rails
-will automatically know that you want to add a column to a specific table and
-write that into the migration for you. You don't need to tell it any more than
-this.
-
-This migration will need to be run on the application. To do that, it must first
-be copied using this command:
-
-```bash
-$ rake blorgh:install:migrations
-```
-
-Notice that only _one_ migration was copied over here. This is because the first
-two migrations were copied over the first time this command was run.
-
-```
-NOTE Migration [timestamp]_create_blorgh_articles.blorgh.rb from blorgh has been skipped. Migration with the same name already exists.
-NOTE Migration [timestamp]_create_blorgh_comments.blorgh.rb from blorgh has been skipped. Migration with the same name already exists.
-Copied migration [timestamp]_add_author_id_to_blorgh_articles.blorgh.rb from blorgh
-```
-
-Run the migration using:
-
-```bash
-$ rake db:migrate
-```
-
-Now with all the pieces in place, an action will take place that will associate
-an author - represented by a record in the `users` table - with an article,
-represented by the `blorgh_articles` table from the engine.
-
-Finally, the author's name should be displayed on the article's page. Add this code
-above the "Title" output inside `app/views/blorgh/articles/show.html.erb`:
-
-```html+erb
-<p>
-  <b>Author:</b>
-  <%= @article.author %>
-</p>
-```
-
-By outputting `@article.author` using the `<%=` tag, the `to_s` method will be
-called on the object. By default, this will look quite ugly:
-
-```
-#<User:0x00000100ccb3b0>
-```
-
-This is undesirable. It would be much better to have the user's name there. To
-do this, add a `to_s` method to the `User` class within the application:
-
-```ruby
-def to_s
-  name
-end
-```
-
-Now instead of the ugly Ruby object output, the author's name will be displayed.
-
-#### Using a Controller Provided by the Application
-
-Because Rails controllers generally share code for things like authentication
-and accessing session variables, they inherit from `ApplicationController` by
-default. Rails engines, however are scoped to run independently from the main
-application, so each engine gets a scoped `ApplicationController`. This
-namespace prevents code collisions, but often engine controllers need to access
-methods in the main application's `ApplicationController`. An easy way to
-provide this access is to change the engine's scoped `ApplicationController` to
-inherit from the main application's `ApplicationController`. For our Blorgh
-engine this would be done by changing
-`app/controllers/blorgh/application_controller.rb` to look like:
-
-```ruby
-module Blorgh
-  class ApplicationController < ::ApplicationController
-  end
-end
-```
-
-By default, the engine's controllers inherit from
-`Blorgh::ApplicationController`. So, after making this change they will have
-access to the main application's `ApplicationController`, as though they were
-part of the main application.
-
-This change does require that the engine is run from a Rails application that
-has an `ApplicationController`.
-
-### Configuring an Engine
-
-This section covers how to make the `User` class configurable, followed by
-general configuration tips for the engine.
-
-#### Setting Configuration Settings in the Application
-
-The next step is to make the class that represents a `User` in the application
-customizable for the engine. This is because that class may not always be
-`User`, as previously explained. To make this setting customizable, the engine
-will have a configuration setting called `author_class` that will be used to
-specify which class represents users inside the application.
-
-To define this configuration setting, you should use a `mattr_accessor` inside
-the `Blorgh` module for the engine. Add this line to `lib/blorgh.rb` inside the
-engine:
-
-```ruby
-mattr_accessor :author_class
-```
-
-This method works like its brothers, `attr_accessor` and `cattr_accessor`, but
-provides a setter and getter method on the module with the specified name. To
-use it, it must be referenced using `Blorgh.author_class`.
-
-The next step is to switch the `Blorgh::Article` model over to this new setting.
-Change the `belongs_to` association inside this model
-(`app/models/blorgh/article.rb`) to this:
-
-```ruby
-belongs_to :author, class_name: Blorgh.author_class
-```
-
-The `set_author` method in the `Blorgh::Article` model should also use this class:
-
-```ruby
-self.author = Blorgh.author_class.constantize.find_or_create_by(name: author_name)
-```
-
-To save having to call `constantize` on the `author_class` result all the time,
-you could instead just override the `author_class` getter method inside the
-`Blorgh` module in the `lib/blorgh.rb` file to always call `constantize` on the
-saved value before returning the result:
-
-```ruby
-def self.author_class
-  @@author_class.constantize
-end
-```
-
-This would then turn the above code for `set_author` into this:
-
-```ruby
-self.author = Blorgh.author_class.find_or_create_by(name: author_name)
-```
-
-Resulting in something a little shorter, and more implicit in its behavior. The
-`author_class` method should always return a `Class` object.
-
-Since we changed the `author_class` method to return a `Class` instead of a
-`String`, we must also modify our `belongs_to` definition in the `Blorgh::Article`
-model:
-
-```ruby
-belongs_to :author, class_name: Blorgh.author_class.to_s
-```
-
-To set this configuration setting within the application, an initializer should
-be used. By using an initializer, the configuration will be set up before the
-application starts and calls the engine's models, which may depend on this
-configuration setting existing.
-
-Create a new initializer at `config/initializers/blorgh.rb` inside the
-application where the `blorgh` engine is installed and put this content in it:
-
-```ruby
-Blorgh.author_class = "User"
-```
-
-WARNING: It's very important here to use the `String` version of the class,
-rather than the class itself. If you were to use the class, Rails would attempt
-to load that class and then reference the related table. This could lead to
-problems if the table wasn't already existing. Therefore, a `String` should be
-used and then converted to a class using `constantize` in the engine later on.
-
-Go ahead and try to create a new article. You will see that it works exactly in the
-same way as before, except this time the engine is using the configuration
-setting in `config/initializers/blorgh.rb` to learn what the class is.
-
-There are now no strict dependencies on what the class is, only what the API for
-the class must be. The engine simply requires this class to define a
-`find_or_create_by` method which returns an object of that class, to be
-associated with an article when it's created. This object, of course, should have
-some sort of identifier by which it can be referenced.
-
-#### General Engine Configuration
-
-Within an engine, there may come a time where you wish to use things such as
-initializers, internationalization or other configuration options. The great
-news is that these things are entirely possible, because a Rails engine shares
-much the same functionality as a Rails application. In fact, a Rails
-application's functionality is actually a superset of what is provided by
-engines!
-
-If you wish to use an initializer - code that should run before the engine is
-loaded - the place for it is the `config/initializers` folder. This directory's
-functionality is explained in the [Initializers
-section](configuring.html#initializers) of the Configuring guide, and works
-precisely the same way as the `config/initializers` directory inside an
-application. The same thing goes if you want to use a standard initializer.
-
-For locales, simply place the locale files in the `config/locales` directory,
-just like you would in an application.
-
-Testing an engine
------------------
-
-When an engine is generated, there is a smaller dummy application created inside
-it at `test/dummy`. This application is used as a mounting point for the engine,
-to make testing the engine extremely simple. You may extend this application by
-generating controllers, models or views from within the directory, and then use
-those to test your engine.
-
-The `test` directory should be treated like a typical Rails testing environment,
-allowing for unit, functional and integration tests.
-
-### Functional Tests
-
-A matter worth taking into consideration when writing functional tests is that
-the tests are going to be running on an application - the `test/dummy`
-application - rather than your engine. This is due to the setup of the testing
-environment; an engine needs an application as a host for testing its main
-functionality, especially controllers. This means that if you were to make a
-typical `GET` to a controller in a controller's functional test like this:
-
-```ruby
-module Blorgh
-  class FooControllerTest < ActionController::TestCase
-    def test_index
-      get :index
-      ...
-    end
-  end
-end
-```
-
-It may not function correctly. This is because the application doesn't know how
-to route these requests to the engine unless you explicitly tell it **how**. To
-do this, you must set the `@routes` instance variable to the engine's route set
-in your setup code:
-
-```ruby
-module Blorgh
-  class FooControllerTest < ActionController::TestCase
-    setup do
-      @routes = Engine.routes
-    end
-
-    def test_index
-      get :index
-      ...
-    end
-  end
-end
-```
-
-This tells the application that you still want to perform a `GET` request to the
-`index` action of this controller, but you want to use the engine's route to get
-there, rather than the application's one.
-
-This also ensures that the engine's URL helpers will work as expected in your
-tests.
-
-Improving engine functionality
-------------------------------
-
-This section explains how to add and/or override engine MVC functionality in the
-main Rails application.
-
-### Overriding Models and Controllers
-
-Engine model and controller classes can be extended by open classing them in the
-main Rails application (since model and controller classes are just Ruby classes
-that inherit Rails specific functionality). Open classing an Engine class
-redefines it for use in the main application. This is usually implemented by
-using the decorator pattern.
-
-For simple class modifications, use `Class#class_eval`. For complex class
-modifications, consider using `ActiveSupport::Concern`.
-
-#### A note on Decorators and Loading Code
-
-Because these decorators are not referenced by your Rails application itself,
-Rails' autoloading system will not kick in and load your decorators. This means
-that you need to require them yourself.
-
-Here is some sample code to do this:
-
-```ruby
-# lib/blorgh/engine.rb
-module Blorgh
-  class Engine < ::Rails::Engine
-    isolate_namespace Blorgh
-
-    config.to_prepare do
-      Dir.glob(Rails.root + "app/decorators/**/*_decorator*.rb").each do |c|
-        require_dependency(c)
-      end
-    end
-  end
-end
-```
-
-This doesn't apply to just Decorators, but anything that you add in an engine
-that isn't referenced by your main application.
-
-#### Implementing Decorator Pattern Using Class#class_eval
-
-**Adding** `Article#time_since_created`:
-
-```ruby
-# MyApp/app/decorators/models/blorgh/article_decorator.rb
-
-Blorgh::Article.class_eval do
-  def time_since_created
-    Time.current - created_at
-  end
-end
-```
-
-```ruby
-# Blorgh/app/models/article.rb
-
-class Article < ActiveRecord::Base
-  has_many :comments
-end
-```
-
-
-**Overriding** `Article#summary`:
-
-```ruby
-# MyApp/app/decorators/models/blorgh/article_decorator.rb
-
-Blorgh::Article.class_eval do
-  def summary
-    "#{title} - #{truncate(text)}"
-  end
-end
-```
-
-```ruby
-# Blorgh/app/models/article.rb
-
-class Article < ActiveRecord::Base
-  has_many :comments
-  def summary
-    "#{title}"
-  end
-end
-```
-
-#### Implementing Decorator Pattern Using ActiveSupport::Concern
-
-Using `Class#class_eval` is great for simple adjustments, but for more complex
-class modifications, you might want to consider using [`ActiveSupport::Concern`]
-(http://api.rubyonrails.org/classes/ActiveSupport/Concern.html).
-ActiveSupport::Concern manages load order of interlinked dependent modules and
-classes at run time allowing you to significantly modularize your code.
-
-**Adding** `Article#time_since_created` and **Overriding** `Article#summary`:
-
-```ruby
-# MyApp/app/models/blorgh/article.rb
-
-class Blorgh::Article < ActiveRecord::Base
-  include Blorgh::Concerns::Models::Article
-
-  def time_since_created
-    Time.current - created_at
-  end
-
-  def summary
-    "#{title} - #{truncate(text)}"
-  end
-end
-```
-
-```ruby
-# Blorgh/app/models/article.rb
-
-class Article < ActiveRecord::Base
-  include Blorgh::Concerns::Models::Article
-end
-```
-
-```ruby
-# Blorgh/lib/concerns/models/article
-
-module Blorgh::Concerns::Models::Article
-  extend ActiveSupport::Concern
-
-  # 'included do' causes the included code to be evaluated in the
-  # context where it is included (article.rb), rather than being
-  # executed in the module's context (blorgh/concerns/models/article).
-  included do
-    attr_accessor :author_name
-    belongs_to :author, class_name: "User"
-
-    before_save :set_author
-
-    private
-      def set_author
-        self.author = User.find_or_create_by(name: author_name)
-      end
-  end
-
-  def summary
-    "#{title}"
-  end
-
-  module ClassMethods
-    def some_class_method
-      'some class method string'
-    end
-  end
-end
-```
-
-### Overriding Views
-
-When Rails looks for a view to render, it will first look in the `app/views`
-directory of the application. If it cannot find the view there, it will check in
-the `app/views` directories of all engines that have this directory.
-
-When the application is asked to render the view for `Blorgh::ArticlesController`'s
-index action, it will first look for the path
-`app/views/blorgh/articles/index.html.erb` within the application. If it cannot
-find it, it will look inside the engine.
-
-You can override this view in the application by simply creating a new file at
-`app/views/blorgh/articles/index.html.erb`. Then you can completely change what
-this view would normally output.
-
-Try this now by creating a new file at `app/views/blorgh/articles/index.html.erb`
-and put this content in it:
-
-```html+erb
-<h1>Articles</h1>
-<%= link_to "New Article", new_article_path %>
-<% @articles.each do |article| %>
-  <h2><%= article.title %></h2>
-  <small>By <%= article.author %></small>
-  <%= simple_format(article.text) %>
-  <hr>
-<% end %>
-```
-
-### Routes
-
-Routes inside an engine are isolated from the application by default. This is
-done by the `isolate_namespace` call inside the `Engine` class. This essentially
-means that the application and its engines can have identically named routes and
-they will not clash.
-
-Routes inside an engine are drawn on the `Engine` class within
-`config/routes.rb`, like this:
-
-```ruby
-Blorgh::Engine.routes.draw do
-  resources :articles
-end
-```
-
-By having isolated routes such as this, if you wish to link to an area of an
-engine from within an application, you will need to use the engine's routing
-proxy method. Calls to normal routing methods such as `articles_path` may end up
-going to undesired locations if both the application and the engine have such a
-helper defined.
-
-For instance, the following example would go to the application's `articles_path`
-if that template was rendered from the application, or the engine's `articles_path`
-if it was rendered from the engine:
-
-```erb
-<%= link_to "Blog articles", articles_path %>
-```
-
-To make this route always use the engine's `articles_path` routing helper method,
-we must call the method on the routing proxy method that shares the same name as
-the engine.
-
-```erb
-<%= link_to "Blog articles", blorgh.articles_path %>
-```
-
-If you wish to reference the application inside the engine in a similar way, use
-the `main_app` helper:
-
-```erb
-<%= link_to "Home", main_app.root_path %>
-```
-
-If you were to use this inside an engine, it would **always** go to the
-application's root. If you were to leave off the `main_app` "routing proxy"
-method call, it could potentially go to the engine's or application's root,
-depending on where it was called from.
-
-If a template rendered from within an engine attempts to use one of the
-application's routing helper methods, it may result in an undefined method call.
-If you encounter such an issue, ensure that you're not attempting to call the
-application's routing methods without the `main_app` prefix from within the
-engine.
-
-### Assets
-
-Assets within an engine work in an identical way to a full application. Because
-the engine class inherits from `Rails::Engine`, the application will know to
-look up assets in the engine's 'app/assets' and 'lib/assets' directories.
-
-Like all of the other components of an engine, the assets should be namespaced.
-This means that if you have an asset called `style.css`, it should be placed at
-`app/assets/stylesheets/[engine name]/style.css`, rather than
-`app/assets/stylesheets/style.css`. If this asset isn't namespaced, there is a
-possibility that the host application could have an asset named identically, in
-which case the application's asset would take precedence and the engine's one
-would be ignored.
-
-Imagine that you did have an asset located at
-`app/assets/stylesheets/blorgh/style.css` To include this asset inside an
-application, just use `stylesheet_link_tag` and reference the asset as if it
-were inside the engine:
-
-```erb
-<%= stylesheet_link_tag "blorgh/style.css" %>
-```
-
-You can also specify these assets as dependencies of other assets using Asset
-Pipeline require statements in processed files:
-
-```
-/*
- *= require blorgh/style
-*/
-```
-
-INFO. Remember that in order to use languages like Sass or CoffeeScript, you
-should add the relevant library to your engine's `.gemspec`.
-
-### Separate Assets & Precompiling
-
-There are some situations where your engine's assets are not required by the
-host application. For example, say that you've created an admin functionality
-that only exists for your engine. In this case, the host application doesn't
-need to require `admin.css` or `admin.js`. Only the gem's admin layout needs
-these assets. It doesn't make sense for the host app to include
-`"blorgh/admin.css"` in its stylesheets. In this situation, you should
-explicitly define these assets for precompilation.  This tells sprockets to add
-your engine assets when `rake assets:precompile` is triggered.
-
-You can define assets for precompilation in `engine.rb`:
-
-```ruby
-initializer "blorgh.assets.precompile" do |app|
-  app.config.assets.precompile += %w(admin.css admin.js)
-end
-```
-
-For more information, read the [Asset Pipeline guide](asset_pipeline.html).
-
-### Other Gem Dependencies
-
-Gem dependencies inside an engine should be specified inside the `.gemspec` file
-at the root of the engine. The reason is that the engine may be installed as a
-gem. If dependencies were to be specified inside the `Gemfile`, these would not
-be recognized by a traditional gem install and so they would not be installed,
-causing the engine to malfunction.
-
-To specify a dependency that should be installed with the engine during a
-traditional `gem install`, specify it inside the `Gem::Specification` block
-inside the `.gemspec` file in the engine:
-
-```ruby
-s.add_dependency "moo"
-```
-
-To specify a dependency that should only be installed as a development
-dependency of the application, specify it like this:
-
-```ruby
-s.add_development_dependency "moo"
-```
-
-Both kinds of dependencies will be installed when `bundle install` is run inside
-of the application. The development dependencies for the gem will only be used
-when the tests for the engine are running.
-
-Note that if you want to immediately require dependencies when the engine is
-required, you should require them before the engine's initialization. For
-example:
-
-```ruby
-require 'other_engine/engine'
-require 'yet_another_engine/engine'
-
-module MyEngine
-  class Engine < ::Rails::Engine
-  end
-end
-```