diff options
Diffstat (limited to 'railties/doc/guides/source/configuring.txt')
| -rw-r--r-- | railties/doc/guides/source/configuring.txt | 89 |
1 files changed, 67 insertions, 22 deletions
diff --git a/railties/doc/guides/source/configuring.txt b/railties/doc/guides/source/configuring.txt index 945e48cd45..489e205eb1 100644 --- a/railties/doc/guides/source/configuring.txt +++ b/railties/doc/guides/source/configuring.txt @@ -6,23 +6,43 @@ This guide covers the configuration and initialization features available to Rai * Adjust the behavior of your Rails applications * Add additional code to be run at application start time +NOTE: The first edition of this Guide was written from the Rails 2.3 source code. While the information it contains is broadly applicable to Rails 2.2, backwards compatibility is not guaranteed. + == Locations for Initialization Code -preinitializers -environment.rb first -env-specific files -initializers (load_application_initializers) -after-initializer +Rails offers (at least) five good spots to place initialization code: + +* Preinitializers +* environment.rb +* Environment-specific Configuration Files +* Initializers (load_application_initializers) +* After-Initializers == Using a Preinitializer -== Initialization Process Settings +Rails allows you to use a preinitializer to run code before the framework itself is loaded. If you save code in +RAILS_ROOT/config/preinitializer.rb+, that code will be the first thing loaded, before any of the framework components (Active Record, Action Pack, and so on.) If you want to change the behavior of one of the classes that is used in the initialization process, you can do so in this file. == Configuring Rails Components +In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The +environment.rb+ and environment-specific configuration files (such as +config/environments/production.rb+) allow you to specify the various settings that you want to pass down to all of the components. For example, the default Rails 2.3 +environment.rb+ file includes one setting: + +[source, ruby] +------------------------------------------------------- +config.time_zone = 'UTC' +------------------------------------------------------- + +This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same +config+ object: + +[source, ruby] +------------------------------------------------------- +config.active_record.colorize_logging = false +------------------------------------------------------- + +Rails will use that particular setting to configure Active Record. + === Configuring Active Record -+ActiveRecord::Base+ includej a variety of configuration options: ++ActiveRecord::Base+ includes a variety of configuration options: +logger+ accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling +logger+ on either an ActiveRecord model class or an ActiveRecord model instance. Set to nil to disable logging. @@ -125,21 +145,21 @@ There are a number of settings available on +ActionMailer::Base+: +smtp_settings+ allows detailed configuration for the +:smtp+ delivery method. It accepts a hash of options, which can include any of these options: -* <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting. -* <tt>:port</tt> - On the off chance that your mail server doesn't run on port 25, you can change it. -* <tt>:domain</tt> - If you need to specify a HELO domain, you can do it here. -* <tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting. -* <tt>:password</tt> - If your mail server requires authentication, set the password in this setting. -* <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>. +* +:address+ - Allows you to use a remote mail server. Just change it from its default "localhost" setting. +* +:port+ - On the off chance that your mail server doesn't run on port 25, you can change it. +* +:domain+ - If you need to specify a HELO domain, you can do it here. +* +:user_name+ - If your mail server requires authentication, set the username in this setting. +* +:password+ - If your mail server requires authentication, set the password in this setting. +* +:authentication+ - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of +:plain+, +:login+, +:cram_md5+. +sendmail_settings+ allows detailed configuration for the +sendmail+ delivery method. It accepts a hash of options, which can include any of these options: -* <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>. -* <tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>. +* +:location+ - The location of the sendmail executable. Defaults to +/usr/sbin/sendmail+. +* +:arguments+ - The command line arguments. Defaults to +-i -t+. +raise_delivery_errors+ specifies whether to raise an error if email delivery cannot be completed. It defaults to +true+. -+delivery_method+ defines the delivery method. The allowed values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>. ++delivery_method+ defines the delivery method. The allowed values are +:smtp+ (default), +:sendmail+, and +:test+. +perform_deliveries+ specifies whether mail will actually be delivered. By default this is +true+; it can be convenient to set it to +false+ for testing. @@ -151,7 +171,7 @@ There are a number of settings available on +ActionMailer::Base+: +default_implicit_parts_order+ - When a message is built implicitly (i.e. multiple parts are assembled from templates which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to -<tt>["text/html", "text/enriched", "text/plain"]</tt>. Items that appear first in the array have higher priority in the mail client ++["text/html", "text/enriched", "text/plain"]+. Items that appear first in the array have higher priority in the mail client and appear last in the mime encoded message. === Configuring Active Resource @@ -174,21 +194,46 @@ There are a few configuration options available in Active Support: Active Model currently has a single configuration setting: -+ActiveModel::Errors.default_error_messages is an array containing all of the validation error messages. ++ActiveModel::Errors.default_error_messages+ is an array containing all of the validation error messages. == Using Initializers - organization, controlling load order + +After it loads the framework plus any gems and plugins in your application, Rails turns to loading initializers. An initializer is any file of ruby code stored under +/config/initializers+ in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and plugins are loaded. + +NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the +initializers+ folder on down. + +TIP: If you have any ordering dependency in your initializers, you can control the load order by naming. For example, +01_critical.rb+ will be loaded before +02_normal.rb+. == Using an After-Initializer +After-initializers are run (as you might guess) after any initializers are loaded. You can supply an +after_initialize+ block (or an array of such blocks) by setting up +config.after_initialize+ in any of the Rails configuration files: + +[source, ruby] +------------------------------------------------------------------ +config.after_initialize do + SomeClass.init +end +------------------------------------------------------------------ + +WARNING: Some parts of your application, notably observers and routing, are not yet set up at the point where the +after_initialize+ block is called. + == Rails Environment Settings -ENV +Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails: + ++ENV['RAILS_ENV']+ defines the Rails environment (production, development, test, and so on) that Rails will run under. + ++ENV['RAILS_RELATIVE_URL_ROOT']+ is used by the routing code to recognize URLs when you deploy your application to a subdirectory. + ++ENV["RAILS_ASSET_ID"]+ will override the default cache-busting timestamps that Rails generates for downloadable assets. + ++ENV["RAILS_CACHE_ID"]+ and +ENV["RAILS_APP_VERSION"]+ are used to generate expanded cache keys in Rails' caching code. This allows you to have multiple separate caches from the same application. + ++ENV['RAILS_GEM_VERSION']+ defines the version of the Rails gems to use, if +RAILS_GEM_VERSION+ is not defined in your +environment.rb+ file. == Changelog == http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/28[Lighthouse ticket] +* January 3, 2009: First reasonably complete draft by link:../authors.html#mgunderloy[Mike Gunderloy] * November 5, 2008: Rough outline by link:../authors.html#mgunderloy[Mike Gunderloy] - -need to look for def self. ??? |