Where Do Decorators Go In Rails

Getting Started with Engines

In this guide y'all will larn about engines and how they tin can be used to provide boosted functionality to their host applications through a clean and very easy-to-employ 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 awarding.

Chapters

1. What are engines?
2. Generating an engine
   • Within an Engine
3. Providing engine functionality
   • Generating a Post Resource
   • Generating a Comments Resource
4. Hooking Into an Awarding
   • Mounting the Engine
   • Engine setup
   • Using a Grade Provided past the Awarding
   • Configuring an Engine
5. Testing an engine
   • Functional Tests
6. Improving engine functionality
   • Overriding Models and Controllers
   • Overriding Views
   • Routes
   • Assets
   • Carve up Assets & Precompiling
   • Other Gem Dependencies

ane What are engines?

Engines can exist considered miniature applications that provide functionality to their host applications. A Track awarding is actually but a "supercharged" engine, with the Rails::Application class inheriting a lot of its beliefs from Runway::Engine.

Therefore, engines and applications tin be idea of almost the same thing, merely with subtle differences, every bit you'll see throughout this guide. Engines and applications also share a mutual 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 (every bit indicated past the --full pick that's passed to the generator control). This guide will refer to them simply every bit "engines" throughout. An engine tin be a plugin, and a plugin can exist an engine.

The engine that will be created in this guide volition be called "blorgh". The engine will provide blogging functionality to its host applications, allowing for new posts and comments to exist created. At the offset of this guide, you volition exist working solely inside the engine itself, simply 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 awarding is able to have a path provided by a routing helper such as posts_path and utilise an engine also that provides a path as well called posts_path, and the two would not clash. Forth with this, controllers, models and table names are as well namespaced. You'll run across how to practice this later on in this guide.

Information technology's of import to keep in mind at all times that the application should ever accept precedence over its engines. An application is the object that has final say in what goes on in the universe (with the universe beingness the application's environment) where the engine should only be enhancing it, rather than changing it drastically.

To see demonstrations of other engines, check out Devise, an engine that provides authentication for its parent applications, or Forem, an engine that provides forum functionality. At that place'southward likewise Spree which provides an e-commerce platform, and RefineryCMS, a CMS engine.

Finally, engines would not have been possible without the work of James Adam, Piotr Sarnacki, the Rails Core Squad, and a number of other people. If you always meet them, don't forget to say thanks!

2 Generating an engine

To generate an engine, you will demand to run the plugin generator and pass it options as appropriate to the need. For the "blorgh" example, you volition need to create a "mountable" engine, running this control in a terminal:

$ bin/rails plugin new blorgh --mountable          

The full list of options for the plugin generator may be seen by typing:

$ bin/rail plugin --aid          

The --full pick tells the generator that y'all want to create an engine, including a skeleton structure that provides the following:

• An app directory tree

• A config/routes.rb file:

  Rails.awarding.routes.draw practice end              

• A file at lib/blorgh/engine.rb, which is identical in function to a

• standard Rails application's config/application.rb file:

  module Blorgh   class Engine < ::Rails::Engine   end end              

The --mountable option tells the generator that you want to create a "mountable" and namespace-isolated engine. This generator will provide the aforementioned skeleton structure as would the --full option, and will add together:

• Nugget manifest files (application.js and awarding.css)
• A namespaced ApplicationController stub
• A namespaced ApplicationHelper stub
• A layout view template for the engine

• Namespace isolation to config/routes.rb:

  Blorgh::Engine.routes.draw do end              

• Namespace isolation to lib/blorgh/engine.rb:

  module Blorgh   class Engine < ::Rails::Engine     isolate_namespace Blorgh   stop end              

Additionally, the --mountable choice tells the generator to mountain the engine within 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:

mount Blorgh::Engine, at: "blorgh"          

ii.1 Within an Engine

two.1.i Critical Files

At the root of this make new engine's directory lives a blorgh.gemspec file. When you include the engine into an application afterwards on, you will exercise so with this line in the Rails awarding'south Gemfile:

precious stone 'blorgh', path: "vendor/engines/blorgh"          

Don't forget to run package install as usual. By specifying it as a gem within the Gemfile, Bundler will load information technology every bit such, parsing this blorgh.gemspec file and requiring a file within the lib directory chosen lib/blorgh.rb. This file requires the blorgh/engine.rb file (located at lib/blorgh/engine.rb) and defines a base module called Blorgh.

require "blorgh/engine"  module Blorgh cease          

Some engines cull to use this file to put global configuration options for their engine. It'due south a relatively good thought, and then if you desire to offer configuration options, the file where your engine's module is divers is perfect for that. Place the methods within the module and you'll exist good to get.

Inside lib/blorgh/engine.rb is the base class for the engine:

module Blorgh   class Engine < Runway::Engine     isolate_namespace Blorgh   end end          

Past inheriting from the Rail::Engine class, this precious stone notifies Rails that there's an engine at the specified path, and will correctly mount the engine within 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 find. This call is responsible for isolating the controllers, models, routes and other things into their ain namespace, abroad from like components within the awarding. 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. 1 of the examples of such conflicts is helpers. Without calling isolate_namespace, the engine's helpers would be included in an awarding's controllers.

Information technology is highly recommended that the isolate_namespace line be left inside 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/rail g model, such as bin/rails g model post, won't be chosen Post, but instead exist namespaced and called Blorgh::Mail service. In add-on, the table for the model is namespaced, becoming blorgh_posts, rather than simply posts. Similar to the model namespacing, a controller called PostsController becomes Blorgh::PostsController and the views for that controller will not be at app/views/posts, but app/views/blorgh/posts instead. Mailers are namespaced also.

Finally, routes will also exist isolated inside the engine. This is one of the most important parts about namespacing, and is discussed later in the Routes section of this guide.

2.one.ii app Directory

Within the app directory are the standard assets, controllers, helpers, mailers, models and views directories that you should exist 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 hereafter section, when nosotros're writing the engine.

Within the app/assets directory, there are the images, javascripts and stylesheets directories which, once more, you should be familiar with due to their similarity to an awarding. One departure here, however, is that each directory contains a sub-directory with the engine proper noun. 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 volition provide whatever common functionality for the controllers of the engine. The blorgh directory is where the other controllers for the engine will get. By placing them within this namespaced directory, you forbid them from possibly ambivalent with identically-named controllers within other engines or even within the application.

The ApplicationController form within an engine is named just like a Rails application in lodge to arrive easier for you to catechumen 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 yous would add together any customization to its layout in this file, rather than the application's app/views/layouts/application.html.erb file.

If you don't desire to force a layout on to users of the engine, and so yous can delete this file and reference a different layout in the controllers of your engine.

2.i.3 bin Directory

This directory contains i file, bin/track, which enables you lot to use the rails sub-commands and generators just similar yous would within an application. This means that you lot will be able to generate new controllers and models for this engine very easily by running commands similar this:

Go along in heed, of course, that anything generated with these commands within of an engine that has isolate_namespace in the Engine form will be namespaced.

2.one.4 examination Directory

The examination directory is where tests for the engine will become. To test the engine, there is a cut-down version of a Track application embedded within information technology at test/dummy. This application will mount the engine in the test/dummy/config/routes.rb file:

Rails.application.routes.draw practise   mount Blorgh::Engine => "/blorgh" cease          

This line mounts the engine at the path /blorgh, which will get in attainable through the application only at that path.

Inside the test directory there is the examination/integration directory, where integration tests for the engine should exist placed. Other directories tin can be created in the test directory every bit well. For example, you may wish to create a examination/models directory for your model tests.

3 Providing engine functionality

The engine that this guide covers provides posting and commenting functionality and follows a similar thread to the Getting Started Guide, with some new twists.

iii.1 Generating a Mail service Resource

The first thing to generate for a weblog engine is the Post model and related controller. To chop-chop generate this, y'all can use the Rails scaffold generator.

$ bin/track generate scaffold mail service title:string text:text          

This control will output this data:

invoke  active_record create    db/migrate/[timestamp]_create_blorgh_posts.rb create    app/models/blorgh/post.rb invoke    test_unit create      test/models/blorgh/post_test.rb create      test/fixtures/blorgh/posts.yml invoke  resource_route  road    resources :posts invoke  scaffold_controller create    app/controllers/blorgh/posts_controller.rb invoke    erb create      app/views/blorgh/posts create      app/views/blorgh/posts/alphabetize.html.erb create      app/views/blorgh/posts/edit.html.erb create      app/views/blorgh/posts/show.html.erb create      app/views/blorgh/posts/new.html.erb create      app/views/blorgh/posts/_form.html.erb invoke    test_unit create      test/controllers/blorgh/posts_controller_test.rb invoke    helper create      app/helpers/blorgh/posts_helper.rb invoke      test_unit create        exam/helpers/blorgh/posts_helper_test.rb invoke  avails invoke    js create      app/assets/javascripts/blorgh/posts.js invoke    css create      app/assets/stylesheets/blorgh/posts.css invoke  css create    app/assets/stylesheets/scaffold.css          

The offset thing that the scaffold generator does is invoke the active_record generator, which generates a migration and a model for the resource. Notation here, even so, that the migration is called create_blorgh_posts rather than the usual create_posts. This is due to the isolate_namespace method called in the Blorgh::Engine class'south definition. The model here is also namespaced, being placed at app/models/blorgh/post.rb rather than app/models/post.rb due to the isolate_namespace phone call within the Engine class.

Next, the test_unit generator is invoked for this model, generating a model test at exam/models/blorgh/post_test.rb (rather than test/models/post_test.rb) and a fixture at test/fixtures/blorgh/posts.yml (rather than test/fixtures/posts.yml).

Afterwards that, a line for the resource is inserted into the config/routes.rb file for the engine. This line is only resource :posts, turning the config/routes.rb file for the engine into this:

Blorgh::Engine.routes.draw do   resource :posts cease          

Notation hither that the routes are drawn upon the Blorgh::Engine object rather than the YourApp::Awarding class. This is so that the engine routes are bars to the engine itself and can be mounted at a specific signal as shown in the test directory section. It as well causes the engine'southward routes to exist isolated from those routes that are inside the awarding. The Routes section of this guide describes it in detail.

Next, the scaffold_controller generator is invoked, generating a controller chosen Blorgh::PostsController (at app/controllers/blorgh/posts_controller.rb) and its related views at app/views/blorgh/posts. This generator as well generates a test for the controller (test/controllers/blorgh/posts_controller_test.rb) and a helper (app/helpers/blorgh/posts_controller.rb).

Everything this generator has created is neatly namespaced. The controller'southward course is defined inside the Blorgh module:

module Blorgh   course PostsController < ApplicationController     ...   stop cease          

The ApplicationController class beingness inherited from here is the Blorgh::ApplicationController, not an application'south ApplicationController.

The helper within app/helpers/blorgh/posts_helper.rb is also namespaced:

module Blorgh   module PostsHelper     ...   end cease          

This helps foreclose conflicts with any other engine or application that may have a post resources likewise.

Finally, the avails for this resource are generated in ii files: app/assets/javascripts/blorgh/posts.js and app/assets/stylesheets/blorgh/posts.css. Y'all'll see how to use these a little later.

Past default, the scaffold styling is non applied to the engine because the engine'south 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:

<%= stylesheet_link_tag "scaffold" %>          

Y'all can see what the engine has and so far by running rake db:migrate at the root of our engine to run the migration generated by the scaffold generator, and so running runway server in examination/dummy. When y'all open http://localhost:3000/blorgh/posts you lot volition see the default scaffold that has been generated. Click around! You've merely generated your first engine's first functions.

If you lot'd rather play around in the panel, track console will also piece of work just like a Rails application. Remember: the Post model is namespaced, so to reference information technology you must call it as Blorgh::Post.

>> Blorgh::Post.find(one) => #<Blorgh::Post id: one ...>          

Ane final affair is that the posts 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 posts. This can exist made to happen if this line is inserted into the config/routes.rb file inside the engine:

Now people will only demand to go to the root of the engine to run into all the posts, rather than visiting /posts. This means that instead of http://localhost:3000/blorgh/posts, you only need to become to http://localhost:3000/blorgh now.

Now that the engine can create new blog posts, it simply makes sense to add commenting functionality equally well. To do this, you'll need to generate a comment model, a comment controller and so change the posts scaffold to display comments and permit people to create new ones.

From the awarding root, run the model generator. Tell it to generate a Comment model, with the related table having two columns: a post_id integer and text text column.

$ bin/rails generate model Comment post_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      examination/models/blorgh/comment_test.rb create      examination/fixtures/blorgh/comments.yml          

This generator call volition generate only the necessary model files it needs, namespacing the files under a blorgh directory and creating a model form chosen Blorgh::Annotate. Now run the migration to create our blorgh_comments table:

To show the comments on a post, edit app/views/blorgh/posts/show.html.erb and add this line earlier the "Edit" link:

<h3>Comments</h3> <%= render @postal service.comments %>          

This line volition require in that location to be a has_many association for comments divers on the Blorgh::Postal service model, which at that place isn't right now. To ascertain ane, open app/models/blorgh/post.rb and add this line into the model:

Turning the model into this:

module Blorgh   form Post < ActiveRecord::Base     has_many :comments   end cease          

Because the has_many is divers inside a class that is inside the Blorgh module, Rail will know that you want to utilize the Blorgh::Annotate model for these objects, so there'southward no demand to specify that using the :class_name pick here.

Next, there needs to be a form so that comments tin can be created on a mail. To add this, put this line underneath the call to return @post.comments in app/views/blorgh/posts/show.html.erb:

<%= render "blorgh/comments/form" %>          

Next, the fractional that this line will render needs to be. Create a new directory at app/views/blorgh/comments and in it a new file chosen _form.html.erb which has this content to create the required partial:

<h3>New comment</h3> <%= form_for [@mail, @post.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 /posts/:post_id/comments within the engine. This route doesn't exist at the moment, but can be created past changing the resources :posts line inside config/routes.rb into these lines:

resources :posts do   resource :comments terminate          

This creates a nested route for the comments, which is what the class requires.

The route now exists, but the controller that this road goes to does not. To create it, run this command from the awarding root:

$ bin/track 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    test_unit create      test/helpers/blorgh/comments_helper_test.rb invoke  assets invoke    js create      app/assets/javascripts/blorgh/comments.js invoke    css create      app/assets/stylesheets/blorgh/comments.css          

The form will exist making a POST request to /posts/:post_id/comments, which volition represent with the create action in Blorgh::CommentsController. This action needs to be created, which tin be washed by putting the following lines inside the class definition in app/controllers/blorgh/comments_controller.rb:

def create   @post = Postal service.observe(params[:post_id])   @comment = @post.comments.create(comment_params)   flash[:notice] = "Comment has been created!"   redirect_to posts_path end  private   def comment_params     params.require(:comment).permit(:text)   stop          

This is the final step required to get the new comment form working. Displaying the comments, notwithstanding, is not quite right yet. If you were to create a comment right at present, 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/exam/dummy/app/views"   * "/Users/ryan/Sites/side_projects/blorgh/app/views"          

The engine is unable to find the partial required for rendering the comments. Track looks start in the application's (test/dummy) app/views directory and then in the engine'southward app/views directory. When it can't observe information technology, information technology will throw this error. The engine knows to look for blorgh/comments/comment considering the model object information technology is receiving is from the Blorgh::Annotate class.

This fractional will exist 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 within it:

<%= comment_counter + i %>. <%= annotate.text %>          

The comment_counter local variable is given to us past the <%= return @post.comments %> call, which volition define it automatically and increment the counter as it iterates through each annotate. It'due south used in this case to display a modest number side by side to each annotate when it's created.

That completes the annotate function of the blogging engine. Now information technology'south time to apply it inside an awarding.

4 Hooking Into an Application

Using an engine within an awarding is very easy. This department covers how to mount the engine into an awarding and the initial setup required, as well every bit linking the engine to a User class provided by the application to provide ownership for posts and comments within the engine.

4.1 Mounting the Engine

First, the engine needs to be specified within the awarding'southward Gemfile. If there isn't an application handy to exam this out in, generate 1 using the runway new command outside of the engine directory like this:

Usually, specifying the engine inside the Gemfile would be washed by specifying information technology every bit a normal, everyday gem.

However, because you are developing the blorgh engine on your local machine, y'all will need to specify the :path choice in your Gemfile:

gem 'blorgh', path: "/path/to/blorgh"          

Then run packet to install the precious stone.

As described before, by placing the gem in the Gemfile it will exist loaded when Rails is loaded. It will first require lib/blorgh.rb from the engine, so lib/blorgh/engine.rb, which is the file that defines the major pieces of functionality for the engine.

To make the engine'south functionality accessible from inside an application, it needs to exist mounted in that application'southward config/routes.rb file:

mount Blorgh::Engine, at: "/blog"          

This line will mountain the engine at /blog in the application. Making it accessible at http://localhost:3000/blog when the awarding runs with runway server.

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 exercise exactly the same thing, mounting pieces of the engines's functionality at a pre-defined path which may be customizable.

4.2 Engine setup

The engine contains migrations for the blorgh_posts and blorgh_comments table which need to be created in the application's database so that the engine'due south models can query them correctly. To copy these migrations into the awarding apply this command:

$ bin/rake blorgh:install:migrations          

If y'all have multiple engines that demand migrations copied over, utilize railties:install:migrations instead:

$ bin/rake railties:install:migrations          

This control, when run for the first time, will copy over all the migrations from the engine. When run the next fourth dimension, information technology will only copy over migrations that oasis't been copied over already. The first run for this command will output something such as this:

Copied migration [timestamp_1]_create_blorgh_posts.rb from blorgh Copied migration [timestamp_2]_create_blorgh_comments.rb from blorgh          

The first timestamp ([timestamp_1]) volition be the electric current time, and the second timestamp ([timestamp_2]) volition be the electric current time plus a 2nd. The reason for this is so that the migrations for the engine are run after whatsoever existing migrations in the awarding.

To run these migrations inside the context of the application, only run rake db:migrate. When accessing the engine through http://localhost:3000/web log, the posts will exist empty. This is because the table created within the application is different from the ane 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 but an engine.

If you lot would similar to run migrations only from one engine, you lot can exercise it by specifying Scope:

rake db:migrate SCOPE=blorgh          

This may be useful if you lot desire to revert engine's migrations earlier removing information technology. To revert all migrations from blorgh engine you lot can run lawmaking such as:

rake db:migrate Telescopic=blorgh VERSION=0          

four.three Using a Form Provided by the Awarding

4.3.ane Using a Model Provided by the Awarding

When an engine is created, it may desire to use specific classes from an awarding to provide links between the pieces of the engine and the pieces of the application. In the example of the blorgh engine, making posts and comments take authors would make a lot of sense.

A typical application might have a User course that would be used to represent authors for a post or a comment. Just in that location could be a instance where the application calls this class something unlike, such as Person. For this reason, the engine should not hardcode associations specifically for a User form.

To proceed it simple in this case, the application volition have a course called User that represents the users of the application. It can be generated using this command within the application:

rails g model user proper noun:cord          

The rake db:migrate command needs to be run here to ensure that our application has the users table for time to come use.

Also, to keep information technology uncomplicated, the posts course will have a new text field called author_name, where users tin can elect to put their name. The engine will and so take this name and either create a new User object from it, or detect i that already has that proper name. The engine will then associate the postal service with the constitute or created User object.

First, the author_name text field needs to exist added to the app/views/blorgh/posts/_form.html.erb partial within the engine. This tin be added above the title field with this code:

<div class="field">   <%= f.label :author_name %><br>   <%= f.text_field :author_name %> </div>          

Adjacent, we need to update our Blorgh::PostController#post_params method to allow the new course parameter:

def post_params   params.require(:postal service).permit(:title, :text, :author_name) end          

The Blorgh::Mail model should then take some lawmaking to convert the author_name field into an actual User object and associate it as that mail's author before the postal service is saved. It will besides need to have an attr_accessor ready up for this field, and so that the setter and getter methods are defined for it.

To do all this, y'all'll demand to add the attr_accessor for author_name, the clan for the writer and the before_save call into app/models/blorgh/post.rb. The writer association will exist difficult-coded to the User course for the time being.

attr_accessor :author_name belongs_to :author, class_name: "User"  before_save :set_author  individual   def set_author     cocky.author = User.find_or_create_by(name: author_name)   cease          

By representing the writer clan'southward object with the User class, a link is established between the engine and the application. There needs to exist a way of associating the records in the blorgh_posts tabular array with the records in the users table. Because the association is called author, there should exist an author_id column added to the blorgh_posts table.

To generate this new cavalcade, run this command within the engine:

$ bin/rails k migration add_author_id_to_blorgh_posts author_id:integer          

Due to the migration's name and the column specification after it, Rails will automatically know that you lot desire to add a cavalcade to a specific table and write that into the migration for you. You don't need to tell it whatever more than than this.

This migration will need to be run on the application. To do that, information technology must first be copied using this command:

$ bin/rake blorgh:install:migrations          

Notice that just 1 migration was copied over here. This is because the get-go two migrations were copied over the first time this command was run.

Annotation Migration [timestamp]_create_blorgh_posts.rb from blorgh has been skipped. Migration with the same name already exists. NOTE Migration [timestamp]_create_blorgh_comments.rb from blorgh has been skipped. Migration with the aforementioned proper noun already exists. Copied migration [timestamp]_add_author_id_to_blorgh_posts.rb from blorgh          

Run the migration using:

Now with all the pieces in place, an action will accept place that volition associate an author - represented by a tape in the users table - with a postal service, represented by the blorgh_posts table from the engine.

Finally, the writer'south proper name should exist displayed on the mail'due south folio. Add this code above the "Title" output inside app/views/blorgh/posts/show.html.erb:

<p>   <b>Author:</b>   <%= @post.author %> </p>          

By outputting @post.writer using the <%= tag, the to_s method will exist called on the object. By default, this will look quite ugly:

This is undesirable. Information technology would be much better to have the user's proper noun there. To do this, add a to_s method to the User course within the application:

Now instead of the ugly Ruby object output, the author's name will exist displayed.

4.three.2 Using a Controller Provided by the Application

Considering Rails controllers by and large share code for things like authentication and accessing session variables, they inherit from ApplicationController by default. Rails engines, even so are scoped to run independently from the master application, then each engine gets a scoped ApplicationController. This namespace prevents code collisions, but oft engine controllers need to access methods in the main awarding'due south ApplicationController. An piece of cake style to provide this access is to change the engine's scoped ApplicationController to inherit from the main application'south ApplicationController. For our Blorgh engine this would exist done past irresolute app/controllers/blorgh/application_controller.rb to wait like:

class Blorgh::ApplicationController < ApplicationController stop          

By default, the engine's controllers inherit from Blorgh::ApplicationController. So, after making this change they volition accept 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 awarding that has an ApplicationController.

4.4 Configuring an Engine

This department covers how to brand the User course configurable, followed by general configuration tips for the engine.

4.4.1 Setting Configuration Settings in the Awarding

The next step is to brand the class that represents a User in the application customizable for the engine. This is because that class may not ever be User, equally previously explained. To make this setting customizable, the engine volition take a configuration setting called author_class that will exist used to specify which class represents users inside the application.

To ascertain this configuration setting, y'all should apply a mattr_accessor inside the Blorgh module for the engine. Add this line to lib/blorgh.rb within the engine:

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::Mail model over to this new setting. Change the belongs_to clan inside this model (app/models/blorgh/mail service.rb) to this:

belongs_to :writer, class_name: Blorgh.author_class          

The set_author method in the Blorgh::Post model should too use this form:

cocky.author = Blorgh.author_class.constantize.find_or_create_by(proper name: author_name)          

To save having to call constantize on the author_class consequence all the time, you could instead just override the author_class getter method within the Blorgh module in the lib/blorgh.rb file to always call constantize on the saved value before returning the result:

def self.author_class   @@author_class.constantize end          

This would then turn the to a higher place code for set_author into this:

self.writer = Blorgh.author_class.find_or_create_by(proper noun: author_name)          

Resulting in something a little shorter, and more than implicit in its behavior. The author_class method should always return a Grade 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::Mail model:

belongs_to :author, class_name: Blorgh.author_class.to_s          

To ready this configuration setting within the awarding, an initializer should exist used. Past using an initializer, the configuration will exist set upwardly earlier the application starts and calls the engine'southward 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:

Blorgh.author_class = "User"          

It's very important here to utilize the String version of the form, rather than the course itself. If yous were to utilise the class, Runway would effort 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 exist used and then converted to a form using constantize in the engine afterwards on.

Go alee and attempt to create a new postal service. You will see that it works exactly in the same way as earlier, 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 course must be. The engine simply requires this form to define a find_or_create_by method which returns an object of that class, to exist associated with a post when information technology's created. This object, of course, should have some sort of identifier by which information technology tin be referenced.

4.4.2 General Engine Configuration

Within an engine, there may come a fourth dimension 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 equally a Rails application. In fact, a Track awarding'due south functionality is actually a superset of what is provided by engines!

If y'all wish to use an initializer - lawmaking that should run before the engine is loaded - the place for information technology is the config/initializers binder. This directory's functionality is explained in the Initializers section of the Configuring guide, and works precisely the same way as the config/initializers directory inside an awarding. The same affair goes if you desire to use a standard initializer.

For locales, just identify the locale files in the config/locales directory, but like you would in an application.

5 Testing an engine

When an engine is generated, there is a smaller dummy awarding created inside it at test/dummy. This application is used equally a mounting betoken for the engine, to make testing the engine extremely simple. Yous may extend this application by generating controllers, models or views from within the directory, and then employ those to examination your engine.

The test directory should exist treated like a typical Rails testing surround, allowing for unit, functional and integration tests.

five.ane 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 awarding - rather than your engine. This is due to the setup of the testing environment; an engine needs an awarding as a host for testing its main functionality, especially controllers. This means that if you were to brand a typical Go to a controller in a controller's functional exam like this:

module Blorgh   class FooControllerTest < ActionController::TestCase     def test_index       become :index       ...     stop   end end          

It may not function correctly. This is because the awarding doesn't know how to route these requests to the engine unless yous explicitly tell it how. To practice this, you must set the @routes instance variable to the engine's route set in your setup code:

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 yous nonetheless want to perform a GET request to the index activeness of this controller, but y'all desire to use the engine'south route to get there, rather than the awarding's one.

This besides ensures that the engine'south URL helpers volition work as expected in your tests.

6 Improving engine functionality

This section explains how to add and/or override engine MVC functionality in the main Rails application.

6.one Overriding Models and Controllers

Engine model and controller classes can be extended by open classing them in the main Rails awarding (since model and controller classes are just Ruby classes that inherit Rails specific functionality). Open classing an Engine class redefines it for employ in the primary application. This is usually implemented past using the decorator pattern.

For simple class modifications, use Form#class_eval. For complex form modifications, consider using ActiveSupport::Business organisation.

six.one.one A note on Decorators and Loading Lawmaking

Because these decorators are not referenced past your Rails application itself, Rail' autoloading system volition not kick in and load your decorators. This means that y'all need to require them yourself.

Here is some sample code to do this:

# 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)       cease     terminate   end cease          

This doesn't use to but Decorators, but anything that you add in an engine that isn't referenced by your main application.

6.1.two Implementing Decorator Blueprint Using Class#class_eval

Adding Mail#time_since_created:

# MyApp/app/decorators/models/blorgh/post_decorator.rb  Blorgh::Postal service.class_eval do   def time_since_created     Time.current - created_at   stop end          

# Blorgh/app/models/post.rb  class Mail service < ActiveRecord::Base   has_many :comments end          

Overriding Mail#summary:

# MyApp/app/decorators/models/blorgh/post_decorator.rb  Blorgh::Post.class_eval do   def summary     "#{title} - #{truncate(text)}"   end end          

# Blorgh/app/models/mail service.rb  form Mail service < ActiveRecord::Base   has_many :comments   def summary     "#{title}"   terminate end          

6.1.3 Implementing Decorator Pattern Using ActiveSupport::Concern

Using Class#class_eval is peachy for unproblematic adjustments, but for more complex class modifications, yous might want to consider using ActiveSupport::Business concern. ActiveSupport::Business manages load order of interlinked dependent modules and classes at run time assuasive you to significantly modularize your lawmaking.

Adding Post#time_since_created and Overriding Post#summary:

# MyApp/app/models/blorgh/post.rb  form Blorgh::Mail service < ActiveRecord::Base   include Blorgh::Concerns::Models::Mail service    def time_since_created     Fourth dimension.electric current - created_at   end    def summary     "#{title} - #{truncate(text)}"   end end          

# Blorgh/app/models/postal service.rb  course Post < ActiveRecord::Base   include Blorgh::Concerns::Models::Post terminate          

# Blorgh/lib/concerns/models/post  module Blorgh::Concerns::Models::Mail service   extend ActiveSupport::Concern    # 'included do' causes the included code to be evaluated in the   # context where it is included (post.rb), rather than being   # executed in the module's context (blorgh/concerns/models/mail service).   included do     attr_accessor :author_name     belongs_to :writer, class_name: "User"      before_save :set_author      individual       def set_author         self.author = User.find_or_create_by(name: author_name)       terminate   end    def summary     "#{title}"   end    module ClassMethods     def some_class_method       'some class method string'     end   cease end          

6.two Overriding Views

When Rail looks for a view to render, it volition beginning look in the app/views directory of the awarding. If it cannot observe the view there, it volition check in the app/views directories of all engines that have this directory.

When the application is asked to return the view for Blorgh::PostsController'southward index activeness, it will first look for the path app/views/blorgh/posts/index.html.erb within the application. If it cannot observe it, it will look within the engine.

Y'all tin override this view in the awarding past simply creating a new file at app/views/blorgh/posts/index.html.erb. So you can completely alter what this view would usually output.

Try this now by creating a new file at app/views/blorgh/posts/index.html.erb and put this content in it:

<h1>Posts</h1> <%= link_to "New Post", new_post_path %> <% @posts.each exercise |post| %>   <h2><%= mail service.title %></h2>   <pocket-sized>By <%= post.author %></small>   <%= simple_format(post.text) %>   <hr> <% end %>          

6.3 Routes

Routes within an engine are isolated from the awarding by default. This is done by the isolate_namespace telephone call within the Engine grade. This essentially means that the awarding and its engines can have identically named routes and they will not clash.

Routes inside an engine are fatigued on the Engine form within config/routes.rb, similar this:

Blorgh::Engine.routes.draw exercise   resources :posts end          

By having isolated routes such as this, if you lot wish to link to an surface area of an engine from within an awarding, you will demand to use the engine's routing proxy method. Calls to normal routing methods such as posts_path may end up going to undesired locations if both the application and the engine have such a helper defined.

For case, the following case would become to the application's posts_path if that template was rendered from the application, or the engine'southward posts_path if it was rendered from the engine:

<%= link_to "Blog posts", posts_path %>          

To make this road always apply the engine's posts_path routing helper method, we must call the method on the routing proxy method that shares the same proper name equally the engine.

<%= link_to "Blog posts", blorgh.posts_path %>          

If you wish to reference the application inside the engine in a similar fashion, apply the main_app helper:

<%= link_to "Domicile", main_app.root_path %>          

If yous were to use this within an engine, it would e'er 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'due south or application's root, depending on where it was called from.

If a template rendered from within an engine attempts to utilise one of the awarding'southward routing helper methods, it may outcome in an undefined method call. If y'all encounter such an issue, ensure that yous're non attempting to call the application's routing methods without the main_app prefix from inside the engine.

6.4 Assets

Assets inside an engine work in an identical way to a total application. Because the engine class inherits from Rail::Engine, the application will know to look upwardly assets in the engine's 'app/assets' and 'lib/assets' directories.

Similar all of the other components of an engine, the assets should be namespaced. This means that if you accept an asset chosen style.css, it should be placed at app/avails/stylesheets/[engine proper noun]/style.css, rather than app/assets/stylesheets/style.css. If this asset isn't namespaced, there is a possibility that the host application could take an asset named identically, in which example the application'southward asset would take precedence and the engine's one would exist ignored.

Imagine that you did have an nugget located at app/avails/stylesheets/blorgh/way.css To include this nugget inside an application, simply utilize stylesheet_link_tag and reference the asset as if it were inside the engine:

<%= stylesheet_link_tag "blorgh/way.css" %>          

You tin can also specify these avails equally dependencies of other avails using Asset Pipeline require statements in processed files:

/*  *= crave blorgh/style */          

Remember that in order to use languages like Sass or CoffeeScript, you should add the relevant library to your engine'southward .gemspec.

6.v Separate Assets & Precompiling

There are some situations where your engine's assets are not required by the host awarding. For instance, say that y'all've created an admin functionality that only exists for your engine. In this instance, the host application doesn't demand to require admin.css or admin.js. Only the gem'south admin layout needs these assets. Information technology doesn't make sense for the host app to include "blorgh/admin.css" in its stylesheets. In this situation, yous should explicitly ascertain these assets for precompilation. This tells sprockets to add your engine assets when rake assets:precompile is triggered.

Yous can define avails for precompilation in engine.rb:

initializer "blorgh.avails.precompile" practice |app|   app.config.assets.precompile += %w(admin.css admin.js) stop          

For more than information, read the Asset Pipeline guide.

6.half dozen Other Gem Dependencies

Precious stone 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 non be installed, causing the engine to malfunction.

To specify a dependency that should exist installed with the engine during a traditional jewel install, specify it inside the Gem::Specification block inside the .gemspec file in the engine:

To specify a dependency that should only exist installed every bit a development dependency of the awarding, specify it similar this:

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 precious stone volition but be used when the tests for the engine are running.

Note that if you desire to immediately require dependencies when the engine is required, you lot should require them before the engine'southward initialization. For instance:

crave 'other_engine/engine' require 'yet_another_engine/engine'  module MyEngine   class Engine < ::Runway::Engine   finish end          

Feedback

You're encouraged to assist improve the quality of this guide.

Please contribute if you come across any typos or factual errors. To get started, you tin can read our documentation contributions section.

You lot may also detect incomplete content, or stuff that is non up to engagement. Please do add any missing documentation for master. Make certain to bank check Edge Guides showtime to verify if the issues are already fixed or non on the chief branch. Cheque the Cherry on Rail Guides Guidelines for style and conventions.

If for whatever reason you spot something to gear up simply cannot patch information technology yourself, please open an effect.

And concluding simply not least, any kind of discussion regarding Reddish on Rails documentation is very welcome in the rubyonrails-docs mailing list.

Source: https://guides.rubyonrails.org/v4.1/engines.html

Posted by: colemanpaland.blogspot.com

Share this post