diff options
Diffstat (limited to 'railties/lib/rails')
| -rw-r--r-- | railties/lib/rails/railtie.rb | 108 | ||||
| -rw-r--r-- | railties/lib/rails/subscriber.rb | 15 |
2 files changed, 115 insertions, 8 deletions
diff --git a/railties/lib/rails/railtie.rb b/railties/lib/rails/railtie.rb index c038d0ac70..2dc2ba1002 100644 --- a/railties/lib/rails/railtie.rb +++ b/railties/lib/rails/railtie.rb @@ -2,6 +2,114 @@ require 'rails/initializable' require 'rails/configuration' module Rails + # Railtie is the core of the Rails Framework and provides all the hooks and + # methods you need to link your plugin into Rails. + # + # What Railtie does is make every component of Rails a "plugin" and creates + # an API that exposes all the powers that the builtin components need + # to any plugin author. + # + # In fact, every major component of Rails (Action Mailer, Action Controller, + # Action View, Active Record and Active Resource) are all now just plain + # old plugins, so anything they can do, your plugin can do. + # + # Developing a plugin for Rails does not _require_ any implementation of + # Railtie, there is no fixed rule, but as a guideline, if your plugin works + # by just being required before Rails boots, then there is no need for you + # to hook into 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 (including route insertion) + # * modifying the render path (think HAML et al) + # * adding Rails config.* keys to the environment + # * setting up a subscriber to the Rails +ActiveSupport::Notifications+ + # * adding global Rake tasks into rails + # * setting up a default configuration for the Application + # + # Railtie gives you a central place to connect into the Rails framework. If you + # find yourself writing plugin code that is having to monkey patch parts of the + # Rails framework to achieve something, there is probably a better, more elegant + # way to do it through Railtie, if there isn't, then you have found a lacking + # feature of Railtie, please lodge a ticket. + # + # Implementing Railtie in your plugin is by creating a class Railtie in your + # application that has your plugin name and making sure that this gets loaded + # durng boot time of the Rails stack. + # + # You can do this however you wish, but three straight forward ways are: + # + # == For gems or plugins that are not used outside of Rails + # + # * Create a Railtie subclass within your lib/my_plugin.rb file: + # + # # lib/my_plugin.rb + # module MyPlugin + # class Railtie < Rails::Railtie + # end + # end + # + # * Pass in your plugin name + # + # # lib/my_plugin.rb + # module MyPlugin + # class Railtie < Rails::Railtie + # plugin_name :my_plugin + # end + # end + # + # == For gems that could be used 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 + # 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 + # end + # end + # + # * Give your gem a unique name: + # + # # lib/my_gem/railtie.rb + # require 'my_gem' + # require 'rails' + # + # module MyGem + # class Railtie < Rails::Railtie + # plugin_name :my_gem + # 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/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"] + # class Railtie autoload :Configurable, "rails/railtie/configurable" autoload :Configuration, "rails/railtie/configuration" diff --git a/railties/lib/rails/subscriber.rb b/railties/lib/rails/subscriber.rb index 8c62f562d9..6638ff28c1 100644 --- a/railties/lib/rails/subscriber.rb +++ b/railties/lib/rails/subscriber.rb @@ -3,10 +3,10 @@ require 'active_support/notifications' module Rails # Rails::Subscriber is an object set to consume ActiveSupport::Notifications - # on initialization with solely purpose of logging. The subscriber dispatches - # notifications to a regirested object based on its given namespace. + # on initialization with the sole purpose of logging. The subscriber dispatches + # notifications to a registered object based on it's given namespace. # - # An example would be ActiveRecord subscriber responsible for logging queries: + # An example would be an Active Record subscriber responsible for logging queries: # # module ActiveRecord # class Railtie @@ -18,16 +18,16 @@ module Rails # end # end # - # It's finally registed as: + # Which would be registed as: # # Rails::Subscriber.add :active_record, ActiveRecord::Railtie::Subscriber.new # - # So whenever a "active_record.sql" notification arrive to Rails::Subscriber, + # So whenever an +active_record.sql+ notification arrives to Rails::Subscriber, # it will properly dispatch the event (ActiveSupport::Notifications::Event) to # the sql method. # - # This is useful because it avoids spanning several subscribers just for logging - # purposes(which slows down the main thread). Besides of providing a centralized + # This avoids spanning several subscribers just for logging purposes + # (which slows down the main thread). It also provides a centralized # facility on top of Rails.logger. # # Subscriber also has some helpers to deal with logging and automatically flushes @@ -97,7 +97,6 @@ module Rails # option is set to true, it also adds bold to the string. This is based # on Highline implementation and it automatically appends CLEAR to the end # of the returned String. - # def color(text, color, bold=false) return text unless colorize_logging color = self.class.const_get(color.to_s.upcase) if color.is_a?(Symbol) |