Skip to content
This repository
Browse code

Config guide: begin documenting the initializers

  • Loading branch information...
commit 2484b7e92b519306c72e0c538ead607f4e15a6e6 1 parent 85ced0f
Ryan Bigg radar authored fxn committed

Showing 1 changed file with 101 additions and 4 deletions. Show diff stats Hide diff stats

  1. +101 4 railties/guides/source/configuring.textile
105 railties/guides/source/configuring.textile
Source Rendered
@@ -370,7 +370,6 @@ There are a few configuration options available in Active Support:
370 370
371 371 * +ActiveSupport::Logger.silencer+ is set to +false+ to disable the ability to silence logging in a block. The default is +true+.
372 372
373   -
374 373 h3. Rails Environment Settings
375 374
376 375 Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails:
@@ -388,7 +387,7 @@ h3. Initialization events
388 387 Rails has 5 initialization events which can be hooked into (listed in order that they are ran):
389 388
390 389 * +before_configuration+: This is run as soon as the application constant inherits from +Rails::Application+. The +config+ calls are evaluated before this happens.
391   -* +before_initialize+: This is run directly before the initialization process of the application occurs.
  390 +* +before_initialize+: This is run directly before the initialization process of the application occurs with the +:bootstrap_hook+ initializer near the beginning of the Rails initialization process.
392 391 * +to_prepare+: Run after the initializers are ran for all Railties (including the application itself), but before eager loading and the middleware stack is built.
393 392 * +before_eager_load+: This is run directly before eager loading occurs, which is the default behaviour for the _production_ environment and not for the +development+ enviroment.
394 393 * +after_initialize+: Run directly after the initialization of the application, but before the application initializers are run.
@@ -406,7 +405,6 @@ Rails has several initializers that run on startup that are all defined by using
406 405 end
407 406 </ruby>
408 407
409   -
410 408 The +initializer+ method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The +:before+ key in the options hash can be specified to specify which initializer this new initializer must run before, and the +:after+ key will specify which initializer to run this initializer _after_.
411 409
412 410 Initializers defined using the +initializer+ method will be ran in the order they are defined in, with the exception of ones that use the +:before+ or +:after+ methods.
@@ -415,6 +413,104 @@ WARNING: You may put your initializer before or after any other initializer in t
415 413
416 414 The block's argument of the +initialize+ is the instance of the application itself, and so we can access the configuration on it by using the +config+ method as this initializer does.
417 415
  416 +Because +Rails::Application+ inherits from +Rails::Railtie+ (indirectly), you can use the +initializer+ method in +config/application.rb+ to define initializers for the application.
  417 +
  418 +Below is a comprehensive list of all the initializers found in Rails in the order that they are defined (and therefore run in, unless otherwise stated).
  419 +
  420 +h4. +load_environment_hook+
  421 +
  422 +Serves as a placeholder so that +:load_environment_config+ can be defined to run before it.
  423 +
  424 +h4. +load_active_support+
  425 +
  426 +Requires +active_support/dependencies+ which sets up the basis for Active Support. Optionally requires +active_support/all+ if +config.active_support.bare+ is un-truthful, which is the default.
  427 +
  428 +h4. +preload_frameworks+
  429 +
  430 +Will load all autoload dependencies of Rails automatically if +config.preload_frameworks+ is +true+ or "truthful". By default this configuration option is disabled. In Rails, when internal classes are referenced for the first time they are autoloaded. +:preload_frameworks+ loads all of this at once on initialization.
  431 +
  432 +h4. +initialize_logger+
  433 +
  434 +Initializes the logger (an +ActiveSupport::BufferedLogger+ object) for the application and makes it accessible at +Rails.logger+, providing that there's no initializer inserted before this point that has defined +Rails.logger+.
  435 +
  436 +h4. +initialize_cache+
  437 +
  438 +If +RAILS_CACHE+ isn't yet set, initializes the cache by referencing the value in +config.cache_store+ and stores the outcome as +RAILS_CACHE+. If this object responds to the +middleware+ method, its middleware is inserted before +Rack::Runtime+ in the middleware stack.
  439 +
  440 +h4. +set_clear_dependencies_hook+
  441 +
  442 +Provides a hook for +active_record.set_dispatch_hooks+ to use, which will run before this initializer.
  443 +
  444 +This initializer -- which runs only if +cache_classes+ is set to +false+ -- uses +ActionDispatch::Callbacks.after+ to remove the constants which have been referenced during the request from the object space so that they will be reloaded during the following request.
  445 +
  446 +h4. +initialize_dependency_mechanism+
  447 +
  448 +If +config.cache_classes+ is set to +true+, configures +ActiveSupport::Dependencies.mechanism+ to +require+ dependencies rather than +load+ them.
  449 +
  450 +h4. +bootstrap_hook+
  451 +
  452 +Runs all configured +before_initialize+ blocks.
  453 +
  454 +h4. +i18n.callbacks+
  455 +
  456 +In the development environment, sets up a +to_prepare+ callback which will call +I18n.reload!+ if any of the locales have changed since the last request. In production mode this callback will only run on the first request.
  457 +
  458 +h4. +active_support.initialize_whiny_nils+
  459 +
  460 +Will require +active_support/whiny_nil+ if +config.whiny_nil+ is set to +true+. This file will output errors such as:
  461 +
  462 +<text>
  463 + Called id for nil, which would mistakenly be 4 -- if you really wanted the id of nil, use object_id
  464 +</text>
  465 +
  466 +And:
  467 +
  468 +<text>
  469 + You have a nil object when you didn't expect it!
  470 + You might have expected an instance of Array.
  471 + The error occurred while evaluating nil.each
  472 +</text>
  473 +
  474 +h4. +active_support.deprecation_behavior+
  475 +
  476 +Sets up deprecation reporting for environments, defaulting to +log+ for development, +notify+ for production and +stderr+ for test. If a value isn't set for +config.active_support.deprecation+ then this initializer will prompt the user to configure this line in the current environment's +config/environments+ file.
  477 +
  478 +h4. +active_support.initialize_time_zone+
  479 +
  480 +Sets the default time zone for the application based off the +config.time_zone+ setting, which defaults to "UTC".
  481 +
  482 +h4. +action_dispatch.configure+
  483 +
  484 +Configures the +ActionDispatch::Http::URL.tld_length+ to be set to the value of +config.action_dispatch.tld_length+.
  485 +
  486 +h4. +action_view.cache_asset_ids+
  487 +
  488 +Will set +ActionView::Helpers::AssetTagHelper::AssetPaths.cache_asset_ids+ to +false+ when Active Support loads, but only if +config.cache_classes+ is too.
  489 +
  490 +h4. +action_view.javascript_expansions+
  491 +
  492 +Registers the expansions set up by +config.action_view.javascript_expansions+ and +config.action_view.stylesheet_expansions+ to be recognised by Action View and therefore usable in the views.
  493 +
  494 +h4. +action_view.set_configs+
  495 +
  496 +Sets up Action View by using the settings in +config.action_view+ by +send+'ing the method names as setters to +ActionView::Base+ and passing the values through.
  497 +
  498 +h4. +action_controller.logger+
  499 +
  500 +Sets +ActionController::Base.logger+ -- if it's not already set -- to +Rails.logger+.
  501 +
  502 +h4. +action_controller.initialize_framework_caches+
  503 +
  504 +Sets +ActionController::Base.cache_store+ -- if it's not already set -- to +RAILS_CACHE+.
  505 +
  506 +h4. +action_controller.set_configs+
  507 +
  508 +Sets up Action View by using the settings in +config.action_controller+ by +send+'ing the method names as setters to +ActionController::Base+ and passing the values through.
  509 +
  510 +h4 +active_record.initialize_timezone+
  511 +
  512 +Sets +ActiveRecord::Base.time_zone_aware_attributes+ to true, as well as setting +ActiveRecord::Base.default_timezone+ to UTC.
  513 +
418 514 h4. Initializer files
419 515
420 516 After loading the framework and any gems and plugins in your application, Rails turns to loading initialization code from +config/initializers+. The files in this directory can be used to hold configuration settings that should be made after all of the frameworks and plugins are loaded.
@@ -425,7 +521,8 @@ TIP: If you have any ordering dependency in your initializers, you can control t
425 521
426 522 h3. Changelog
427 523
428   -* November 26, 2010: Removed all config settings not available in Rails 3 (Ryan Bigg)
  524 +* December 3, 2010: Added initialization events for Rails 3 ("Ryan Bigg":http://ryanbigg.com)
  525 +* November 26, 2010: Removed all config settings not available in Rails 3 ("Ryan Bigg":http://ryanbigg.com)
429 526 * August 13, 2009: Updated with config syntax and added general configuration options by "John Pignata"
430 527 * January 3, 2009: First reasonably complete draft by "Mike Gunderloy":credits.html#mgunderloy
431 528 * November 5, 2008: Rough outline by "Mike Gunderloy":credits.html#mgunderloy

0 comments on commit 2484b7e

Please sign in to comment.
Something went wrong with that request. Please try again.