diff --git a/railties/doc/guides/html/action_mailer_basics.html b/railties/doc/guides/html/action_mailer_basics.html new file mode 100644 index 0000000000..56451818eb --- /dev/null +++ b/railties/doc/guides/html/action_mailer_basics.html @@ -0,0 +1,197 @@ + + + + + Action Mailer Basics + + + + + + + + +

+ + + +

Action Mailer Basics

This guide should provide you with all you need to get started in sending emails from your application, and will also cover how to test your mailers.

1. What is Action Mailer?

Action Mailer allows you to send email from your application using a mailer model and views. +Yes, that is correct, in Rails, emails are used by creating Models that inherit from ActionMailer::Base. They live alongside other models in /app/models BUT they have views just like controllers that appear alongside other views in app/views.

2. Quick walkthrough to creating a Mailer

Let’s say you want to send a welcome email to a user after they signup. Here is how you would go about this:

2.1. 1. Create the mailer:

./script/generate mailer UserMailer
+exists  app/models/
+create  app/views/user_mailer
+exists  test/unit/
+create  test/fixtures/user_mailer
+create  app/models/user_mailer.rb
+create  test/unit/user_mailer_test.rb

So we got the model, the fixtures, and the tests all created for us

2.2. 2. Edit the model:

class UserMailer < ActionMailer::Base
+
+end

Lets add a method called welcome_email, that will send an email to the user’s registered email address:

class UserMailer < ActionMailer::Base
+
+  def welcome_email(user)
+    recipients    user.email
+    from          "My Awesome Site Notifications<notifications@example.com>"
+    subject       "Welcome to My Awesome Site"
+    sent_on       Time.now
+    body          {:user => user, :url => "http://example.com/login"}
+    content_type  "text/html"
+  end
+
+end

So what do we have here? +recipients: who the recipients are, put in an array for multiple, ie, @recipients = ["user1@example.com", "user2@example.com"] +from: Who the email will appear to come from in the recipients' mailbox +subject: The subject of the email +sent_on: Timestamp for the email +content_type: The content type, by default is text/plain

How about @body[:user]? Well anything you put in the @body hash will appear in the mailer view (more about mailer views below) as an instance variable ready for you to use, ie, in our example the mailer view will have a @user instance variable available for its consumption.

2.3. 3. Create the mailer view

The file can look like:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+  <head>
+    <meta content='text/html; charset=iso-8859-1' http-equiv='Content-Type' />
+  </head>
+  <body>
+    <h1>Welcome to example.com, <%= @user.first_name %></h1>
+
+    <p>
+      You have successfully signed up to example.com, and your username is: <%= @user.login %>.<br/>
+      To login to the site, just follow this link: <%= @url %>.
+    </p>
+    <p>Thanks for joining and have a great day!</p>
+  </body>
+</html>

2.4. 4. Wire it up so that the system sends the email when a user signs up

There are 3 was to achieve this. One is to send the email from the controller that sends the email, another is to put it in a before_create block in the user model, and the last one is to use an observer on the user model. Whether you use the second or third methods is up to you, but staying away from the first is recommended. Not because it’s wrong, but because it keeps your controller clean, and keeps all logic related to the user model within the user model. This way, whichever way a user is created (from a web form, or from an API call, for example), we are guaranteed that the email will be sent.

# Code that already exists
+
+Rails::Initializer.run do |config|
+
+  # Code that already exists
+
+  config.active_record.observers = :user_observer
+
+end

# Code that already exists
+
+Rails::Initializer.run do |config|
+
+  # Code that already exists
+
+  config.load_paths += %W(#{RAILS_ROOT}/app/observers)
+
+  config.active_record.observers = :user_observer
+
+end

ALMOST THERE :) Now all we need is that danged observer, and we’re done:

class UserObserver < ActiveRecord::Observer
+  def after_create(user)
+    UserMailer.deliver_welcome_email(user)
+  end
+end

Notice how we call deliver_welcome_email? Where is that method? Well if you remember, we created a method called welcome_email in UserMailer, right? Well, as part of the "magic" of rails, we deliver the email identified by welcome_email by calling deliver_welcome_email.

That’s it! Now whenever your users signup, they will be greeted with a nice welcome email. Next up, we’ll talk about how to test a mailer model.

3. Mailer Testing

+ +

+ + diff --git a/railties/doc/guides/html/actioncontroller_basics.html b/railties/doc/guides/html/actioncontroller_basics.html index 76d7ee0588..f5b25a4d7a 100644 --- a/railties/doc/guides/html/actioncontroller_basics.html +++ b/railties/doc/guides/html/actioncontroller_basics.html @@ -181,7 +181,7 @@ Deal with exceptions that may be raised during request processing

A controller is a Ruby class which inherits from ApplicationController and has methods just like any other class. When your application receives a request, the routing will determine which controller and action to run, then Rails creates an instance of that controller and runs the public method with the same name as the action.

@@ -205,7 +205,7 @@ private

There’s no rule saying a method on a controller has to be an action; they may well be used for other purposes such as filters, which will be covered later in this guide.

As an example, if a user goes to /clients/new in your application to add a new client, Rails will create an instance of ClientsController and run the new method. Note that the empty method from the example above could work just fine because Rails will by default render the new.html.erb view unless the action says otherwise. The new method could make available to the view a @client instance variable by creating a new Client:

@@ -219,7 +219,7 @@ http://www.gnu.org/software/src-highlite -->

You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from a HTML form which has been filled in by the user. It’s called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the params hash in your controller:

@@ -282,7 +282,7 @@ http://www.gnu.org/software/src-highlite -->

3.2. Routing Parameters

The params hash will always contain the :controller and :action keys, but you should use the methods controller_name and action_name instead to access these values. Any other parameters defined by the routing, such as :id will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the :status parameter in a "pretty" URL:

@@ -335,7 +335,7 @@ ActiveRecordStore - Stores the data in a database using Active Record.

Read more about session storage in the Security Guide.

If you need a different session storage mechanism, you can change it in the config/environment.rb file:

@@ -353,7 +353,7 @@ config.action_controller

Session values are stored using key/value pairs like a hash:

@@ -371,7 +371,7 @@ private end

To store something in the session, just assign it to the key like a hash:

@@ -389,7 +389,7 @@ http://www.gnu.org/software/src-highlite --> end

To remove something from the session, assign that key to be nil:

@@ -407,7 +407,7 @@ http://www.gnu.org/software/src-highlite -->

4.2. The flash

The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for storing error messages etc. It is accessed in much the same way as the session, like a hash. Let’s use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request:

@@ -439,7 +439,7 @@ http://www.gnu.org/software/src-highlite -->

This way, if an action sets an error or a notice message, the layout will display it automatically.

If you want a flash value to be carried over to another request, use the keep method:

@@ -457,7 +457,7 @@ http://www.gnu.org/software/src-highlite -->

4.2.1. `flash.now`

By default, adding values to the flash will make them available to the next request, but sometimes you may want to access those values in the same request. For example, if the create action fails to save a resource and you render the new template directly, that’s not going to result in a new request, but you may still want to display a message using the flash. To do this, you can use flash.now in the same way you use the normal flash:

@@ -479,7 +479,7 @@ http://www.gnu.org/software/src-highlite -->

Your application can store small amounts of data on the client - called cookies - that will be persisted across requests and even sessions. Rails provides easy access to cookies via the cookies method, which - much like the session - works like a hash:

@@ -514,7 +514,7 @@ http://www.gnu.org/software/src-highlite -->

Filters are methods that are run before, after or "around" a controller action. For example, one filter might check to see if the logged in user has the right credentials to access that particular controller or action. Filters are inherited, so if you set a filter on ApplicationController, it will be run on every controller in your application. A common, simple filter is one which requires that a user is logged in for an action to be run. You can define the filter method this way:

@@ -541,7 +541,7 @@ private end

The method simply stores an error message in the flash and redirects to the login form if the user is not logged in. If a before filter (a filter which is run before the action) renders or redirects, the action will not run. If there are additional filters scheduled to run after the rendering or redirecting filter, they are also cancelled. To use this filter in a controller, use the before_filter method:

@@ -552,7 +552,7 @@ http://www.gnu.org/software/src-highlite --> end

In this example, the filter is added to ApplicationController and thus all controllers in the application. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn’t be able to log in in the first place!), not all controllers or actions should require this. You can prevent this filter from running before particular actions with skip_before_filter:

@@ -565,7 +565,7 @@ http://www.gnu.org/software/src-highlite -->

6.1. After Filters and Around Filters

In addition to the before filters, you can run filters after an action has run or both before and after. The after filter is similar to the before filter, but because the action has already been run it has access to the response data that’s about to be sent to the client. Obviously, after filters can not stop the action from running. Around filters are responsible for running the action, but they can choose not to, which is the around filter’s way of stopping it.

@@ -589,7 +589,7 @@ private

While the most common way to use filters is by creating private methods and using *_filter to add them, there are two other ways to do the same thing.

The first is to use a block directly with the *_filter methods. The block receives the controller as an argument, and the require_login filter from above could be rewritten to use a block:

@@ -601,7 +601,7 @@ http://www.gnu.org/software/src-highlite -->

Note that the filter in this case uses send because the logged_in? method is private and the filter is not run in the scope of the controller. This is not the recommended way to implement this particular filter, but in more simple cases it might be useful.

The second way is to use a class (actually, any object that responds to the right methods will do) to handle the filtering. This is useful in cases that are more complex than can not be implemented in a readable and reusable way using the two other methods. As an example, you could rewrite the login filter again to use a class:

@@ -629,7 +629,7 @@ http://www.gnu.org/software/src-highlite -->

Verifications make sure certain criteria are met in order for a controller or action to run. They can specify that a certain key (or several keys in the form of an array) is present in the params, session or flash hashes or that a certain HTTP method was used or that the request was made using XMLHTTPRequest (Ajax). The default action taken when these criteria are not met is to render a 400 Bad Request response, but you can customize this by specifying a redirect URL or rendering something else and you can also add flash messages and HTTP headers to the response. It is described in the API documentation as "essentially a special kind of before_filter".

Here’s an example of using verification to make sure the user supplies a username and a password in order to log in:

@@ -652,7 +652,7 @@ http://www.gnu.org/software/src-highlite --> end

Now the create action won’t run unless the "username" and "password" parameters are present, and if they’re not, an error message will be added to the flash and the new action will be rendered. But there’s something rather important missing from the verification above: It will be used for every action in LoginsController, which is not what we want. You can limit which actions it will be used for with the :only and :except options just like a filter:

@@ -670,7 +670,7 @@ http://www.gnu.org/software/src-highlite -->

Cross-site request forgery is a type of attack in which a site tricks a user into making requests on another site, possibly adding, modifying or deleting data on that site without the user’s knowledge or permission. The first step to avoid this is to make sure all "destructive" actions (create, update and destroy) can only be accessed with non-GET requests. If you’re following RESTful conventions you’re already doing this. However, a malicious site can still send a non-GET request to your site quite easily, and that’s where the request forgery protection comes in. As the name says, it protects from forged requests. The way this is done is to add a non-guessable token which is only known to your server to each request. This way, if a request comes in without the proper token, it will be denied access.

If you generate a form like this:

@@ -680,7 +680,7 @@ http://www.gnu.org/software/src-highlite --> <% end -%>

You will see how the token gets added as a hidden field:

@@ -797,7 +797,7 @@ headers - Headers used for the response.

9.2.1. Setting Custom Headers

If you want to set custom headers for a response then response.headers is the place to do it. The headers attribute is a hash which maps header names to their values, and Rails will set some of them - like "Content-Type" - automatically. If you want to add or change a header, just assign it to headers with the name and value:

@@ -807,7 +807,7 @@ http://www.gnu.org/software/src-highlite -->

Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser’s HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, authenticate_or_request_with_http_basic.

@@ -833,7 +833,7 @@ private

Sometimes you may want to send a file to the user instead of rendering an HTML page. All controllers in Rails have the send_data and the send_file methods, that will both stream data to the client. send_file is a convenience method which lets you provide the name of a file on the disk and it will stream the contents of that file for you.

To stream data to the client, use send_data:

@@ -862,7 +862,7 @@ private

11.1. Sending Files

If you want to send a file that already exists on disk, use the send_file method. This is usually not recommended, but can be useful if you want to perform some authentication before letting the user download the file.

@@ -895,7 +895,7 @@ http://www.gnu.org/software/src-highlite -->

11.2. RESTful Downloads

While send_data works just fine, if you are creating a RESTful application having separate actions for file downloads is usually not necessary. In REST terminology, the PDF file from the example above can be considered just another representation of the client resource. Rails provides an easy and quite sleek way of doing "RESTful downloads". Here’s how you can rewrite the example so that the PDF download is a part of the show action, without any streaming:

@@ -914,7 +914,7 @@ http://www.gnu.org/software/src-highlite --> end

In order for this example to work, you have to add the PDF MIME type to Rails. This can be done by adding the following line to the file config/initializers/mime_types.rb:

@@ -937,7 +937,7 @@ http://www.gnu.org/software/src-highlite -->

Rails keeps a log file for each environment (development, test and production) in the log folder. These are extremely useful when debugging what’s actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The filter_parameter_logging method can be used to filter out sensitive information from the log. It works by replacing certain values in the params hash with "[FILTERED]" as they are written to the log. As an example, let’s see how to filter all parameters with keys that include "password":

@@ -957,7 +957,7 @@ http://www.gnu.org/software/src-highlite -->

If you want to do something a bit more elaborate when catching errors, you can use rescue_from, which handles exceptions of a certain type (or multiple types) in an entire controller and its subclasses. When an exception occurs which is caught by a rescue_from directive, the exception object is passed to the handler. The handler can be a method or a Proc object passed to the :with option. You can also use a block directly instead of an explicit Proc object.

Here’s how you can use rescue_from to intercept all ActiveRecord::RecordNotFound errors and do something with them.

@@ -974,7 +974,7 @@ private end

Of course, this example is anything but elaborate and doesn’t improve on the default exception handling at all, but once you can catch all those exceptions you’re free to do whatever you want with them. For example, you could create custom exception classes that will be thrown when a user doesn’t have access to a certain section of your application:

diff --git a/railties/doc/guides/html/active_record_querying.html b/railties/doc/guides/html/active_record_querying.html index d5b0c42dca..e42bd80e2b 100644 --- a/railties/doc/guides/html/active_record_querying.html +++ b/railties/doc/guides/html/active_record_querying.html @@ -174,7 +174,7 @@ Perform various calculations on Active Record models

If you’re used to using raw SQL to find database records then, generally, you will find that there are better ways to carry out the same operations in Rails. Active Record insulates you from the need to use SQL in most cases.

Code examples throughout this guide will refer to one or more of the following models:

@@ -185,7 +185,7 @@ http://www.gnu.org/software/src-highlite --> has_and_belongs_to_many :roles end

@@ -193,14 +193,14 @@ http://www.gnu.org/software/src-highlite --> belongs_to :client end

class MailingAddress < Address
 end

@@ -208,7 +208,7 @@ http://www.gnu.org/software/src-highlite --> belongs_to :client, :counter_cache => true end

@@ -225,7 +225,7 @@ http://www.gnu.org/software/src-highlite -->

To retrieve objects from the database, Active Record provides a primary method called find. This method allows you to pass arguments into it to perform certain queries on your database without the need of SQL. If you wanted to find the record with the id of 1, you could type Client.find(1) which would execute this query on your database:

@@ -240,7 +240,7 @@ http://www.gnu.org/software/src-highlite -->

If you wanted to find clients with id 1 or 2, you call Client.find([1,2]) or Client.find(1,2) and then this will be executed as:

@@ -271,7 +271,7 @@ http://www.gnu.org/software/src-highlite -->

If you were reading your log file (the default is log/development.log) you may see something like this:

@@ -286,7 +286,7 @@ http://www.gnu.org/software/src-highlite -->

If you were reading your log file (the default is log/development.log) you may see something like this:

@@ -300,7 +300,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -334,14 +334,14 @@ http://www.gnu.org/software/src-highlite -->

Now what if that number could vary, say as a argument from somewhere, or perhaps from the user’s level status somewhere? The find then becomes something like Client.first(:conditions => ["orders_count = ?", params[:orders]]). Active Record will go through the first element in the conditions value and any additional elements will replace the question marks (?) in the first element. If you want to specify two conditions, you can do it like Client.first(:conditions => ["orders_count = ? AND locked = ?", params[:orders], false]). In this example, the first question mark will be replaced with the value in params[:orders] and the second will be replaced with the SQL representation of false, which depends on the adapter.

The reason for doing code like:

Client.first(:conditions => ["orders_count = ?", params[:orders]])

instead of:

@@ -357,7 +357,7 @@ http://www.gnu.org/software/src-highlite -->

If you’re looking for a range inside of a table (for example, users created in a certain timeframe) you can use the conditions option coupled with the IN sql statement for this. If you had two dates coming in from a controller you could do something like this to look for a range:

@@ -365,7 +365,7 @@ http://www.gnu.org/software/src-highlite --> (params[:start_date].to_date)..(params[:end_date].to_date)])

This would generate the proper query which is great for small ranges but not so good for larger ranges. For example if you pass in a range of date objects spanning a year that’s 365 (or possibly 366, depending on the year) strings it will attempt to match your field against.

@@ -379,14 +379,14 @@ http://www.gnu.org/software/src-highlite --> '2008-12-27','2008-12-28','2008-12-29','2008-12-30','2008-12-31'))

Things can get really messy if you pass in Time objects as it will attempt to compare your field to every second in that range:

Client.all(:conditions => ["created_at IN (?)",
   (params[:start_date].to_date.to_time)..(params[:end_date].to_date.to_time)])

@@ -401,7 +401,7 @@ http://www.gnu.org/software/src-highlite -->

Where query is the actual query used to get that error.

In this example it would be better to use greater-than and less-than operators in SQL, like so:

@@ -409,7 +409,7 @@ http://www.gnu.org/software/src-highlite --> ["created_at > ? AND created_at < ?", params[:start_date], params[:end_date]])

You can also use the greater-than-or-equal-to and less-than-or-equal-to like this:

@@ -419,7 +419,7 @@ http://www.gnu.org/software/src-highlite -->

2.3. Placeholder Conditions

Similar to the array style of params you can also specify keys in your conditions:

@@ -429,28 +429,28 @@ http://www.gnu.org/software/src-highlite -->

2.4. Hash Conditions

Rails also allows you to pass in a hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them:

Client.all(:conditions => { :locked => true })

The field name does not have to be a symbol it can also be a string:

Client.all(:conditions => { 'locked' => true })

The good thing about this is that we can pass in a range for our fields without it generating a large query as shown in the preamble of this section.

Client.all(:conditions => { :created_at => (Time.now.midnight - 1.day)..Time.now.midnight})

This will find all clients created yesterday by using a BETWEEN sql statement:

@@ -458,14 +458,14 @@ http://www.gnu.org/software/src-highlite -->

This demonstrates a shorter syntax for the examples in Array Conditions

You can also join in tables and specify their columns in the hash:

Client.all(:include => "orders", :conditions => { 'orders.created_at' => (Time.now.midnight - 1.day)..Time.now.midnight })

An alternative and cleaner syntax to this is:

@@ -473,14 +473,14 @@ http://www.gnu.org/software/src-highlite -->

This will find all clients who have orders that were created yesterday, again using a BETWEEN expression.

If you want to find records using the IN expression you can pass an array to the conditions hash:

Client.all(:include => "orders", :conditions => { :orders_count => [1,3,5] }

This code will generate SQL like this:

@@ -505,27 +505,27 @@ http://www.gnu.org/software/src-highlite -->

If you want to limit the amount of records to a certain subset of all the records retrieved you usually use limit for this, sometimes coupled with offset. Limit is the maximum number of records that will be retrieved from a query, and offset is the number of records it will start reading from from the first record of the set. Take this code for example:

Client.all(:limit => 5)

This code will return a maximum of 5 clients and because it specifies no offset it will return the first 5 clients in the table. The SQL it executes will look like this:

SELECT * FROM clients LIMIT 5

Client.all(:limit => 5, :offset => 5)

This code will return a maximum of 5 clients and because it specifies an offset this time, it will return these records starting from the 5th client in the clients table. The SQL looks like:

@@ -535,7 +535,7 @@ http://www.gnu.org/software/src-highlite -->

The group option for find is useful, for example, if you want to find a collection of the dates orders were created on. You could use the option in this context:

@@ -543,7 +543,7 @@ http://www.gnu.org/software/src-highlite -->

And this will give you a single Order object for each date where there are orders in the database.

The SQL that would be executed would be something like this:

@@ -554,7 +554,7 @@ http://www.gnu.org/software/src-highlite -->

The :having option allows you to specify SQL and acts as a kind of a filter on the group option. :having can only be specified when :group is specified.

An example of using it would be:

@@ -565,14 +565,14 @@ http://www.gnu.org/software/src-highlite -->

readonly is a find option that you can set in order to make that instance of the record read-only. Any attempt to alter or destroy the record will not succeed, raising an ActiveRecord::ReadOnlyRecord exception. To set this option, specify it like this:

Client.first(:readonly => true)

If you assign this record to a variable client, calling the following code will raise an ActiveRecord::ReadOnlyRecord exception:

@@ -584,7 +584,7 @@ client.save

If you’re wanting to stop race conditions for a specific record (for example, you’re incrementing a single field for a record, potentially from multiple simultaneous connections) you can use the lock option to ensure that the record is updated correctly. For safety, you should use this inside a transaction.

@@ -594,7 +594,7 @@ http://www.gnu.org/software/src-highlite --> end

You can also pass SQL to this option to allow different types of locks. For example, MySQL has an expression called LOCK IN SHARE MODE where you can lock a record but still allow other queries to read it. To specify this expression just pass it in as the lock option:

@@ -611,7 +611,7 @@ http://www.gnu.org/software/src-highlite -->

Eager loading is loading associated records along with any number of records in as few queries as possible. For example, if you wanted to load all the addresses associated with all the clients in a single query you could use Client.all(:include => :address). If you wanted to include both the address and mailing address for the client you would use Client.find(:all, :include => [:address, :mailing_address]). Include will first find the client records and then load the associated address records. Running script/server in one window, and executing the code through script/console in another window, the output should look similar to this:

@@ -624,7 +624,7 @@ MailingAddress Load

If you wanted to get all the addresses for a client in the same query you would do Client.all(:joins => :address). If you wanted to find the address and mailing address for that client you would do Client.all(:joins => [:address, :mailing_address]). This is more efficient because it does all the SQL in one query, as shown by this example:

@@ -633,7 +633,7 @@ http://www.gnu.org/software/src-highlite --> mailing_addresses.client_id = client.id

This query is more efficent, but there’s a gotcha: if you have a client who does not have an address or a mailing address they will not be returned in this query at all. If you have any association as an optional association, you may want to use include rather than joins. Alternatively, you can use a SQL join clause to specify exactly the join you need (Rails always assumes an inner join):

@@ -642,7 +642,7 @@ http://www.gnu.org/software/src-highlite --> client.id = mailing_addresses.client_id”)

When using eager loading you can specify conditions for the columns of the tables inside the eager loading to get back a smaller subset. If, for example, you want to find a client and all their orders within the last two weeks you could use eager loading with conditions for this:

@@ -657,7 +657,7 @@ http://www.gnu.org/software/src-highlite -->

If you want to find both by name and locked, you can chain these finders together by simply typing and between the fields for example Client.find_by_name_and_locked("Ryan", true).

There’s another set of dynamic finders that let you find or create/initialize objects if they aren’t found. These work in a similar fashion to the other finders and can be used like find_or_create_by_name(params[:name]). Using this will firstly perform a find and then create if the find returns nil. The SQL looks like this for Client.find_or_create_by_name("Ryan"):

@@ -668,7 +668,7 @@ BEGIN COMMIT

find_or_create's sibling, find_or_initialize, will find an object and if it does not exist will act similar to calling new with the arguments you passed in. For example:

@@ -679,7 +679,7 @@ http://www.gnu.org/software/src-highlite -->

If you’d like to use your own SQL to find records in a table you can use find_by_sql. The find_by_sql method will return an array of objects even the underlying query returns just a single record. For example you could run this query:

@@ -690,7 +690,7 @@ http://www.gnu.org/software/src-highlite -->

find_by_sql has a close relative called connection#select_all. select_all will retrieve objects from the database using custom SQL just like find_by_sql but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record.

@@ -706,7 +706,7 @@ http://www.gnu.org/software/src-highlite -->

16.1. Simple Named Scopes

Suppose we want to find all clients who are male. You could use this code:

@@ -716,7 +716,7 @@ http://www.gnu.org/software/src-highlite -->

Then you could call Client.males.all to get all the clients who are male. Please note that if you do not specify the all on the end you will get a Scope object back, not a set of records which you do get back if you put the all on the end.

If you wanted to find all the clients who are active, you could use this:

@@ -727,14 +727,14 @@ http://www.gnu.org/software/src-highlite -->

16.2. Combining Named Scopes

If you wanted to find all the clients who are active and male you can stack the named scopes like this:

Client.males.active.all

If you would then like to do a all on that scope, you can. Just like an association, named scopes allow you to call all on them:

@@ -742,7 +742,7 @@ http://www.gnu.org/software/src-highlite -->

16.3. Runtime Evaluation of Named Scope Conditions

Consider the following code:

@@ -751,7 +751,7 @@ http://www.gnu.org/software/src-highlite --> end

This looks like a standard named scope that defines a method called recent which gathers all records created any time between now and 2 weeks ago. That’s correct for the first time the model is loaded but for any time after that, 2.weeks.ago is set to that same value, so you will consistently get records from a certain date until your model is reloaded by something like your application restarting. The way to fix this is to put the code in a lambda block:

@@ -762,7 +762,7 @@ http://www.gnu.org/software/src-highlite -->

16.4. Named Scopes with Multiple Models

In a named scope you can use :include and :joins options just like in find.

@@ -774,7 +774,7 @@ http://www.gnu.org/software/src-highlite -->

16.5. Arguments to Named Scopes

If you want to pass to a named scope a required arugment, just specify it as a block argument like this:

@@ -783,7 +783,7 @@ http://www.gnu.org/software/src-highlite --> end

This will work if you call Client.recent(2.weeks.ago).all but not if you call Client.recent. If you want to add an optional argument for this, you have to use prefix the arugment with an *.

@@ -795,7 +795,7 @@ http://www.gnu.org/software/src-highlite -->

16.6. Anonymous Scopes

All Active Record models come with a named scope named scoped, which allows you to create anonymous scopes. For example:

@@ -806,7 +806,7 @@ http://www.gnu.org/software/src-highlite --> end

Anonymous scopes are most useful to create scopes "on the fly":

@@ -817,14 +817,14 @@ http://www.gnu.org/software/src-highlite -->

If you simply want to check for the existence of the object there’s a method called exists?. This method will query the database using the same query as find, but instead of returning an object or collection of objects it will return either true or false+.

Client.exists?(1)

The exists? method also takes multiple ids, but the catch is that it will return true if any one of those records exists.

@@ -833,7 +833,7 @@ http://www.gnu.org/software/src-highlite --> Client.exists?([1,2,3])

Further more, exists takes a conditions option much like find:

@@ -844,28 +844,28 @@ http://www.gnu.org/software/src-highlite -->

This section uses count as an example method in this preamble, but the options described apply to all sub-sections.

count takes conditions much in the same way exists? does:

Client.count(:conditions => "first_name = 'Ryan'")

Which will execute:

SELECT count(*) AS count_all FROM clients WHERE (first_name = 'Ryan')

You can also use :include or :joins for this to do something a little more complex:

Client.count(:conditions => "clients.first_name = 'Ryan' AND orders.status = 'received'", :include => "orders")

Which will execute:

@@ -879,7 +879,7 @@ http://www.gnu.org/software/src-highlite -->

18.2. Average

If you want to see the average of a certain number in one of your tables you can call the average method on the class that relates to the table. This method call will look something like this:

@@ -889,7 +889,7 @@ http://www.gnu.org/software/src-highlite -->

18.3. Minimum

If you want to find the minimum value of a field in your table you can call the minimum method on the class that relates to the table. This method call will look something like this:

@@ -898,7 +898,7 @@ http://www.gnu.org/software/src-highlite -->

18.4. Maximum

If you want to find the maximum value of a field in your table you can call the maximum method on the class that relates to the table. This method call will look something like this:

@@ -907,7 +907,7 @@ http://www.gnu.org/software/src-highlite -->

18.5. Sum

If you want to find the sum of a field for all records in your table you can call the sum method on the class that relates to the table. This method call will look something like this:

diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html index 2153979d7b..be556283c1 100644 --- a/railties/doc/guides/html/activerecord_validations_callbacks.html +++ b/railties/doc/guides/html/activerecord_validations_callbacks.html @@ -236,7 +236,7 @@ Using validation directly in your Active Record classes ensures that only valid

1.2. When Does Validation Happen?

There are two kinds of Active Record objects: those that correspond to a row inside your database and those that do not. When you create a fresh object, using the new method, that object does not belong to the database yet. Once you call save upon that object it will be saved into the appropriate database table. Active Record uses the new_record? instance method to determine whether an object is already in the database or not. Consider the following simple Active Record class:

@@ -274,7 +274,7 @@ http://www.gnu.org/software/src-highlite -->

2.1. The `validates_acceptance_of` helper

Validates that a checkbox on the user interface was checked when a form was submitted. This is normally used when the user needs to agree to your application’s terms of service, confirm reading some text, or any similar concept. This validation is very specific to web applications and actually this acceptance does not need to be recorded anywhere in your database (if you don’t have a field for it, the helper will just create a virtual attribute).

@@ -284,7 +284,7 @@ http://www.gnu.org/software/src-highlite -->

The default error message for validates_acceptance_of is "must be accepted"

validates_acceptance_of can receive an :accept option, which determines the value that will be considered acceptance. It defaults to "1", but you can change this.

@@ -294,7 +294,7 @@ http://www.gnu.org/software/src-highlite -->

2.2. The `validates_associated` helper

You should use this helper when your model has associations with other models and they also need to be validated. When you try to save your object, valid? will be called upon each one of the associated objects.

@@ -315,7 +315,7 @@ http://www.gnu.org/software/src-highlite -->

2.3. The `validates_confirmation_of` helper

You should use this helper when you have two text fields that should receive exactly the same content. For example, you may want to confirm an email address or a password. This validation creates a virtual attribute, using the name of the field that has to be confirmed with _confirmation appended.

@@ -324,7 +324,7 @@ http://www.gnu.org/software/src-highlite --> end

In your view template you could use something like

@@ -339,7 +339,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -351,7 +351,7 @@ http://www.gnu.org/software/src-highlite -->

2.4. The `validates_exclusion_of` helper

This helper validates that the attributes' values are not included in a given set. In fact, this set can be any enumerable object.

@@ -364,7 +364,7 @@ http://www.gnu.org/software/src-highlite -->

2.5. The `validates_format_of` helper

This helper validates the attributes' values by testing whether they match a given pattern. This pattern must be specified using a Ruby regular expression, which is specified using the :with option.

@@ -376,7 +376,7 @@ http://www.gnu.org/software/src-highlite -->

2.6. The `validates_inclusion_of` helper

This helper validates that the attributes' values are included in a given set. In fact, this set can be any enumerable object.

@@ -389,7 +389,7 @@ http://www.gnu.org/software/src-highlite -->

2.7. The `validates_length_of` helper

This helper validates the length of your attribute’s value. It includes a variety of different options, so you can specify length constraints in different ways:

@@ -424,7 +424,7 @@ http://www.gnu.org/software/src-highlite -->

The default error messages depend on the type of length validation being performed. You can personalize these messages, using the :wrong_length, :too_long and :too_short options and the %d format mask as a placeholder for the number corresponding to the length constraint being used. You can still use the :message option to specify an error message.

@@ -436,7 +436,7 @@ http://www.gnu.org/software/src-highlite -->

This helper validates that your attributes have only numeric values. By default, it will match an optional sign followed by a integral or floating point number. Using the :integer_only option set to true, you can specify that only integral numbers are allowed.

If you set :integer_only to true, then it will use the $$/\A[\-]?\d+\Z/ regular expression to validate the attribute’s value. Otherwise, it will try to convert the value to a number using +Kernel.Float.

@@ -486,7 +486,7 @@ http://www.gnu.org/software/src-highlite -->

2.9. The `validates_presence_of` helper

This helper validates that the specified attributes are not empty. It uses the blank? method to check if the value is either nil or an empty string (if the string has only spaces, it will still be considered empty).

@@ -502,7 +502,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -522,7 +522,7 @@ http://www.gnu.org/software/src-highlite -->

2.10. The `validates_uniqueness_of` helper

This helper validates that the attribute’s value is unique right before the object gets saved. It does not create a uniqueness constraint directly into your database, so it may happen that two different database connections create two records with the same value for a column that you intend to be unique. To avoid that, you must create an unique index in your database.

@@ -532,7 +532,7 @@ http://www.gnu.org/software/src-highlite -->

The validation happens by performing a SQL query into the model’s table, searching for a record where the attribute that must be validated is equal to the value in the object being validated.

There is a :scope option that you can use to specify other attributes that are used to limit the uniqueness check:

@@ -542,7 +542,7 @@ http://www.gnu.org/software/src-highlite --> end

There is also a :case_sensitive option that you can use to define whether the uniqueness constraint will be case sensitive or not. This option defaults to true.

@@ -553,7 +553,7 @@ http://www.gnu.org/software/src-highlite -->

2.11. The `validates_each` helper

This helper validates attributes against a block. It doesn’t have a predefined validation function. You should create one using a block, and every attribute passed to validates_each will be tested against it. In the following example, we don’t want names and surnames to begin with lower case.

@@ -570,7 +570,7 @@ http://www.gnu.org/software/src-highlite -->

3.1. The `:allow_nil` option

The :allow_nil option skips the validation when the value being validated is nil. You may be asking yourself if it makes any sense to use :allow_nil and validates_presence_of together. Well, it does. Remember, the validation will be skipped only for nil attributes, but empty strings are not considered nil.

@@ -581,7 +581,7 @@ http://www.gnu.org/software/src-highlite -->

3.2. The `:allow_blank` option

The :allow_blank: option is similar to the +:allow_nil option. This option will let validation pass if the attribute’s value is nil or an empty string, i.e., any value that returns true for blank?.

@@ -596,7 +596,7 @@ Topic.create(3.4. The :on option

The :on option lets you specify when the validation should happen. The default behavior for all the built-in validation helpers is to be ran on save (both when you’re creating a new record and when you’re updating it). If you want to change it, you can use :on => :create to run the validation only when a new record is created or :on => :update to run the validation only when a record is updated.

@@ -617,7 +617,7 @@ http://www.gnu.org/software/src-highlite -->

4.1. Using a symbol with the `:if` and `:unless` options

You can associate the :if and :unless options with a symbol corresponding to the name of a method that will get called right before validation happens. This is the most commonly used option.

@@ -631,7 +631,7 @@ http://www.gnu.org/software/src-highlite -->

4.2. Using a string with the `:if` and `:unless` options

You can also use a string that will be evaluated using :eval and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition.

@@ -641,7 +641,7 @@ http://www.gnu.org/software/src-highlite -->

4.3. Using a Proc object with the `:if` and :`unless` options

Finally, it’s possible to associate :if and :unless with a Ruby Proc object which will be called. Using a Proc object can give you the hability to write a condition that will be executed only when the validation happens and not when your code is loaded by the Ruby interpreter. This option is best suited when writing short validation methods, usually one-liners.

@@ -654,7 +654,7 @@ http://www.gnu.org/software/src-highlite -->

When the built-in validation helpers are not enough for your needs, you can write your own validation methods. You can do that by implementing methods that verify the state of your models and add messages to their errors collection when they are invalid. You must then register those methods by using one or more of the validate, validate_on_create or validate_on_update class methods, passing in the symbols for the validation methods' names. You can pass more than one symbol for each class method and the respective validations will be ran in the same order as they were registered.

@@ -674,7 +674,7 @@ http://www.gnu.org/software/src-highlite --> end

You can even create your own validation helpers and reuse them in several different models. Here is an example where we create a custom validation helper to validate the format of fields that represent email addresses:

@@ -692,7 +692,7 @@ http://www.gnu.org/software/src-highlite --> end

The recipe is simple: just create a new validation method inside the ActiveRecord::Validations::ClassMethods module. You can put this code in a file inside your application’s lib folder, and then requiring it from your environment.rb or any other file inside config/initializers. You can use this helper like this:

@@ -711,7 +711,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -728,7 +728,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -745,7 +745,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -763,7 +763,7 @@ person.invalid?

@@ -793,7 +793,7 @@ person.errors.<

@@ -817,7 +817,7 @@ p.errors.

Rails provides built-in helpers to display the error messages of your models in your view templates. When creating a form with the form_for helper, you can use the error_messages method on the form builder to render all failed validation messages for the current model instance.

@@ -898,7 +898,7 @@ http://www.gnu.org/software/src-highlite -->

7.1. Changing the way form fields with errors are displayed

By default, form fields with errors are displayed enclosed by a div element with the fieldWithErrors CSS class. However, we can write some Ruby code to override the way Rails treats those fields by default. Here is a simple example where we change the Rails behaviour to always display the error messages in front of each of the form fields with errors. The error messages will be enclosed by a span element with a validation-error CSS class. There will be no div element enclosing the input element, so we get rid of that red border around the text field. You can use the validation-error CSS class to style it anyway you want.

@@ -937,7 +937,7 @@ An object of the ActionView::Helpers::InstanceTag class.

8.1. Callbacks registration

In order to use the available callbacks, you need to registrate them. You can do that by implementing them as an ordinary methods, and then using a macro-style class method to register then as callbacks.

@@ -955,7 +955,7 @@ http://www.gnu.org/software/src-highlite --> end

The macro-style class methods can also receive a block. Rails best practices say that you should only use this style of registration if the code inside your block is so short that it fits in just one line.

@@ -979,7 +979,7 @@ http://www.gnu.org/software/src-highlite -->

9.1. Using a symbol with the `:if` and `:unless` options

You can associate the :if and :unless options with a symbol corresponding to the name of a method that will get called right before the callback. If this method returns false the callback won’t be executed. This is the most common option. Using this form of registration it’s also possible to register several different methods that should be called to check the if the callback should be executed.

@@ -989,7 +989,7 @@ http://www.gnu.org/software/src-highlite -->

9.2. Using a string with the `:if` and `:unless` options

You can also use a string that will be evaluated using :eval and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition.

@@ -999,7 +999,7 @@ http://www.gnu.org/software/src-highlite -->

9.3. Using a Proc object with the `:if` and :`unless` options

Finally, it’s possible to associate :if and :unless with a Ruby Proc object. This option is best suited when writing short validation methods, usually one-liners.

@@ -1010,7 +1010,7 @@ http://www.gnu.org/software/src-highlite -->

9.4. Multiple Conditions for Callbacks

When writing conditional callbacks, it’s possible to mix both :if and :unless in the same callback declaration.

@@ -1139,7 +1139,7 @@ http://www.gnu.org/software/src-highlite -->

Sometimes the callback methods that you’ll write will be useful enough to be reused at other models. Active Record makes it possible to create classes that encapsulate the callback methods, so it becomes very easy to reuse them.

Here’s an example where we create a class with a after_destroy callback for a PictureFile model.

@@ -1150,7 +1150,7 @@ http://www.gnu.org/software/src-highlite --> end

When declared inside a class the callback method will receive the model object as a parameter. We can now use it this way:

@@ -1159,7 +1159,7 @@ http://www.gnu.org/software/src-highlite --> end

Note that we needed to instantiate a new PictureFileCallbacks object, since we declared our callback as an instance method. Sometimes it will make more sense to have it as a class method.

@@ -1170,7 +1170,7 @@ http://www.gnu.org/software/src-highlite --> end

If the callback method is declared this way, it won’t be necessary to instantiate a PictureFileCallbacks object.

@@ -1186,7 +1186,7 @@ http://www.gnu.org/software/src-highlite -->

Observer classes are subclasses of the ActiveRecord::Observer class. When this class is subclassed, Active Record will look at the name of the new class and then strip the Observer part to find the name of the Active Record class to observe.

Consider a Registration model, where we want to send an email every time a new registration is created. Since sending emails is not directly related to our model’s purpose, we could create an Observer to do just that:

@@ -1198,7 +1198,7 @@ http://www.gnu.org/software/src-highlite -->

Like in callback classes, the observer’s methods receive the observed model as a parameter.

Sometimes using the ModelName + Observer naming convention won’t be the best choice, mainly when you want to use the same observer for more than one model class. It’s possible to explicity specify the models that our observer should observe.

@@ -1208,7 +1208,7 @@ http://www.gnu.org/software/src-highlite -->

13.1. Registering observers

If you paid attention, you may be wondering where Active Record Observers are referenced in our applications, so they get instantiated and begin to interact with our models. For observers to work we need to register them somewhere. The usual place to do that is in our application’s config/environment.rb file. In this file there is a commented-out line where we can define the observers that our application should load at start-up.

diff --git a/railties/doc/guides/html/association_basics.html b/railties/doc/guides/html/association_basics.html index 8d03bdddba..bfe8f3f341 100644 --- a/railties/doc/guides/html/association_basics.html +++ b/railties/doc/guides/html/association_basics.html @@ -125,7 +125,7 @@ Use the methods added to your models by creating associations

Why do we need associations between models? Because they make common operations simpler and easier in your code. For example, consider a simple Rails application that includes a model for customers and a model for orders. Each customer can have many orders. Without associations, the model declarations would look like this:

@@ -136,14 +136,14 @@ http://www.gnu.org/software/src-highlite --> end

Now, suppose we wanted to add a new order for an existing customer. We’d need to do something like this:

@order = Order.create(:order_date => Time.now, :customer_id => @customer.id)

Or consider deleting a customer, and ensuring that all of its orders get deleted as well:

@@ -154,7 +154,7 @@ http://www.gnu.org/software/src-highlite --> @customer.destroy

With Active Record associations, we can streamline these - and other - operations by declaratively telling Rails that there is a connection between the two models. Here’s the revised code for setting up customers and orders:

@@ -167,14 +167,14 @@ http://www.gnu.org/software/src-highlite --> end

With this change, creating a new order for a particular customer is easier:

@order = @customer.orders.create(:order_date => Time.now)

Deleting a customer and all of its orders is much easier:

@@ -220,7 +220,7 @@ http://www.gnu.org/software/src-highlite -->

2.1. The `belongs_to` Association

A belongs_to association sets up a one-to-one connection with another model, such that each instance of the declaring model "belongs to" one instance of the other model. For example, if your application includes customers and orders, and each order can be assigned to exactly one customer, you’d declare the order model this way:

@@ -233,7 +233,7 @@ http://www.gnu.org/software/src-highlite -->

2.2. The `has_one` Association

A has_one association also sets up a one-to-one connection with another model, but with somewhat different semantics (and consequences). This association indicates that each instance of a model contains or possesses one instance of another model. For example, if each supplier in your application has only one account, you’d declare the supplier model like this:

@@ -246,7 +246,7 @@ http://www.gnu.org/software/src-highlite -->

2.3. The `has_many` Association

A has_many association indicates a one-to-many connection with another model. You’ll often find this association on the "other side" of a belongs_to association. This association indicates that each instance of the model has zero or more instances of another model. For example, in an application containing customers and orders, the customer model could be declared like this:

@@ -267,7 +267,7 @@ http://www.gnu.org/software/src-highlite -->

2.4. The `has_many :through` Association

A has_many :through association is often used to set up a many-to-many connection with another model. This association indicates that the declaring model can be matched with zero or more instances of another model by proceeding through a third model. For example, consider a medical practice where patients make appointments to see physicians. The relevant association declarations could look like this:

@@ -290,7 +290,7 @@ http://www.gnu.org/software/src-highlite -->

The has_many :through association is also useful for setting up "shortcuts" through nested :has_many associations. For example, if a document has many sections, and a section has many paragraphs, you may sometimes want to get a simple collection of all paragraphs in the document. You could set that up this way:

@@ -310,7 +310,7 @@ http://www.gnu.org/software/src-highlite -->

2.5. The `has_one :through` Association

A has_one :through association sets up a one-to-one connection with another model. This association indicates that the declaring model can be matched with one instance of another model by proceeding through a third model. For example, if each supplier has one account, and each account is associated with one account history, then the customer model could look like this:

@@ -333,7 +333,7 @@ http://www.gnu.org/software/src-highlite -->

2.6. The `has_and_belongs_to_many` Association

A has_and_belongs_to_many association creates a direct many-to-many connection with another model, with no intervening model. For example, if your application includes assemblies and parts, with each assembly having many parts and each part appearing in many assemblies, you could declare the models this way:

@@ -351,7 +351,7 @@ http://www.gnu.org/software/src-highlite -->

If you want to set up a 1-1 relationship between two models, you’ll need to add belongs_to to one, and has_one to the other. How do you know which is which?

The distinction is in where you place the foreign key (it goes on the table for the class declaring the belongs_to association), but you should give some thought to the actual meaning of the data as well. The has_one relationship says that one of something is yours - that is, that something points back to you. For example, it makes more sense to say that a supplier owns an account than that an account owns a supplier. This suggests that the correct relationships are like this:

@@ -364,7 +364,7 @@ http://www.gnu.org/software/src-highlite --> end

The corresponding migration might look like this:

@@ -398,7 +398,7 @@ http://www.gnu.org/software/src-highlite -->

2.8. Choosing Between `has_many :through` and `has_and_belongs_to_many`

Rails offers two different ways to declare a many-to-many relationship between models. The simpler way is to use has_and_belongs_to_many, which allows you to make the association directly:

@@ -411,7 +411,7 @@ http://www.gnu.org/software/src-highlite --> end

The second way to declare a many-to-many relationship is to use has_many :through. This makes the association indirectly, through a join model:

@@ -434,7 +434,7 @@ http://www.gnu.org/software/src-highlite -->

2.9. Polymorphic Associations

A slightly more advanced twist on associations is the polymorphic association. With polymorphic associations, a model can belong to more than one other model, on a single association. For example, you might have a picture model that belongs to either an employee model or a product model. Here’s how this could be declared:

@@ -451,7 +451,7 @@ http://www.gnu.org/software/src-highlite --> end

You can think of a polymorphic belongs_to declaration as setting up an interface that any other model can use. From an instance of the Employee model, you can retrieve a collection of pictures: @employee.pictures. Similarly, you can retrieve @product.pictures. If you have an instance of the Picture model, you can get to its parent via @picture.imageable. To make this work, you need to declare both a foreign key column and a type column in the model that declares the polymorphic interface:

@@ -471,7 +471,7 @@ http://www.gnu.org/software/src-highlite --> end

This migration can be simplified by using the t.references form:

@@ -494,7 +494,7 @@ http://www.gnu.org/software/src-highlite -->

2.10. Self Joins

In designing a data model, you will sometimes find a model that should have a relation to itself. For example, you may want to store all employees in a single database model, but be able to trace relationships such as manager and subordinates. This situation can be modeled with self-joining associations:

@@ -532,7 +532,7 @@ Controlling association scope

3.1. Controlling Caching

All of the association methods are built around caching that keeps the result of the most recent query available for further operations. The cache is even shared across methods. For example:

@@ -541,7 +541,7 @@ customer.orders customer.orders.empty? # uses the cached copy of orders

But what if you want to reload the cache, because data might have been changed by some other part of the application? Just pass true to the association call:

@@ -555,7 +555,7 @@ customer.orders

3.3.1. Creating Foreign Keys for `belongs_to` Associations

When you declare a belongs_to association, you need to create foreign keys as appropriate. For example, consider this model:

@@ -564,7 +564,7 @@ http://www.gnu.org/software/src-highlite --> end

This declaration needs to be backed up by the proper foreign key declaration on the orders table:

@@ -594,7 +594,7 @@ http://www.gnu.org/software/src-highlite -->

Whatever the name, you must manually generate the join table with an appropriate migration. For example, consider these associations:

@@ -607,7 +607,7 @@ http://www.gnu.org/software/src-highlite --> end

These need to be backed up by a migration to create the assemblies_parts table. This table should be created without a primary key:

@@ -626,7 +626,7 @@ http://www.gnu.org/software/src-highlite -->

3.4. Controlling Association Scope

By default, associations look for objects only within the current module’s scope. This can be important when you declare Active Record models within a module. For example:

@@ -643,7 +643,7 @@ http://www.gnu.org/software/src-highlite --> end

This will work fine, because both the Supplier and the Account class are defined within the same scope. But this will not work, because Supplier and Account are defined in different scopes:

@@ -662,7 +662,7 @@ http://www.gnu.org/software/src-highlite --> end

To associate a model with a model in a different scope, you must specify the complete class name in your association declaration:

@@ -716,7 +716,7 @@ http://www.gnu.org/software/src-highlite -->

In all of these methods, association is replaced with the symbol passed as the first argument to belongs_to. For example, given the declaration:

@@ -725,7 +725,7 @@ http://www.gnu.org/software/src-highlite --> end

Each instance of the order model will have these methods:

@@ -737,7 +737,7 @@ create_customer

`association(force_reload = false)`

The association method returns the associated object, if any. If no associated object is found, it returns nil.

@@ -746,7 +746,7 @@ http://www.gnu.org/software/src-highlite -->

`association=(associate)`

The association= method assigns an associated object to this object. Behind the scenes, this means extracting the primary key from the associate object and setting this object’s foreign key to the same value.

@@ -754,7 +754,7 @@ http://www.gnu.org/software/src-highlite -->

`association.nil?`

The association.nil? method returns true if there is no associated object.

@@ -764,7 +764,7 @@ http://www.gnu.org/software/src-highlite -->

`build_association(attributes = {})`

The build_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object’s foreign key will be set, but the associated object will not yet be saved.

@@ -772,7 +772,7 @@ http://www.gnu.org/software/src-highlite -->

`create_association(attributes = {})`

The create_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object’s foreign key will be set. In addition, the associated object will be saved (assuming that it passes any validations).

@@ -780,7 +780,7 @@ http://www.gnu.org/software/src-highlite -->

4.1.2. Options for `belongs_to`

In many situations, you can use the default behavior of belongs_to without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a belongs_to association. For example, an association with several options might look like this:

@@ -843,7 +843,7 @@ http://www.gnu.org/software/src-highlite -->

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if an order belongs to a customer, but the actual name of the model containing customers is Patron, you’d set things up this way:

@@ -853,7 +853,7 @@ http://www.gnu.org/software/src-highlite -->

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

@@ -863,7 +863,7 @@ http://www.gnu.org/software/src-highlite -->

`:counter_cache`

The :counter_cache option can be used to make finding the number of belonging objects more efficient. Consider these models:

@@ -875,7 +875,7 @@ http://www.gnu.org/software/src-highlite --> end

With these declarations, asking for the value of @customer.orders.size requires making a call to the database to perform a COUNT(*) query. To avoid this call, you can add a counter cache to the belonging model:

@@ -888,7 +888,7 @@ http://www.gnu.org/software/src-highlite -->

With this declaration, Rails will keep the cache value up to date, and then return that value in response to the .size method.

Although the :counter_cache option is specified on the model that includes the belongs_to declaration, the actual column must be added to the associated model. In the case above, you would need to add a column named orders_count to the Customer model. You can override the default column name if you need to:

@@ -912,7 +912,7 @@ http://www.gnu.org/software/src-highlite -->

`:foreign_key`

By convention, Rails guesses that the column used to hold the foreign key on this model is the name of the association with the suffix _id added. The :foreign_key option lets you set the name of the foreign key directly:

@@ -930,7 +930,7 @@ http://www.gnu.org/software/src-highlite -->

`:include`

You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:

@@ -946,7 +946,7 @@ http://www.gnu.org/software/src-highlite --> end

If you frequently retrieve customers directly from line items (@line_item.order.customer), then you can make your code somewhat more efficient by including customers in the association from line items to orders:

@@ -1019,7 +1019,7 @@ http://www.gnu.org/software/src-highlite -->

In all of these methods, association is replaced with the symbol passed as the first argument to has_one. For example, given the declaration:

@@ -1028,7 +1028,7 @@ http://www.gnu.org/software/src-highlite --> end

Each instance of the Supplier model will have these methods:

@@ -1040,7 +1040,7 @@ create_account

`association(force_reload = false)`

The association method returns the associated object, if any. If no associated object is found, it returns nil.

@@ -1049,7 +1049,7 @@ http://www.gnu.org/software/src-highlite -->

`association=(associate)`

The association= method assigns an associated object to this object. Behind the scenes, this means extracting the primary key from this object and setting the associate object’s foreign key to the same value.

@@ -1057,7 +1057,7 @@ http://www.gnu.org/software/src-highlite -->

`association.nil?`

The association.nil? method returns true if there is no associated object.

@@ -1067,7 +1067,7 @@ http://www.gnu.org/software/src-highlite -->

`build_association(attributes = {})`

The build_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set, but the associated object will not yet be saved.

@@ -1075,7 +1075,7 @@ http://www.gnu.org/software/src-highlite -->

`create_association(attributes = {})`

The create_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set. In addition, the associated object will be saved (assuming that it passes any validations).

@@ -1083,7 +1083,7 @@ http://www.gnu.org/software/src-highlite -->

4.2.2. Options for `has_one`

In many situations, you can use the default behavior of has_one without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a has_one association. For example, an association with several options might look like this:

@@ -1168,7 +1168,7 @@ http://www.gnu.org/software/src-highlite -->

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if a supplier has an account, but the actual name of the model containing accounts is Billing, you’d set things up this way:

@@ -1178,7 +1178,7 @@ http://www.gnu.org/software/src-highlite -->

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

@@ -1190,7 +1190,7 @@ http://www.gnu.org/software/src-highlite -->

`:foreign_key`

By convention, Rails guesses that the column used to hold the foreign key on the other model is the name of this model with the suffix _id added. The :foreign_key option lets you set the name of the foreign key directly:

@@ -1208,7 +1208,7 @@ http://www.gnu.org/software/src-highlite -->

`:include`

You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:

@@ -1224,7 +1224,7 @@ http://www.gnu.org/software/src-highlite --> end

If you frequently retrieve representatives directly from suppliers (@supplier.account.representative), then you can make your code somewhat more efficient by including representatives in the association from suppliers to accounts:

@@ -1332,7 +1332,7 @@ http://www.gnu.org/software/src-highlite -->

In all of these methods, collection is replaced with the symbol passed as the first argument to has_many, and collection\_singular is replaced with the singularized version of that symbol.. For example, given the declaration:

@@ -1341,7 +1341,7 @@ http://www.gnu.org/software/src-highlite --> end

Each instance of the customer model will have these methods:

@@ -1361,7 +1361,7 @@ orders.create(<

`collection(force_reload = false)`

The collection method returns an array of all of the associated objects. If there are no associated objects, it returns an empty array.

@@ -1369,7 +1369,7 @@ http://www.gnu.org/software/src-highlite -->

`collection<<(object, ...)`

The collection<< method adds one or more objects to the collection by setting their foreign keys to the primary key of the calling model.

@@ -1377,7 +1377,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.delete(object, ...)`

The collection.delete method removes one or more objects from the collection by setting their foreign keys to NULL.

@@ -1395,7 +1395,7 @@ http://www.gnu.org/software/src-highlite -->

`collection\_singular\_ids`

The collection\_singular\_ids method returns an array of the ids of the objects in the collection.

@@ -1407,7 +1407,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.empty?`

The collection.empty? method returns true if the collection does not contain any associated objects.

@@ -1417,7 +1417,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.size`

The collection.size method returns the number of objects in the collection.

@@ -1425,7 +1425,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.find(...)`

The collection.find method finds objects within the collection. It uses the same syntax and options as ActiveRecord::Base.find.

@@ -1435,7 +1435,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.build(attributes = {}, ...)`

The collection.build method returns one or more new objects of the associated type. These objects will be instantiated from the passed attributes, and the link through their foreign key will be created, but the associated objects will not yet be saved.

@@ -1443,7 +1443,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.create(attributes = {})`

The collection.create method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be created, and the associated object will be saved (assuming that it passes any validations).

@@ -1451,7 +1451,7 @@ http://www.gnu.org/software/src-highlite -->

4.3.2. Options for has_many

In many situations, you can use the default behavior for has_many without any customization. But you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a has_many association. For example, an association with several options might look like this:

@@ -1571,7 +1571,7 @@ http://www.gnu.org/software/src-highlite -->

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if a customer has many orders, but the actual name of the model containing orders is Transaction, you’d set things up this way:

@@ -1581,7 +1581,7 @@ http://www.gnu.org/software/src-highlite -->

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

@@ -1590,7 +1590,7 @@ http://www.gnu.org/software/src-highlite --> end

You can also set conditions via a hash:

@@ -1625,7 +1625,7 @@ http://www.gnu.org/software/src-highlite -->

`:foreign_key`

@@ -1643,7 +1643,7 @@ http://www.gnu.org/software/src-highlite -->

`:group`

The :group option supplies an attribute name to group the result set by, using a GROUP BY clause in the finder SQL.

@@ -1653,7 +1653,7 @@ http://www.gnu.org/software/src-highlite -->

`:include`

You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:

@@ -1669,7 +1669,7 @@ http://www.gnu.org/software/src-highlite --> end

If you frequently retrieve line items directly from customers (@customer.orders.line_items), then you can make your code somewhat more efficient by including line items in the association from customers to orders:

@@ -1686,7 +1686,7 @@ http://www.gnu.org/software/src-highlite -->

`:limit`

The :limit option lets you restrict the total number of objects that will be fetched through an association.

@@ -1698,7 +1698,7 @@ http://www.gnu.org/software/src-highlite -->

`:order`

The :order option dictates the order in which associated objects will be received (in the syntax used by a SQL ORDER BY clause).

@@ -1807,7 +1807,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -1816,7 +1816,7 @@ http://www.gnu.org/software/src-highlite --> end

Each instance of the part model will have these methods:

@@ -1846,7 +1846,7 @@ assemblies.createcollection(force_reload = false)

The collection method returns an array of all of the associated objects. If there are no associated objects, it returns an empty array.

@@ -1854,7 +1854,7 @@ http://www.gnu.org/software/src-highlite -->

`collection<<(object, ...)`

The collection<< method adds one or more objects to the collection by creating records in the join table.

@@ -1870,7 +1870,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.delete(object, ...)`

The collection.delete method removes one or more objects from the collection by deleting records in the join table. This does not destroy the objects.

@@ -1881,7 +1881,7 @@ http://www.gnu.org/software/src-highlite -->

# Returns an array of the associated objects' ids

The collection\_singular\_ids method returns an array of the ids of the objects in the collection.

@@ -1893,7 +1893,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.empty?`

The collection.empty? method returns true if the collection does not contain any associated objects.

@@ -1903,7 +1903,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.size`

The collection.size method returns the number of objects in the collection.

@@ -1911,7 +1911,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.find(...)`

The collection.find method finds objects within the collection. It uses the same syntax and options as ActiveRecord::Base.find. It also adds the additional condition that the object must be in the collection.

@@ -1921,7 +1921,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.build(attributes = {})`

The collection.build method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through the join table will be created, but the associated object will not yet be saved.

@@ -1929,7 +1929,7 @@ http://www.gnu.org/software/src-highlite -->

`collection.create(attributes = {})`

The collection.create method returns a new object of the associated type. This objects will be instantiated from the passed attributes, the link through the join table will be created, and the associated object will be saved (assuming that it passes any validations).

@@ -1937,7 +1937,7 @@ http://www.gnu.org/software/src-highlite -->

4.4.2. Options for has_and_belongs_to_many

In many situations, you can use the default behavior for has_and_belongs_to_many without any customization. But you can alter that behavior in a number of ways. This section cover the options that you can pass when you create a has_and_belongs_to_many association. For example, an association with several options might look like this:

@@ -2053,7 +2053,7 @@ http://www.gnu.org/software/src-highlite -->

@@ -2064,7 +2064,7 @@ http://www.gnu.org/software/src-highlite -->

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if a part has many assemblies, but the actual name of the model containing assemblies is Gadget, you’d set things up this way:

@@ -2074,7 +2074,7 @@ http://www.gnu.org/software/src-highlite -->

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

@@ -2083,7 +2083,7 @@ http://www.gnu.org/software/src-highlite --> end

You can also set conditions via a hash:

@@ -2110,7 +2110,7 @@ http://www.gnu.org/software/src-highlite -->

`:foreign_key`

By convention, Rails guesses that the column in the join table used to hold the foreign key pointing to this model is the name of this model with the suffix _id added. The :foreign_key option lets you set the name of the foreign key directly:

@@ -2121,7 +2121,7 @@ http://www.gnu.org/software/src-highlite -->

`:group`

The :group option supplies an attribute name to group the result set by, using a GROUP BY clause in the finder SQL.

@@ -2137,7 +2137,7 @@ http://www.gnu.org/software/src-highlite -->

`:limit`

The :limit option lets you restrict the total number of objects that will be fetched through an association.

@@ -2149,7 +2149,7 @@ http://www.gnu.org/software/src-highlite -->

`:order`

The :order option dictates the order in which associated objects will be received (in the syntax used by a SQL ORDER BY clause).

@@ -2196,7 +2196,7 @@ http://www.gnu.org/software/src-highlite -->

You define association callbacks by adding options to the association declaration. For example:

@@ -2210,7 +2210,7 @@ http://www.gnu.org/software/src-highlite -->

Rails passes the object being added or removed to the callback.

You can stack callbacks on a single event by passing them as an array:

@@ -2229,7 +2229,7 @@ http://www.gnu.org/software/src-highlite -->

4.6. Association Extensions

You’re not limited to the functionality that Rails automatically builds into association proxy objects. You can also extend these objects through anonymous modules, adding new finders, creators, or other methods. For example:

@@ -2242,7 +2242,7 @@ http://www.gnu.org/software/src-highlite --> end

If you have an extension that should be shared by many associations, you can use a named extension module. For example:

@@ -2261,7 +2261,7 @@ http://www.gnu.org/software/src-highlite --> end

To include more than one extension module in a single association, specify an array of names:

diff --git a/railties/doc/guides/html/caching_with_rails.html b/railties/doc/guides/html/caching_with_rails.html index 04498f268f..02cc981b0e 100644 --- a/railties/doc/guides/html/caching_with_rails.html +++ b/railties/doc/guides/html/caching_with_rails.html @@ -75,7 +75,7 @@ to true for your environment. This flag is normally set in the corresponding config/environments/*.rb and caching is disabled by default there for development and test, and enabled for production.

@@ -91,7 +91,7 @@ expiration is an issue that needs to be dealt with.

have a controller called ProductsController and a list action that lists all the products

@@ -119,7 +119,7 @@ configuration setting config.action_controller.page_cache_extension.

In order to expire this page when a new product is added we could extend our example controler like this:

@@ -148,7 +148,7 @@ result of the output from a cached copy.

Let’s say you only wanted authenticated users to edit or create a Product object, but still cache those pages:

@@ -191,7 +191,7 @@ in real time and didn’t want to cache that part of the page, but did want to cache the part of the page which lists all products available, you could use this piece of code:

@@ -209,7 +209,7 @@ http://www.gnu.org/software/src-highlite --> written out to the same place as the Action Cache, which means that if you want to cache multiple fragments per action, you should provide an action_suffix to the cache call:

@@ -217,7 +217,7 @@ http://www.gnu.org/software/src-highlite --> All available products:

and you can expire it using the expire_fragment method, like so:

@@ -226,7 +226,7 @@ http://www.gnu.org/software/src-highlite --> also use globally keyed fragments by calling the cache method with a key, like so:

@@ -235,7 +235,7 @@ http://www.gnu.org/software/src-highlite -->

This fragment is then available to all actions in the ProductsController using the key and can be expired the same way:

@@ -250,7 +250,7 @@ an around or after filter.

Continuing with our Product controller example, we could rewrite it with a sweeper such as the following:

@@ -286,7 +286,7 @@ actions are called. So, if we wanted to expire the cached content for the list and edit actions when the create action was called, we could do the following:

@@ -314,7 +314,7 @@ will used the cached result set as opposed to running the query against the database again.

For example:

@@ -360,7 +360,7 @@ caches. Page caches are always stored on disk.

take up a lot of memory since each process keeps all the caches in memory.

@@ -371,7 +371,7 @@ http://www.gnu.org/software/src-highlite --> running from the same application directory to access the cached content.

@@ -381,7 +381,7 @@ http://www.gnu.org/software/src-highlite --> only keeps one cache around for all processes, but requires that you run and manage a separate DRb process.

@@ -389,14 +389,14 @@ http://www.gnu.org/software/src-highlite -->

4) MemCached store: Works like DRbStore, but uses Danga’s MemCache instead. Rails uses the bundled memcached-client gem by default.

ActionController::Base.cache_store = :mem_cache_store, "localhost"

5) Custom store: You can define your own cache store (new in Rails 2.1)

@@ -421,7 +421,7 @@ timestamp and the if-none-match header and determine whether or not to send back the full response. With conditional-get support in rails this is a pretty easy task:

@@ -447,7 +447,7 @@ http://www.gnu.org/software/src-highlite --> rendering mechanism (i.e. you’re not using respond_to or calling render yourself) then you’ve got an easy helper in fresh_when:

diff --git a/railties/doc/guides/html/command_line.html b/railties/doc/guides/html/command_line.html index 7f925bc10a..226a68e105 100644 --- a/railties/doc/guides/html/command_line.html +++ b/railties/doc/guides/html/command_line.html @@ -135,7 +135,7 @@ rails

@@ -171,7 +171,7 @@ http://www.gnu.org/software/src-highlite -->

Here we’ll flex our server command, which without any prodding of any kind will run our new shiny Rails app:

@@ -188,7 +188,7 @@ $ ./script/server

1.3. generate

The generate command uses templates to create a whole lot of things. You can always find out what’s available by running generate by itself. Let’s do that:

@@ -222,7 +222,7 @@ Installed Generators

@@ -251,7 +251,7 @@ Modules Example: Test: test/functional/admin/credit_card_controller_test.rb

Ah, the controller generator is expecting parameters in the form of generate controller ControllerName action1 action2. Let’s make a Greetings controller with an action of hello, which will say something nice to us.

@@ -267,7 +267,7 @@ http://www.gnu.org/software/src-highlite -->

Look there! Now what all did this generate? It looks like it made sure a bunch of directories were in our application, and created a controller file, a functional test file, a helper for the view, and a view file.

Let’s check out the controller and modify it a little (in app/controllers/greeting_controller.rb):

@@ -279,7 +279,7 @@ http://www.gnu.org/software/src-highlite --> end

Then the view, to display our nice message (in app/views/greeting/hello.html.erb):

@@ -287,7 +287,7 @@ http://www.gnu.org/software/src-highlite --> <p><%= @message %></p>

Deal. Go check it out in your browser. Fire up your server. Remember? ./script/server at the root of your Rails application should do it.

@@ -304,7 +304,7 @@ http://www.gnu.org/software/src-highlite -->

"What about data, though?", you ask over a cup of coffee. Rails comes with a generator for data models too. Can you guess its generator name?

@@ -328,7 +328,7 @@ Examples:

But instead of generating a model directly (which we’ll be doing later), let’s set up a scaffold. A scaffold in Rails is a full set of model, database migration for that model, controller to manipulate it, views to view and manipulate the data, and a test suite for each of the above.

Let’s set up a simple resource called "HighScore" that will keep track of our highest score on video games we play.

@@ -371,7 +371,7 @@ dependency model

@@ -400,7 +400,7 @@ http://www.gnu.org/software/src-highlite -->

Let’s say you’re creating a website for a client who wants a small accounting system. Every event having to do with money must be logged, and must never be deleted. Wouldn’t it be great if we could override the behavior of a model to never actually take its record out of the database, but instead, just set a field?

There is such a thing! The plugin we’re installing is called "acts_as_paranoid", and it lets models implement a "deleted_at" column that gets set when you call destroy. Later, when calling find, the plugin will tack on a database check to filter out "deleted" things.

@@ -412,7 +412,7 @@ http://www.gnu.org/software/src-highlite -->

1.7. runner

runner runs Ruby code in the context of Rails non-interactively. For instance:

@@ -420,7 +420,7 @@ http://www.gnu.org/software/src-highlite -->

1.8. destroy

Think of destroy as the opposite of generate. It’ll figure out what generate did, and undo it. Believe you-me, the creation of this tutorial used this command many times!

@@ -449,7 +449,7 @@ $ ./script/destroy model Oops

1.9. about

Check it: Version numbers for Ruby, RubyGems, Rails, the Rails subcomponents, your application’s folder, the current Rails environment name, your app’s database adapter, and schema version! about is useful when you need to ask help, check if a security patch might affect you, or when you need some stats for an existing Rails installation.

diff --git a/railties/doc/guides/html/configuring.html b/railties/doc/guides/html/configuring.html index 7bbb849b90..3cd41f100e 100644 --- a/railties/doc/guides/html/configuring.html +++ b/railties/doc/guides/html/configuring.html @@ -137,14 +137,14 @@ After-Initializers

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:

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:

@@ -304,7 +304,7 @@ and appear last in the mime encoded message.

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:

diff --git a/railties/doc/guides/html/creating_plugins.html b/railties/doc/guides/html/creating_plugins.html index c34bbef2f7..3347f77228 100644 --- a/railties/doc/guides/html/creating_plugins.html +++ b/railties/doc/guides/html/creating_plugins.html @@ -299,7 +299,7 @@ create vendor/plugins/yaffle/generators/yaffle/USAGE

vendor/plugins/yaffle/rails/init.rb

@@ -355,7 +355,7 @@ mysql:

For this guide you’ll need 2 tables/models, Hickwalls and Wickwalls, so add the following:

vendor/plugins/yaffle/test/schema.rb:

@@ -376,7 +376,7 @@ http://www.gnu.org/software/src-highlite --> end

vendor/plugins/yaffle/test/test_helper.rb:

@@ -419,7 +419,7 @@ ENV['RAILS_ROOT

Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct. By default rails generates a file in vendor/plugins/yaffle/test/yaffle_test.rb with a sample test. Replace the contents of that file with:

vendor/plugins/yaffle/test/yaffle_test.rb:

@@ -481,7 +481,7 @@ rake DB=postgresql

In this example you will add a method to String named to_squawk. To begin, create a new test file with a few assertions:

vendor/plugins/yaffle/test/core_ext_test.rb

@@ -510,7 +510,7 @@ NoMethodError: undefined method `to_squawk' for "Hello World":String

Then in lib/yaffle.rb require lib/core_ext.rb:

vendor/plugins/yaffle/lib/yaffle.rb

+ Model / Class +	+ Table / Schema +
+ Post +	+ posts +
+ LineItem +	+ line_items +
+ Deer +	+ deer +
+ Mouse +	+ mice +
+ Person +	+ people +

+ Convention +	+
+ Foreign keys +	+ These fields are named table_id i.e. (item_id, order_id) +
+ Primary Key +	+ Rails automatically creates a primary key column named "id" unless told otherwise. +

+ Attribute +	+ Purpose +
+ created_at / created_on +	+ Rails stores the current date & time to this field when creating the record. +
+ updated_at / updated_on +	+ Rails stores the current date & time to this field when updating the record. +
+ lock_version +	+ Adds optimistic locking to a model more about optimistic locking. +
+ type +	+ Specifies that the model uses Single Table Inheritance more about STI. +
+ id +	+ All models require an id. the default is name is "id" but can be changed using the "set_primary_key" or "primary_key" methods. +
+ table_name\_count +	+ Can be used to caches the number of belonging objects on the associated class. +

5.2. Connection Pooling

5.3. Hashes for Join Table Conditions

5.4.1. find_last_by_<attribute>

6.1. Shallow Route Nesting

6.2. Method Arrays for Member or Collection Routes

6.3. Resources With Specific Actions

9.1. Memoization

9.2. each_with_object

9.3. Delegates With Prefixes

Ruby on Rails

Sustainable productivity for web-application development

Chapters

Action Mailer Basics

1. What is Action Mailer?

2. Quick walkthrough to creating a Mailer

2.1. 1. Create the mailer:

2.2. 2. Edit the model:

2.3. 3. Create the mailer view

2.4. 4. Wire it up so that the system sends the email when a user signs up

3. Mailer Testing

3.2. Routing Parameters

4.2. The flash

4.2.1. flash.now

6.1. After Filters and Around Filters

9.2.1. Setting Custom Headers

11.1. Sending Files

11.2. RESTful Downloads

2.3. Placeholder Conditions

2.4. Hash Conditions

16.1. Simple Named Scopes

16.2. Combining Named Scopes

16.3. Runtime Evaluation of Named Scope Conditions

16.4. Named Scopes with Multiple Models

16.5. Arguments to Named Scopes

16.6. Anonymous Scopes

18.2. Average

18.3. Minimum

18.4. Maximum

18.5. Sum

1.2. When Does Validation Happen?

2.1. The validates_acceptance_of helper

2.2. The validates_associated helper

2.3. The validates_confirmation_of helper

2.4. The validates_exclusion_of helper

2.5. The validates_format_of helper

2.6. The validates_inclusion_of helper

2.7. The validates_length_of helper

2.9. The validates_presence_of helper

2.10. The validates_uniqueness_of helper

2.11. The validates_each helper

3.1. The :allow_nil option

3.2. The :allow_blank option

4.1. Using a symbol with the :if and :unless options

4.2. Using a string with the :if and :unless options

4.3. Using a Proc object with the :if and :unless options

7.1. Changing the way form fields with errors are displayed

8.1. Callbacks registration

9.1. Using a symbol with the :if and :unless options

9.2. Using a string with the :if and :unless options

9.3. Using a Proc object with the :if and :unless options

9.4. Multiple Conditions for Callbacks

13.1. Registering observers

2.1. The belongs_to Association

2.2. The has_one Association

2.3. The has_many Association

2.4. The has_many :through Association

2.5. The has_one :through Association

2.6. The has_and_belongs_to_many Association

2.8. Choosing Between has_many :through and has_and_belongs_to_many

2.9. Polymorphic Associations

2.10. Self Joins

3.1. Controlling Caching

3.3.1. Creating Foreign Keys for belongs_to Associations

3.4. Controlling Association Scope

association(force_reload = false)

association=(associate)

association.nil?

build_association(attributes = {})

create_association(attributes = {})

4.1.2. Options for belongs_to

5.4.1. `find_last_by_<attribute>`

9.2. `each_with_object`

4.2.1. `flash.now`

2.1. The `validates_acceptance_of` helper

2.2. The `validates_associated` helper

2.3. The `validates_confirmation_of` helper

2.4. The `validates_exclusion_of` helper

2.5. The `validates_format_of` helper

2.6. The `validates_inclusion_of` helper

2.7. The `validates_length_of` helper

2.9. The `validates_presence_of` helper

2.10. The `validates_uniqueness_of` helper

2.11. The `validates_each` helper

3.1. The `:allow_nil` option

3.2. The `:allow_blank` option

4.1. Using a symbol with the `:if` and `:unless` options

4.2. Using a string with the `:if` and `:unless` options

4.3. Using a Proc object with the `:if` and :`unless` options

9.1. Using a symbol with the `:if` and `:unless` options

9.2. Using a string with the `:if` and `:unless` options

9.3. Using a Proc object with the `:if` and :`unless` options

2.1. The `belongs_to` Association

2.2. The `has_one` Association

2.3. The `has_many` Association

2.4. The `has_many :through` Association

2.5. The `has_one :through` Association

2.6. The `has_and_belongs_to_many` Association

2.8. Choosing Between `has_many :through` and `has_and_belongs_to_many`

3.3.1. Creating Foreign Keys for `belongs_to` Associations

`association(force_reload = false)`

`association=(associate)`

`association.nil?`

`build_association(attributes = {})`

`create_association(attributes = {})`

4.1.2. Options for `belongs_to`

`:class_name`

`:conditions`

`:counter_cache`

`:foreign_key`

`:include`

`association(force_reload = false)`

`association=(associate)`

`association.nil?`

`build_association(attributes = {})`

`create_association(attributes = {})`

4.2.2. Options for `has_one`

`:class_name`

`:conditions`

`:foreign_key`

`:include`

`collection(force_reload = false)`

`collection<<(object, ...)`

`collection.delete(object, ...)`

`collection\_singular\_ids`

`collection.empty?`

`collection.size`

`collection.find(...)`

`collection.build(attributes = {}, ...)`

`collection.create(attributes = {})`

`:class_name`

`:conditions`

`:foreign_key`

`:group`

`:include`

`:limit`

`:order`

`collection<<(object, ...)`

`collection.delete(object, ...)`

`collection.empty?`

`collection.size`

`collection.find(...)`

`collection.build(attributes = {})`

`collection.create(attributes = {})`

`:class_name`

`:conditions`

`:foreign_key`

`:group`

`:limit`

`:order`