require 'rails/initializable'
require 'rails/configuration'
module Rails
# Railtie is the core of the Rails Framework and provides several hooks to extend
# Rails and/or modify the initialization process.
#
# Every major component of Rails (Action Mailer, Action Controller,
# Action View, Active Record and Active Resource) are all Railties, so each of
# them is responsible to set their own initialization. This makes, for example,
# Rails absent of any ActiveRecord hook, allowing any other ORM to hook in.
#
# Developing a Rails extension does not _require_ any implementation of
# Railtie, but if you need to interact with the Rails framework
# during boot, or after boot, then Railtie is what you need to do that
# interaction.
#
# For example, the following would need you to implement Railtie in your
# plugin:
#
# * creating initializers
# * configuring a Rails framework or the Application, like setting a generator
# * adding Rails config.* keys to the environment
# * setting up a subscriber to the Rails +ActiveSupport::Notifications+
# * adding rake tasks into rails
#
# == Creating your Railtie
#
# Implementing Railtie in your Rails extension is done by creating a class
# Railtie that has your extension name and making sure that this gets loaded
# during boot time of the Rails stack.
#
# You can do this however you wish, but here is an example if you want to provide
# it for a gem that can be used with or without Rails:
#
# * Create a file (say, lib/my_gem/railtie.rb) which contains class Railtie inheriting from
# Rails::Railtie and is namespaced to your gem:
#
# # lib/my_gem/railtie.rb
# module MyGem
# class Railtie < Rails::Railtie
# railtie_name :mygem
# end
# end
#
# * Require your own gem as well as rails in this file:
#
# # lib/my_gem/railtie.rb
# require 'my_gem'
# require 'rails'
#
# module MyGem
# class Railtie < Rails::Railtie
# railtie_name :mygem
# end
# end
#
# * Make sure your Gem loads the railtie.rb file if Rails is loaded first, an easy
# way to check is by checking for the Rails constant which will exist if Rails
# has started:
#
# # lib/my_gem.rb
# module MyGem
# require 'lib/my_gem/railtie' if defined?(Rails)
# end
#
# * Or instead of doing the require automatically, you can ask your users to require
# it for you in their Gemfile:
#
# # #{USER_RAILS_ROOT}/Gemfile
# gem "my_gem", :require_as => ["my_gem", "my_gem/railtie"]
#
# == Initializers
#
# To add an initialization step from your Railtie to Rails boot process, you just need
# to create an initializer block:
#
# class MyRailtie < Rails::Railtie
# initializer "my_railtie.configure_rails_initialization" do
# # some initialization behavior
# end
# end
#
# If specified, the block can also receive the application object, in case you
# need to access some application specific configuration:
#
# class MyRailtie < Rails::Railtie
# initializer "my_railtie.configure_rails_initialization" do |app|
# if app.config.cache_classes
# # some initialization behavior
# end
# end
# end
#
# Finally, you can also pass :before and :after as option to initializer, in case
# you want to couple it with a specific step in the initialization process.
#
# == Configuration
#
# Inside the Railtie class, you can access a config object which contains configuration
# shared by all railties and the application:
#
# class MyRailtie < Rails::Railtie
# # Customize the ORM
# config.generators.orm :my_railtie_orm
#
# # Add a middleware
# config.middlewares.use MyRailtie::Middleware
#
# # Add a to_prepare block which is executed once in production
# # and before which request in development
# config.to_prepare do
# MyRailtie.setup!
# end
# end
#
# == Loading rake tasks and generators
#
# If your railtie has rake tasks, you can tell Rails to load them through the method
# rake tasks:
#
# class MyRailtie < Railtie
# rake_tasks do
# load "path/to/my_railtie.tasks"
# end
# end
#
# By default, Rails load generators from your load path. However, if you want to place
# your generators at a different location, you can specify in your Railtie a block which
# will load them during normal generators lookup:
#
# class MyRailtie < Railtie
# generators do
# require "path/to/my_railtie_generator"
# end
# end
#
# == Adding your subscriber
#
# Since version 3.0, Rails ships with a notification system which is used for several
# purposes, including logging. If you are sending notifications in your Railtie, you may
# want to add a subscriber to consume such notifications for logging purposes.
#
# The subscriber is added under the railtie_name namespace and only consumes notifications
# under the given namespace. For example, let's suppose your railtie is publishing the
# following "something_expensive" instrumentation:
#
# ActiveSupport::Notifications.instrument "my_railtie.something_expensive" do
# # something expensive
# end
#
# You can log this instrumentation with your own Rails::Subscriber:
#
# class MyRailtie::Subscriber < Rails::Subscriber
# def something_expensive(event)
# info("Something expensive took %.1fms" % event.duration)
# end
# end
#
# By registering it:
#
# class MyRailtie < Railtie
# subscriber MyRailtie::Subscriber.new
# end
#
# Take a look in Rails::Subscriber docs for more information.
#
# == Application, Plugin and Engine
#
# A Rails::Engine is nothing more than a Railtie with some initializers already set.
# And since Rails::Application and Rails::Plugin are engines, the same configuration
# described here can be used in all three.
#
# Be sure to look at the documentation of those specific classes for more information.
#
class Railtie
autoload :Configurable, "rails/railtie/configurable"
autoload :Configuration, "rails/railtie/configuration"
include Initializable
ABSTRACT_RAILTIES = %w(Rails::Plugin Rails::Engine Rails::Application)
class << self
def subclasses
@subclasses ||= []
end
def inherited(base)
unless abstract_railtie?(base)
base.send(:include, self::Configurable)
subclasses << base
end
end
def railtie_name(railtie_name = nil)
@railtie_name ||= name.demodulize.underscore
@railtie_name = railtie_name if railtie_name
@railtie_name
end
def railtie_names
subclasses.map { |p| p.railtie_name }
end
def subscriber(subscriber)
Rails::Subscriber.add(railtie_name, subscriber)
end
def rake_tasks(&blk)
@rake_tasks ||= []
@rake_tasks << blk if blk
@rake_tasks
end
def generators(&blk)
@generators ||= []
@generators << blk if blk
@generators
end
protected
def abstract_railtie?(base)
ABSTRACT_RAILTIES.include?(base.name)
end
end
def rake_tasks
self.class.rake_tasks
end
def generators
self.class.generators
end
def load_tasks
rake_tasks.each { |blk| blk.call }
end
def load_generators
generators.each { |blk| blk.call }
end
end
end