require 'rails/railtie' require 'rails/engine/railties' require 'active_support/core_ext/module/delegation' require 'pathname' module Rails # 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", __FILE__) # # 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 explicity 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 # => # 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] class Engine < Railtie autoload :Configuration, "rails/engine/configuration" class << self attr_accessor :called_from, :isolated alias :isolated? :isolated alias :engine_name :railtie_name delegate :eager_load!, to: :instance def inherited(base) unless base.abstract_railtie? Rails::Railtie::Configuration.eager_load_namespaces << base base.called_from = begin call_stack = if Kernel.respond_to?(:caller_locations) caller_locations.map { |l| l.absolute_path || l.path } else # Remove the line number from backtraces making sure we don't leave anything behind caller.map { |p| p.sub(/:\d+.*/, '') } end File.dirname(call_stack.detect { |p| p !~ %r[railties[\w.-]*/lib/rails|rack[\w.-]*/lib/rack] }) end end super end def find_root(from) find_root_with_flag "lib", from end def endpoint(endpoint = nil) @endpoint ||= nil @endpoint = endpoint if endpoint @endpoint end def isolate_namespace(mod) engine_name(generate_railtie_name(mod.name)) self.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 # Finds engine with given path. 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 end delegate :middleware, :root, :paths, to: :config delegate :engine_name, :isolated?, to: :class def initialize @_all_autoload_paths = nil @_all_load_paths = nil @app = nil @config = nil @env_config = nil @helpers = nil @routes = nil super end # Load console and invoke the registered hooks. # Check Rails::Railtie.console for more info. def load_console(app=self) require "rails/console/app" require "rails/console/helpers" run_console_blocks(app) self end # Load Rails runner and invoke the registered hooks. # Check Rails::Railtie.runner for more info. def load_runner(app=self) run_runner_blocks(app) self end # Load Rake, railties tasks and invoke the registered hooks. # Check Rails::Railtie.rake_tasks for more info. def load_tasks(app=self) require "rake" run_tasks_blocks(app) self end # Load Rails generators and invoke the registered hooks. # Check Rails::Railtie.generators for more info. def load_generators(app=self) require "rails/generators" run_generators_blocks(app) Rails::Generators.configure!(app.config.generators) self end # Eager load the application by loading all ruby # files inside eager_load paths. def eager_load! config.eager_load_paths.each do |load_path| matcher = /\A#{Regexp.escape(load_path.to_s)}\/(.*)\.rb\Z/ Dir.glob("#{load_path}/**/*.rb").sort.each do |file| require_dependency file.sub(matcher, '\1') end end end def railties @railties ||= Railties.new end # Returns a module with all the helpers defined for the engine. 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 # Returns all registered helpers paths. def helpers_paths paths["app/helpers"].existent end # Returns the underlying rack application for this engine. def app @app ||= begin config.middleware = config.middleware.merge_into(default_middleware_stack) config.middleware.build(endpoint) end end # Returns the endpoint for this engine. If none is registered, # defaults to an ActionDispatch::Routing::RouteSet. def endpoint self.class.endpoint || routes end # Define the Rack API for this engine. def call(env) env.merge!(env_config) if env['SCRIPT_NAME'] env[routes.env_key] = env['SCRIPT_NAME'].dup end app.call(env) end # Defines additional Rack env configuration that is added on each call. def env_config @env_config ||= { 'action_dispatch.routes' => routes } end # Defines the routes for this engine. If a block is given to # routes, it is appended to the engine. def routes @routes ||= ActionDispatch::Routing::RouteSet.new_with_config(config) @routes.append(&Proc.new) if block_given? @routes end # Define the configuration object for the engine. def config @config ||= Engine::Configuration.new(self.class.find_root(self.class.called_from)) end # Load data from db/seeds.rb file. It can be used in to load engines' # seeds, e.g.: # # Blog::Engine.load_seed def load_seed seed_file = paths["db/seeds.rb"].existent.first load(seed_file) if seed_file end # Add configured load paths to ruby load paths and remove duplicates. initializer :set_load_path, before: :bootstrap_hook do _all_load_paths.reverse_each do |path| $LOAD_PATH.unshift(path) if File.directory?(path) end $LOAD_PATH.uniq! end # Set the paths from which Rails will automatically load source files, # and the load_once paths. # # This needs to be an initializer, since it needs to run once # per engine and get the engine as a block parameter. initializer :set_autoload_paths, before: :bootstrap_hook do ActiveSupport::Dependencies.autoload_paths.unshift(*_all_autoload_paths) ActiveSupport::Dependencies.autoload_once_paths.unshift(*_all_autoload_once_paths) # Freeze so future modifications will fail rather than do nothing mysteriously config.autoload_paths.freeze config.eager_load_paths.freeze config.autoload_once_paths.freeze end initializer :add_routing_paths do |app| routing_paths = self.paths["config/routes.rb"].existent if routes? || routing_paths.any? app.routes_reloader.paths.unshift(*routing_paths) app.routes_reloader.route_sets << routes end end # I18n load paths are a special case since the ones added # later have higher priority. initializer :add_locales do config.i18n.railties_load_path.concat(paths["config/locales"].existent) end initializer :add_view_paths do views = paths["app/views"].existent unless views.empty? ActiveSupport.on_load(:action_controller){ prepend_view_path(views) if respond_to?(:prepend_view_path) } ActiveSupport.on_load(:action_mailer){ prepend_view_path(views) } end end initializer :load_environment_config, before: :load_environment_hook, group: :all do paths["config/environments"].existent.each do |environment| require environment end end initializer :prepend_helpers_path do |app| if !isolated? || (app == self) app.config.helpers_paths.unshift(*paths["app/helpers"].existent) end end initializer :load_config_initializers do config.paths["config/initializers"].existent.sort.each do |initializer| load_config_initializer(initializer) end end initializer :engines_blank_point do # We need this initializer so all extra initializers added in engines are # consistently executed after all the initializers above across all engines. end rake_tasks do next if self.is_a?(Rails::Application) next unless has_migrations? namespace railtie_name do namespace :install do desc "Copy migrations from #{railtie_name} to application" task :migrations do ENV["FROM"] = railtie_name if Rake::Task.task_defined?("railties:install:migrations") Rake::Task["railties:install:migrations"].invoke else Rake::Task["app:railties:install:migrations"].invoke end end end end end def routes? #:nodoc: @routes end protected def load_config_initializer(initializer) ActiveSupport::Notifications.instrument('load_config_initializer.railties', initializer: initializer) do load(initializer) end end def run_tasks_blocks(*) #:nodoc: super paths["lib/tasks"].existent.sort.each { |ext| load(ext) } end def has_migrations? #:nodoc: paths["db/migrate"].existent.any? end def self.find_root_with_flag(flag, root_path, default=nil) #:nodoc: while root_path && File.directory?(root_path) && !File.exist?("#{root_path}/#{flag}") parent = File.dirname(root_path) root_path = parent != root_path && parent end root = File.exist?("#{root_path}/#{flag}") ? root_path : default raise "Could not find root path for #{self}" unless root Pathname.new File.realpath root end def default_middleware_stack #:nodoc: ActionDispatch::MiddlewareStack.new end def _all_autoload_once_paths #:nodoc: config.autoload_once_paths end def _all_autoload_paths #:nodoc: @_all_autoload_paths ||= (config.autoload_paths + config.eager_load_paths + config.autoload_once_paths).uniq end def _all_load_paths #:nodoc: @_all_load_paths ||= (config.paths.load_paths + _all_autoload_paths).uniq end end end