Class: Rails::Engine

Inherits:
Railtie show all
Defined in:
lib/rails/engine.rb,
lib/rails/engine/updater.rb,
lib/rails/engine/railties.rb,
lib/rails/engine/configuration.rb

Overview

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

Besides the Railtie configuration which is shared across the application, in a Rails::Engine you can access autoload_paths, eager_load_paths and autoload_once_paths, which, differently from a Railtie, are scoped to the current 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 wrap with Engine and 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 just like that:

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 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 that 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]

Direct Known Subclasses

Application

Defined Under Namespace

Classes: Configuration, Railties, Updater

Constant Summary

Constants inherited from Railtie

Railtie::ABSTRACT_RAILTIES

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Railtie

abstract_railtie?, #configure, configure, console, generators, instance, railtie_name, #railtie_namespace, rake_tasks, runner, subclasses

Methods included from Initializable

included, #initializers, #run_initializers

Constructor Details

#initialize ⇒ Engine

Returns a new instance of Engine.



427
428
429
430
431
432
433
434
435
436
437
 
# File 'lib/rails/engine.rb', line 427

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

Class Attribute Details

.called_from ⇒ Object

Returns the value of attribute called_from.



351
352
353
 
# File 'lib/rails/engine.rb', line 351

def called_from
  @called_from
end

.isolated ⇒ Object Also known as: isolated?

Returns the value of attribute isolated.



351
352
353
 
# File 'lib/rails/engine.rb', line 351

def isolated
  @isolated
end

Class Method Details

.endpoint(endpoint = nil) ⇒ Object 



376
377
378
379
380
 
# File 'lib/rails/engine.rb', line 376

def endpoint(endpoint = nil)
  @endpoint ||= nil
  @endpoint = endpoint if endpoint
  @endpoint
end

.find(path) ⇒ Object

Finds engine with given path.



414
415
416
417
418
419
420
421
 
# File 'lib/rails/engine.rb', line 414

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

.find_root(from) ⇒ Object 



372
373
374
 
# File 'lib/rails/engine.rb', line 372

def find_root(from)
  find_root_with_flag "lib", from
end

.inherited(base) ⇒ Object 



358
359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/rails/engine.rb', line 358

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 !~ %r[railties[\w.-]*/lib/rails|rack[\w.-]*/lib/rack] })
    end
  end

  super
end

.isolate_namespace(mod) ⇒ Object 



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/rails/engine.rb', line 382

def isolate_namespace(mod)
  engine_name(generate_railtie_name(mod.name))

  routes.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}_" }
      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

Instance Method Details

#app ⇒ Object

Returns the underlying Rack application for this engine.



508
509
510
511
512
513
514
515
516
 
# File 'lib/rails/engine.rb', line 508

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

#call(env) ⇒ Object

Define the Rack API for this engine.



525
526
527
528
 
# File 'lib/rails/engine.rb', line 525

def call(env)
  req = build_request env
  app.call req.env
end

#config ⇒ Object

Define the configuration object for the engine.



544
545
546
 
# File 'lib/rails/engine.rb', line 544

def config
  @config ||= Engine::Configuration.new(self.class.find_root(self.class.called_from))
end

#eager_load! ⇒ Object 



472
473
474
475
476
477
478
479
480
481
482
483
484
 
# File 'lib/rails/engine.rb', line 472

def eager_load!
  # Already done by Zeitwerk::Loader.eager_load_all. We need this guard to
  # easily provide a compatible API for both zeitwerk and classic modes.
  return if Rails.autoloaders.zeitwerk_enabled?

  config.eager_load_paths.each do |load_path|
    # Starts after load_path plus a slash, ends before ".rb".
    relname_range = (load_path.to_s.length + 1)...-3
    Dir.glob("#{load_path}/**/*.rb").sort.each do |file|
      require_dependency file[relname_range]
    end
  end
end

#endpoint ⇒ Object

Returns the endpoint for this engine. If none is registered, defaults to an ActionDispatch::Routing::RouteSet.



520
521
522
 
# File 'lib/rails/engine.rb', line 520

def endpoint
  self.class.endpoint || routes
end

#env_config ⇒ Object

Defines additional Rack env configuration that is added on each call.



531
532
533
 
# File 'lib/rails/engine.rb', line 531

def env_config
  @env_config ||= {}
end

#helpers ⇒ Object

Returns a module with all the helpers defined for the engine.



491
492
493
494
495
496
497
498
499
500
 
# File 'lib/rails/engine.rb', line 491

def helpers
  @helpers ||= begin
    helpers = Module.new
    all = ActionController::Base.all_helpers_from_path(helpers_paths)
    ActionController::Base.modules_for_helpers(all).each do |mod|
      helpers.include(mod)
    end
    helpers
  end
end

#helpers_paths ⇒ Object

Returns all registered helpers paths.



503
504
505
 
# File 'lib/rails/engine.rb', line 503

def helpers_paths
  paths["app/helpers"].existent
end

#load_console(app = self) ⇒ Object

Load console and invoke the registered hooks. Check Rails::Railtie.console for more info.



441
442
443
444
445
446
 
# File 'lib/rails/engine.rb', line 441

def load_console(app = self)
  require "rails/console/app"
  require "rails/console/helpers"
  run_console_blocks(app)
  self
end

#load_generators(app = self) ⇒ Object

Load Rails generators and invoke the registered hooks. Check Rails::Railtie.generators for more info.



465
466
467
468
469
470
 
# File 'lib/rails/engine.rb', line 465

def load_generators(app = self)
  require "rails/generators"
  run_generators_blocks(app)
  Rails::Generators.configure!(app.config.generators)
  self
end

#load_runner(app = self) ⇒ Object

Load Rails runner and invoke the registered hooks. Check Rails::Railtie.runner for more info.



450
451
452
453
 
# File 'lib/rails/engine.rb', line 450

def load_runner(app = self)
  run_runner_blocks(app)
  self
end

#load_seed ⇒ Object

Load data from db/seeds.rb file. It can be used in to load engines’ seeds, e.g.:

Blog::Engine.load_seed



552
553
554
555
556
557
558
559
560
561
 
# File 'lib/rails/engine.rb', line 552

def load_seed
  seed_file = paths["db/seeds.rb"].existent.first
  return unless seed_file

  if config.try(:active_job)&.queue_adapter == :async
    with_inline_jobs { load(seed_file) }
  else
    load(seed_file)
  end
end

#load_tasks(app = self) ⇒ Object

Load Rake, railties tasks and invoke the registered hooks. Check Rails::Railtie.rake_tasks for more info.



457
458
459
460
461
 
# File 'lib/rails/engine.rb', line 457

def load_tasks(app = self)
  require "rake"
  run_tasks_blocks(app)
  self
end

#railties ⇒ Object 



486
487
488
 
# File 'lib/rails/engine.rb', line 486

def railties
  @railties ||= Railties.new
end

#routes(&block) ⇒ Object

Defines the routes for this engine. If a block is given to routes, it is appended to the engine.



537
538
539
540
541
 
# File 'lib/rails/engine.rb', line 537

def routes(&block)
  @routes ||= ActionDispatch::Routing::RouteSet.new_with_config(config)
  @routes.append(&block) if block_given?
  @routes
end

#routes? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


653
654
655
 
# File 'lib/rails/engine.rb', line 653

def routes? #:nodoc:
  @routes
end