class Rails::Engine
Rails::Engine
allows you to wrap a specific Rails application or subset of functionality and share it with other applications or within a larger packaged application. Every Rails::Application
is just an engine, which allows for simple feature and application sharing.
Any Rails::Engine
is also a Rails::Railtie
, so the same methods (like rake_tasks
and generators
) and configuration options that are available in railties can also be used in engines.
Creating an Engine
If you want a gem to behave as an engine, you have to specify an Engine
for it somewhere inside your plugin’s lib
folder (similar to how we specify a Railtie
):
# lib/my_engine.rb
module MyEngine
class Engine < Rails::Engine
end
end
Then ensure that this file is loaded at the top of your config/application.rb
(or in your Gemfile
), and it will automatically load models, controllers, and helpers inside app
, load routes at config/routes.rb
, load locales at config/locales/*/
, and load tasks at lib/tasks/*/
.
Configuration
Like railties, engines can access a config object which contains configuration shared by all railties and the application. Additionally, each engine can access autoload_paths
, eager_load_paths
and autoload_once_paths
settings which are scoped to that engine.
class MyEngine < Rails::Engine
# Add a load path for this specific Engine
config.autoload_paths << File.expand_path("lib/some/path", __dir__)
initializer "my_engine.add_middleware" do |app|
app.middleware.use MyEngine::Middleware
end
end
Generators
You can set up generators for engines with config.generators
method:
class MyEngine < Rails::Engine
config.generators do |g|
g.orm :active_record
g.template_engine :erb
g.test_framework :test_unit
end
end
You can also set generators for an application by using config.app_generators
:
class MyEngine < Rails::Engine
# note that you can also pass block to app_generators in the same way you
# can pass it to generators method
config.app_generators.orm :datamapper
end
Paths
Applications and engines have flexible path configuration, meaning that you are not required to place your controllers at app/controllers
, but in any place which you find convenient.
For example, let’s suppose you want to place your controllers in lib/controllers
. You can set that as an option:
class MyEngine < Rails::Engine
paths["app/controllers"] = "lib/controllers"
end
You can also have your controllers loaded from both app/controllers
and lib/controllers
:
class MyEngine < Rails::Engine
paths["app/controllers"] << "lib/controllers"
end
The available paths in an engine are:
class MyEngine < Rails::Engine
paths["app"] # => ["app"]
paths["app/controllers"] # => ["app/controllers"]
paths["app/helpers"] # => ["app/helpers"]
paths["app/models"] # => ["app/models"]
paths["app/views"] # => ["app/views"]
paths["lib"] # => ["lib"]
paths["lib/tasks"] # => ["lib/tasks"]
paths["config"] # => ["config"]
paths["config/initializers"] # => ["config/initializers"]
paths["config/locales"] # => ["config/locales"]
paths["config/routes.rb"] # => ["config/routes.rb"]
end
The Application
class adds a couple more paths to this set. And as in your Application
, all folders under app
are automatically added to the load path. If you have an app/services
folder for example, it will be added by default.
Endpoint
An engine can also be a Rack application. It can be useful if you have a Rack application that you would like to provide with some of the Engine
‘s features.
To do that, use the ::endpoint
method:
module MyEngine
class Engine < Rails::Engine
endpoint MyRackApplication
end
end
Now you can mount your engine in application’s routes:
Rails.application.routes.draw do
mount MyEngine::Engine => "/engine"
end
Middleware stack
As an engine can now be a Rack endpoint, it can also have a middleware stack. The usage is exactly the same as in Application
:
module MyEngine
class Engine < Rails::Engine
middleware.use SomeMiddleware
end
end
Routes
If you don’t specify an endpoint, routes will be used as the default endpoint. You can use them just like you use an application’s routes:
# ENGINE/config/routes.rb
MyEngine::Engine.routes.draw do
get "/" => "posts#index"
end
Mount priority
Note that now there can be more than one router in your application, and it’s better to avoid passing requests through many routers. Consider this situation:
Rails.application.routes.draw do
mount MyEngine::Engine => "/blog"
get "/blog/omg" => "main#omg"
end
MyEngine
is mounted at /blog
, and /blog/omg
points to application’s controller. In such a situation, requests to /blog/omg
will go through MyEngine
, and if there is no such route in Engine
‘s routes, it will be dispatched to main#omg
. It’s much better to swap that:
Rails.application.routes.draw do
get "/blog/omg" => "main#omg"
mount MyEngine::Engine => "/blog"
end
Now, Engine
will get only requests that were not handled by Application
.
Engine name
There are some places where an Engine’s name is used:
-
routes: when you mount an Engine with
mount(MyEngine::Engine => '/my_engine')
, it’s used as default:as
option -
rake task for installing migrations
my_engine:install:migrations
Engine name is set by default based on class name. For MyEngine::Engine
it will be my_engine_engine
. You can change it manually using the engine_name
method:
module MyEngine
class Engine < Rails::Engine
engine_name "my_engine"
end
end
Isolated Engine
Normally when you create controllers, helpers, and models inside an engine, they are treated as if they were created inside the application itself. This means that all helpers and named routes from the application will be available to your engine’s controllers as well.
However, sometimes you want to isolate your engine from the application, especially if your engine has its own router. To do that, you simply need to call ::isolate_namespace
. This method requires you to pass a module where all your controllers, helpers, and models should be nested to:
module MyEngine
class Engine < Rails::Engine
isolate_namespace MyEngine
end
end
With such an engine, everything that is inside the MyEngine
module will be isolated from the application.
Consider this controller:
module MyEngine
class FooController < ActionController::Base
end
end
If the MyEngine
engine is marked as isolated, FooController
only has access to helpers from MyEngine
, and url_helpers
from MyEngine::Engine.routes
.
The next thing that changes in isolated engines is the behavior of routes. Normally, when you namespace your controllers, you also need to namespace the related routes. With an isolated engine, the engine’s namespace is automatically applied, so you don’t need to specify it explicitly in your routes:
MyEngine::Engine.routes.draw do
resources :articles
end
If MyEngine
is isolated, the routes above will point to MyEngine::ArticlesController
. You also don’t need to use longer URL helpers like my_engine_articles_path
. Instead, you should simply use articles_path
, like you would do with your main application.
To make this behavior consistent with other parts of the framework, isolated engines also have an effect on ActiveModel::Naming
. In a normal Rails app, when you use a namespaced model such as Namespace::Article
, ActiveModel::Naming
will generate names with the prefix “namespace”. In an isolated engine, the prefix will be omitted in URL helpers and form fields, for convenience.
polymorphic_url(MyEngine::Article.new)
# => "articles_path" # not "my_engine_articles_path"
form_for(MyEngine::Article.new) do
text_field :title # => <input type="text" name="article[title]" id="article_title" />
end
Additionally, an isolated engine will set its own name according to its namespace, so MyEngine::Engine.engine_name
will return “my_engine”. It will also set MyEngine.table_name_prefix
to “my_engine_”, meaning for example that MyEngine::Article
will use the my_engine_articles
database table by default.
Using Engine’s routes outside Engine
Since you can now mount an engine inside application’s routes, you do not have direct access to Engine
‘s url_helpers
inside Application
. When you mount an engine in an application’s routes, a special helper is created to allow you to do that. Consider such a scenario:
# config/routes.rb
Rails.application.routes.draw do
mount MyEngine::Engine => "/my_engine", as: "my_engine"
get "/foo" => "foo#index"
end
Now, you can use the my_engine
helper inside your application:
class FooController < ApplicationController
def index
my_engine.root_url # => /my_engine/
end
end
There is also a main_app
helper that gives you access to application’s routes inside Engine:
module MyEngine
class BarController
def index
main_app.foo_path # => /foo
end
end
end
Note that the :as
option given to mount takes the engine_name
as default, so most of the time you can simply omit it.
Finally, if you want to generate a URL to an engine’s route using polymorphic_url
, you also need to pass the engine helper. Let’s say that you want to create a form pointing to one of the engine’s routes. All you need to do is pass the helper as the first element in array with attributes for URL:
form_for([my_engine, @user])
This code will use my_engine.user_path(@user)
to generate the proper route.
Isolated engine’s helpers
Sometimes you may want to isolate an engine, but use helpers that are defined for it. If you want to share just a few specific helpers you can add them to application’s helpers in ApplicationController:
class ApplicationController < ActionController::Base
helper MyEngine::SharedEngineHelper
end
If you want to include all of the engine’s helpers, you can use the helper method on an engine’s instance:
class ApplicationController < ActionController::Base
helper MyEngine::Engine.helpers
end
It will include all of the helpers from engine’s directory. Take into account this does not include helpers defined in controllers with helper_method or other similar solutions, only helpers defined in the helpers directory will be included.
Migrations & seed data
Engines can have their own migrations. The default path for migrations is exactly the same as in application: db/migrate
To use engine’s migrations in application you can use the rake task below, which copies them to application’s dir:
$ rake ENGINE_NAME:install:migrations
Note that some of the migrations may be skipped if a migration with the same name already exists in application. In such a situation you must decide whether to leave that migration or rename the migration in the application and rerun copying migrations.
If your engine has migrations, you may also want to prepare data for the database in the db/seeds.rb
file. You can load that data using the load_seed
method, e.g.
MyEngine::Engine.load_seed
Loading priority
In order to change engine’s priority you can use config.railties_order
in the main application. It will affect the priority of loading views, helpers, assets, and all the other files related to engine or application.
# load Blog::Engine with highest priority, followed by application and other railties
config.railties_order = [Blog::Engine, :main_app, :all]
Inherits From
-
class
Railtie
-
module
ActiveSupport::
Callbacks
Attributes
[RW] | called_from |
|
[RW] | isolated |
|
[RW] | isolated? |
Public class methods
Source code GitHub
# File railties/lib/rails/engine.rb, line 379
def endpoint(endpoint = nil)
@endpoint ||= nil
@endpoint = endpoint if endpoint
@endpoint
end
Finds engine with given path.
Source code GitHub
# File railties/lib/rails/engine.rb, line 424
def find(path)
expanded_path = File.expand_path path
Rails::Engine.subclasses.each do |klass|
engine = klass.instance
return engine if File.expand_path(engine.root) == expanded_path
end
nil
end
Source code GitHub
# File railties/lib/rails/engine.rb, line 375
def find_root(from)
find_root_with_flag "lib", from
end
Source code GitHub
# File railties/lib/rails/engine.rb, line 361
def inherited(base)
unless base.abstract_railtie?
Rails::Railtie::Configuration.eager_load_namespaces << base
base.called_from = begin
call_stack = caller_locations.map { |l| l.absolute_path || l.path }
File.dirname(call_stack.detect { |p| !p.match?(%r[railties[\w.-]*/lib/rails|rack[\w.-]*/lib/rack]) })
end
end
super
end
Source code GitHub
# File railties/lib/rails/engine.rb, line 385
def isolate_namespace(mod)
engine_name(generate_railtie_name(mod.name))
config.default_scope = { module: ActiveSupport::Inflector.underscore(mod.name) }
self.isolated = true
unless mod.respond_to?(:railtie_namespace)
name, railtie = engine_name, self
mod.singleton_class.instance_eval do
define_method(:railtie_namespace) { railtie }
unless mod.respond_to?(:table_name_prefix)
define_method(:table_name_prefix) { "#{name}_" }
ActiveSupport.on_load(:active_record) do
mod.singleton_class.redefine_method(:table_name_prefix) do
"#{ActiveRecord::Base.table_name_prefix}#{name}_"
end
end
end
unless mod.respond_to?(:use_relative_model_naming?)
class_eval "def use_relative_model_naming?; true; end", __FILE__, __LINE__
end
unless mod.respond_to?(:railtie_helpers_paths)
define_method(:railtie_helpers_paths) { railtie.helpers_paths }
end
unless mod.respond_to?(:railtie_routes_url_helpers)
define_method(:railtie_routes_url_helpers) { |include_path_helpers = true| railtie.routes.url_helpers(include_path_helpers) }
end
end
end
end
Source code GitHub
# File railties/lib/rails/engine.rb, line 440
def initialize
@_all_autoload_paths = nil
@_all_load_paths = nil
@app = nil
@config = nil
@env_config = nil
@helpers = nil
@routes = nil
@app_build_lock = Mutex.new
super
end
Public instance methods
Returns the underlying Rack application for this engine.
Source code GitHub
# File railties/lib/rails/engine.rb, line 517
def app
@app || @app_build_lock.synchronize {
@app ||= begin
stack = default_middleware_stack
config.middleware = build_middleware.merge_into(stack)
config.middleware.build(endpoint)
end
}
end
Define the Rack API for this engine.
Source code GitHub
# File railties/lib/rails/engine.rb, line 534
def call(env)
req = build_request env
app.call req.env
end
Define the configuration object for the engine.
Source code GitHub
# File railties/lib/rails/engine.rb, line 553
def config
@config ||= Engine::Configuration.new(self.class.find_root(self.class.called_from))
end
Source code GitHub
# File railties/lib/rails/engine.rb, line 491
def eager_load!
# Already done by Zeitwerk::Loader.eager_load_all. By now, we leave the
# method as a no-op for backwards compatibility.
end
Returns the endpoint for this engine. If none is registered, defaults to an ActionDispatch::Routing::RouteSet
.
Source code GitHub
# File railties/lib/rails/engine.rb, line 529
def endpoint
self.class.endpoint || routes
end
Defines additional Rack env configuration that is added on each call.
Source code GitHub
# File railties/lib/rails/engine.rb, line 540
def env_config
@env_config ||= {}
end
Returns a module with all the helpers defined for the engine.
Source code GitHub
# File railties/lib/rails/engine.rb, line 501
def helpers
@helpers ||= begin
helpers = Module.new
AbstractController::Helpers.helper_modules_from_paths(helpers_paths).each do |mod|
helpers.include(mod)
end
helpers
end
end
Returns all registered helpers paths.
Source code GitHub
# File railties/lib/rails/engine.rb, line 512
def helpers_paths
paths["app/helpers"].existent
end
Load console and invoke the registered hooks. Check Rails::Railtie.console
for more info.
Source code GitHub
# File railties/lib/rails/engine.rb, line 454
def load_console(app = self)
require "rails/console/methods"
run_console_blocks(app)
self
end
Load Rails generators and invoke the registered hooks. Check Rails::Railtie.generators
for more info.
Source code GitHub
# File railties/lib/rails/engine.rb, line 477
def load_generators(app = self)
require "rails/generators"
run_generators_blocks(app)
Rails::Generators.configure!(app.config.generators)
self
end
Load Rails runner and invoke the registered hooks. Check Rails::Railtie.runner
for more info.
Source code GitHub
# File railties/lib/rails/engine.rb, line 462
def load_runner(app = self)
run_runner_blocks(app)
self
end
Load data from db/seeds.rb file. It can be used in to load engines’ seeds, e.g.:
Blog::Engine.load_seed
Source code GitHub
# File railties/lib/rails/engine.rb, line 561
def load_seed
seed_file = paths["db/seeds.rb"].existent.first
run_callbacks(:load_seed) { load(seed_file) } if seed_file
end
Invoke the server registered hooks. Check Rails::Railtie.server
for more info.
Source code GitHub
# File railties/lib/rails/engine.rb, line 486
def load_server(app = self)
run_server_blocks(app)
self
end
Load Rake and railties tasks, and invoke the registered hooks. Check Rails::Railtie.rake_tasks
for more info.
Source code GitHub
# File railties/lib/rails/engine.rb, line 469
def load_tasks(app = self)
require "rake"
run_tasks_blocks(app)
self
end
Source code GitHub
# File railties/lib/rails/engine.rb, line 496
def railties
@railties ||= Railties.new
end
Defines the routes for this engine. If a block is given to routes, it is appended to the engine.
Source code GitHub
# File railties/lib/rails/engine.rb, line 546
def routes(&block)
@routes ||= config.route_set_class.new_with_config(config)
@routes.append(&block) if block_given?
@routes
end
Private instance methods
Source code GitHub
# File railties/lib/rails/engine.rb, line 692
def load_config_initializer(initializer) # :doc:
ActiveSupport::Notifications.instrument("load_config_initializer.railties", initializer: initializer) do
load(initializer)
end
end