diff options
| -rw-r--r-- | actionpack/lib/abstract_controller/layouts.rb | 3 | ||||
| -rw-r--r-- | actionpack/lib/action_view/helpers/form_helper.rb | 183 | ||||
| -rw-r--r-- | activemodel/lib/active_model/locale/en.yml | 4 | ||||
| -rw-r--r-- | activemodel/lib/active_model/secure_password.rb | 13 | ||||
| -rw-r--r-- | activerecord/lib/active_record/associations.rb | 4 | ||||
| -rw-r--r-- | railties/guides/source/2_2_release_notes.textile | 2 | ||||
| -rw-r--r-- | railties/guides/source/active_support_core_extensions.textile | 49 | ||||
| -rw-r--r-- | railties/guides/source/active_support_instrumentation.textile | 57 | ||||
| -rw-r--r-- | railties/guides/source/documents.yaml | 4 | ||||
| -rw-r--r-- | railties/guides/source/form_helpers.textile | 4 | ||||
| -rw-r--r-- | railties/guides/source/security.textile | 2 |
11 files changed, 208 insertions, 117 deletions
diff --git a/actionpack/lib/abstract_controller/layouts.rb b/actionpack/lib/abstract_controller/layouts.rb index b02ee5ead3..a82e3dc90a 100644 --- a/actionpack/lib/abstract_controller/layouts.rb +++ b/actionpack/lib/abstract_controller/layouts.rb @@ -238,8 +238,7 @@ module AbstractController # # If the specified layout is a: # String:: the String is the template name - # Symbol:: call the method specified by the symbol, which will return - # the template name + # Symbol:: call the method specified by the symbol, which will return the template name # false:: There is no layout # true:: raise an ArgumentError # diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 865914c1b7..54e3032298 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -20,9 +20,9 @@ module ActionView # identity of the resource in several ways: (i) the url that the form is # sent to (the form element's +action+ attribute) should result in a request # being routed to the appropriate controller action (with the appropriate <tt>:id</tt> - # parameter in the case of an existing resource), and (ii) input fields should + # parameter in the case of an existing resource), (ii) input fields should # be named in such a way that in the controller their values appear in the - # appropriate places within the +params+ hash. Also for an existing record, + # appropriate places within the +params+ hash, and (iii) for an existing record, # when the form is initially displayed, input fields corresponding to attributes # of the resource should show the current values of those attributes. # @@ -120,29 +120,14 @@ module ActionView object.respond_to?(:to_model) ? object.to_model : object end - # Creates a form and a scope around a specific model object that is used - # as a base for questioning about values for the fields. + # Creates a form that allows the user to create or update the attributes + # of a specific model object. # - # Rails provides succinct resource-oriented form generation with +form_for+ - # like this: - # - # <%= form_for @offer do |f| %> - # <%= f.label :version, 'Version' %>: - # <%= f.text_field :version %><br /> - # <%= f.label :author, 'Author' %>: - # <%= f.text_field :author %><br /> - # <%= f.submit %> - # <% end %> - # - # There, +form_for+ is able to generate the rest of RESTful form - # parameters based on introspection on the record, but to understand what - # it does we need to dig first into the alternative generic usage it is - # based upon. - # - # === Generic form_for - # - # The generic way to call +form_for+ yields a form builder around a - # model: + # The method can be used in several slightly different ways, depending on + # how much you wish to rely on Rails to infer automatically from the model + # how the form should be constructed. For a generic model object, a form + # can be created by passing +form_for+ a string or symbol representing + # the object we are concerned with: # # <%= form_for :person do |f| %> # First name: <%= f.text_field :first_name %><br /> @@ -152,24 +137,39 @@ module ActionView # <%= f.submit %> # <% end %> # - # There, the argument is a symbol or string with the name of the - # object the form is about. - # - # The form builder acts as a regular form helper that somehow carries the - # model. Thus, the idea is that + # The variable +f+ yielded to the block is a FormBuilder object that + # incorporates the knowledge about the model object represented by + # <tt>:person</tt> passed to +form_for+. Methods defined on the FormBuilder + # are used to generate fields bound to this model. Thus, for example, # # <%= f.text_field :first_name %> # - # gets expanded to + # will get expanded to # # <%= text_field :person, :first_name %> + # which results in an html <tt><input></tt> tag whose +name+ attribute is + # <tt>person[first_name]</tt>. This means that when the form is submitted, + # the value entered by the user will be available in the controller as + # <tt>params[:person][:first_name]</tt>. + # + # For fields generated in this way using the FormBuilder, + # if <tt>:person</tt> also happens to be the name of an instance variable + # <tt>@person</tt>, the default value of the field shown when the form is + # initially displayed (e.g. in the situation where you are editing an + # existing record) will be the value of the corresponding attribute of + # <tt>@person</tt>. # # The rightmost argument to +form_for+ is an - # optional hash of options: - # - # * <tt>:url</tt> - The URL the form is submitted to. It takes the same - # fields you pass to +url_for+ or +link_to+. In particular you may pass - # here a named route directly as well. Defaults to the current action. + # optional hash of options - + # + # * <tt>:url</tt> - The URL the form is to be submitted to. This may be + # represented in the same way as values passed to +url_for+ or +link_to+. + # So for example you may use a named route directly. When the model is + # represented by a string or symbol, as in the example above, if the + # <tt>:url</tt> option is not specified, by default the form will be + # sent back to the current url (We will describe below an alternative + # resource-oriented usage of +form_for+ in which the URL does not need + # to be specified explicitly). # * <tt>:namespace</tt> - A namespace for your form to ensure uniqueness of # id attributes on form elements. The namespace attribute will be prefixed # with underscore on the generated HTML id. @@ -179,7 +179,7 @@ module ActionView # possible to use both the stand-alone FormHelper methods and methods # from FormTagHelper. For example: # - # <%= form_for @person do |f| %> + # <%= form_for :person do |f| %> # First name: <%= f.text_field :first_name %> # Last name : <%= f.text_field :last_name %> # Biography : <%= text_area :person, :biography %> @@ -191,26 +191,65 @@ module ActionView # are designed to work with an object as base, like # FormOptionHelper#collection_select and DateHelper#datetime_select. # - # === Resource-oriented style + # === #form_for with a model object # - # As we said above, in addition to manually configuring the +form_for+ - # call, you can rely on automated resource identification, which will use - # the conventions and named routes of that approach. This is the - # preferred way to use +form_for+ nowadays. + # In the examples above, the object to be created or edited was + # represented by a symbol passed to +form_for+, and we noted that + # a string can also be used equivalently. It is also possible, however, + # to pass a model object itself to +form_for+. For example, if <tt>@post</tt> + # is an existing record you wish to edit, you can create the form using + # + # <%= form_for @post do |f| %> + # ... + # <% end %> + # + # This behaves in almost the same way as outlined previously, with a + # couple of small exceptions. First, the prefix used to name the input + # elements within the form (hence the key that denotes them in the +params+ + # hash) is actually derived from the object's _class_, e.g. <tt>params[:post]</tt> + # if the object's class is +Post+. However, this can be overwritten using + # the <tt>:as</tt> option, e.g. - + # + # <%= form_for(@person, :as => :client) do |f| %> + # ... + # <% end %> # - # For example, if <tt>@post</tt> is an existing record you want to edit + # would result in <tt>params[:client]</tt>. + # + # Secondly, the field values shown when the form is initially displayed + # are taken from the attributes of the object passed to +form_for+, + # regardless of whether the object is an instance + # variable. So, for example, if we had a _local_ variable +post+ + # representing an existing record, + # + # <%= form_for post do |f| %> + # ... + # <% end %> + # + # would produce a form with fields whose initial state reflect the current + # values of the attributes of +post+. + # + # === Resource-oriented style + # + # In the examples just shown, although not indicated explicitly, we still + # need to use the <tt>:url</tt> option in order to specify where the + # form is going to be sent. However, further simplification is possible + # if the record passed to +form_for+ is a _resource_, i.e. it corresponds + # to a set of RESTful routes, e.g. defined using the +resources+ method + # in <tt>config/routes.rb</tt>. In this case Rails will simply infer the + # appropriate URL from the record itself. For example, # # <%= form_for @post do |f| %> # ... # <% end %> # - # is equivalent to something like: + # is then equivalent to something like: # # <%= form_for @post, :as => :post, :url => post_path(@post), :method => :put, :html => { :class => "edit_post", :id => "edit_post_45" } do |f| %> # ... # <% end %> # - # And for new records + # And for a new record # # <%= form_for(Post.new) do |f| %> # ... @@ -222,7 +261,7 @@ module ActionView # ... # <% end %> # - # You can also overwrite the individual conventions, like this: + # However you can still overwrite individual conventions, such as: # # <%= form_for(@post, :url => super_posts_path) do |f| %> # ... @@ -234,13 +273,6 @@ module ActionView # ... # <% end %> # - # If you have an object that needs to be represented as a different - # parameter, like a Person that acts as a Client: - # - # <%= form_for(@person, :as => :client) do |f| %> - # ... - # <% end %> - # # For namespaced routes, like +admin_post_url+: # # <%= form_for([:admin, @post]) do |f| %> @@ -263,9 +295,9 @@ module ActionView # # :method => (:get|:post|:patch|:put|:delete) # - # in the options hash. If the verb is not GET or POST, which are natively supported by HTML forms, the - # form will be set to POST and a hidden input called _method will carry the intended verb for the server - # to interpret. + # in the options hash. If the verb is not GET or POST, which are natively + # supported by HTML forms, the form will be set to POST and a hidden input + # called _method will carry the intended verb for the server to interpret. # # === Unobtrusive JavaScript # @@ -413,30 +445,59 @@ module ActionView # # === Generic Examples # + # Although the usage and purpose of +field_for+ is similar to +form_for+'s, + # its method signature is slightly different. Like +form_for+, it yields + # a FormBuilder object associated with a particular model object to a block, + # and within the block allows methods to be called on the builder to + # generate fields associated with the model object. Fields may reflect + # a model object in two ways - how they are named (hence how submitted + # values appear within the +params+ hash in the controller) and what + # default values are shown when the form the fields appear in is first + # displayed. In order for both of these features to be specified independently, + # both an object name (represented by either a symbol or string) and the + # object itself can be passed to the method separately - + # # <%= form_for @person do |person_form| %> # First name: <%= person_form.text_field :first_name %> # Last name : <%= person_form.text_field :last_name %> # - # <%= fields_for @person.permission do |permission_fields| %> + # <%= fields_for :permission, @person.permission do |permission_fields| %> # Admin? : <%= permission_fields.check_box :admin %> # <% end %> # # <%= f.submit %> # <% end %> # - # ...or if you have an object that needs to be represented as a different - # parameter, like a Client that acts as a Person: + # In this case, the checkbox field will be represented by an HTML +input+ + # tag with the +name+ attribute <tt>permission[admin]</tt>, and the submitted + # value will appear in the controller as <tt>params[:permission][:admin]</tt>. + # If <tt>@person.permission</tt> is an existing record with an attribute + # +admin+, the initial state of the checkbox when first displayed will + # reflect the value of <tt>@person.permission.admin</tt>. + # + # Often this can be simplified by passing just the name of the model + # object to +fields_for+ - # - # <%= fields_for :person, @client do |permission_fields| %> + # <%= fields_for :permission do |permission_fields| %> # Admin?: <%= permission_fields.check_box :admin %> # <% end %> # - # ...or if you don't have an object, just a name of the parameter: + # ...in which case, if <tt>:permission</tt> also happens to be the name of an + # instance variable <tt>@permission</tt>, the initial state of the input + # field will reflect the value of that variable's attribute <tt>@permission.admin</tt>. # - # <%= fields_for :person do |permission_fields| %> + # Alternatively, you can pass just the model object itself (if the first + # argument isn't a string or symbol +fields_for+ will realize that the + # name has been omitted) - + # + # <%= fields_for @person.permission do |permission_fields| %> # Admin?: <%= permission_fields.check_box :admin %> # <% end %> # + # and +fields_for+ will derive the required name of the field from the + # _class_ of the model object, e.g. if <tt>@person.permission</tt>, is + # of class +Permission+, the field will still be named <tt>permission[admin]</tt>. + # # Note: This also works for the methods in FormOptionHelper and # DateHelper that are designed to work with an object as base, like # FormOptionHelper#collection_select and DateHelper#datetime_select. diff --git a/activemodel/lib/active_model/locale/en.yml b/activemodel/lib/active_model/locale/en.yml index ba49c6beaa..1842ba002f 100644 --- a/activemodel/lib/active_model/locale/en.yml +++ b/activemodel/lib/active_model/locale/en.yml @@ -1,4 +1,8 @@ en: + attributes: + # Prevent confusion in form errors due to 'has_secure_password' + password_digest: "Password" + errors: # The default format to use in full error messages. format: "%{attribute} %{message}" diff --git a/activemodel/lib/active_model/secure_password.rb b/activemodel/lib/active_model/secure_password.rb index e7a57cf691..7c529cb67b 100644 --- a/activemodel/lib/active_model/secure_password.rb +++ b/activemodel/lib/active_model/secure_password.rb @@ -10,6 +10,19 @@ module ActiveModel # a "password_confirmation" attribute) are automatically added. # You can add more validations by hand if need be. # + # Note: the implementation of <tt>has_secure_password</tt> enforces presence validation + # on the <tt>:password_digest</tt> attribute rather than on <tt>:password</tt>, which is + # in fact a virtual reader attribute. However, <tt>validates_confirmation_of</tt> ensures + # an indirect means of presence validation of <tt>:password</tt> if the + # <tt>:password_confirmation</tt> attribute is not nil. + # + # You may want to add presence validation on <tt>:password</tt> for the benefit of your forms + # + # class User < ActiveRecord::Base + # has_secure_password + # validates :password, :presence => { :on => :create } + # end + # # You need to add bcrypt-ruby (~> 3.0.0) to Gemfile to use has_secure_password: # # gem 'bcrypt-ruby', '~> 3.0.0' diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index b1a5110e2d..b901f06ca4 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1382,7 +1382,9 @@ module ActiveRecord # and +decrement_counter+. The counter cache is incremented when an object of this # class is created and decremented when it's destroyed. This requires that a column # named <tt>#{table_name}_count</tt> (such as +comments_count+ for a belonging Comment class) - # is used on the associate class (such as a Post class). You can also specify a custom counter + # is used on the associate class (such as a Post class) - that is the migration for + # <tt>#{table_name}_count</tt> is created on the associate class (such that Post.comments_count will + # return the count cached, see note below). You can also specify a custom counter # cache column by providing a column name instead of a +true+/+false+ value to this # option (e.g., <tt>:counter_cache => :my_custom_counter</tt>.) # Note: Specifying a counter cache will add it to that model's list of readonly attributes diff --git a/railties/guides/source/2_2_release_notes.textile b/railties/guides/source/2_2_release_notes.textile index 8e2d528eee..3a0f2efbaf 100644 --- a/railties/guides/source/2_2_release_notes.textile +++ b/railties/guides/source/2_2_release_notes.textile @@ -229,7 +229,7 @@ This will enable recognition of (among others) these routes: * Lead Contributor: "S. Brent Faulkner":http://www.unwwwired.net/ * More information: -** "Rails Routing from the Outside In":http://guides.rubyonrails.org/routing.html#_nested_resources +** "Rails Routing from the Outside In":http://guides.rubyonrails.org/routing.html#nested-resources ** "What's New in Edge Rails: Shallow Routes":http://ryandaigle.com/articles/2008/9/7/what-s-new-in-edge-rails-shallow-routes h4. Method Arrays for Member or Collection Routes diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 2091ce0395..5d0a3f82e8 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -509,55 +509,6 @@ end NOTE: Defined in +active_support/core_ext/module/aliasing.rb+. -h5. +attr_accessor_with_default+ - -The method +attr_accessor_with_default+ serves the same purpose as the Ruby macro +attr_accessor+ but allows you to set a default value for the attribute: - -<ruby> -class Url - attr_accessor_with_default :port, 80 -end - -Url.new.port # => 80 -</ruby> - -The default value can be also specified with a block, which is called in the context of the corresponding object: - -<ruby> -class User - attr_accessor :name, :surname - attr_accessor_with_default(:full_name) do - [name, surname].compact.join(" ") - end -end - -u = User.new -u.name = 'Xavier' -u.surname = 'Noria' -u.full_name # => "Xavier Noria" -</ruby> - -The result is not cached, the block is invoked in each call to the reader. - -You can overwrite the default with the writer: - -<ruby> -url = Url.new -url.host # => 80 -url.host = 8080 -url.host # => 8080 -</ruby> - -The default value is returned as long as the attribute is unset. The reader does not rely on the value of the attribute to know whether it has to return the default. It rather monitors the writer: if there's any assignment the value is no longer considered to be unset. - -Active Resource uses this macro to set a default value for the +:primary_key+ attribute: - -<ruby> -attr_accessor_with_default :primary_key, 'id' -</ruby> - -NOTE: Defined in +active_support/core_ext/module/attr_accessor_with_default.rb+. - h5. Internal Attributes When you are defining an attribute in a class that is meant to be subclassed, name collisions are a risk. That's remarkably important for libraries. diff --git a/railties/guides/source/active_support_instrumentation.textile b/railties/guides/source/active_support_instrumentation.textile index f9452400ad..8e2866dfc3 100644 --- a/railties/guides/source/active_support_instrumentation.textile +++ b/railties/guides/source/active_support_instrumentation.textile @@ -21,10 +21,67 @@ You are even able to create your own events inside your application which you ca h3. Rails framework hooks +Within the Ruby on Rails framework, there are a number of hooks provided for common events. These are detailed below. + h4. Action Mailer +h5. receive.action_mailer + +This hook is called when the +receive+ method of an +ActionMailer::Base+ class is called: + +<ruby> + class Mailer < ActionMailer::Base + def receive(mail) + + end + end +</ruby> + +The payload for this event has the following parameters related to the incoming email: + +|_.Key |_.Value| +|mailer |Name of the mailer class| +|message_id |ID of the message, generated by the Mail gem| +|subject |Subject of the mail| +|to |To address(es) of the mail| +|from |From address of the mail| +|bcc |BCC addresses of the mail| +|cc |CC addresses of the mail| +|date |Date of the mail| +|mail |The encoded form of the mail| + +h5. deliver.action_mailer + +This hook is called when the +deliver+ method is called on a +Mail::Message+ object. This is due to a hook inserted by Action Mailer, rather than a specific feature of the Mail gem itself. + +The payload for this event has the following parameters related to the outgoing email: + +|_.Key |_.Value| +|mailer |Name of the mailer class| +|message_id |ID of the message, generated by the Mail gem| +|subject |Subject of the mail| +|to |To address(es) of the mail| +|from |From address of the mail| +|bcc |BCC addresses of the mail| +|cc |CC addresses of the mail| +|date |Date of the mail| +|mail |The encoded form of the mail| + + h4. Action Controller +h5. write_fragment.action_controller + +h5. read_fragment.action_controller + +h5. exist_fragment?.action_controller + +h5. expire_fragment.action_controller + +h5. write_page.action_controller + +h5. expire_page.action_controller + h4. Action View h4. Active Record diff --git a/railties/guides/source/documents.yaml b/railties/guides/source/documents.yaml index 08aafda288..1c8d7d284c 100644 --- a/railties/guides/source/documents.yaml +++ b/railties/guides/source/documents.yaml @@ -97,6 +97,10 @@ url: asset_pipeline.html description: This guide documents the asset pipeline. - + name: Getting Started with Engines + url: engines.html + description: This guide explains how to write a mountable engine. + - name: The Rails Initialization Process work_in_progress: true url: initialization.html diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile index a696e4f8ae..9f91d12a54 100644 --- a/railties/guides/source/form_helpers.textile +++ b/railties/guides/source/form_helpers.textile @@ -39,7 +39,7 @@ When called without arguments like this, it creates a +<form>+ tag which, </form> </html> -Now, you'll notice that the HTML contains something extra: a +div+ element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name +utf8+ enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name +authenticity_token+ is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the "Security Guide":./security.html#_cross_site_reference_forgery_csrf. +Now, you'll notice that the HTML contains something extra: a +div+ element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name +utf8+ enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name +authenticity_token+ is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the "Security Guide":./security.html#cross-site-request-forgery-csrf. NOTE: Throughout this guide, the +div+ with the hidden input elements will be excluded from code samples for brevity. @@ -428,7 +428,7 @@ As with other helpers, if you were to use the +select+ helper on a form builder <%= f.select(:city_id, ...) %> </erb> -WARNING: If you are using +select+ (or similar helpers such as +collection_select+, +select_tag+) to set a +belongs_to+ association you must pass the name of the foreign key (in the example above +city_id+), not the name of association itself. If you specify +city+ instead of +city_id+ Active Record will raise an error along the lines of <tt> ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) </tt> when you pass the +params+ hash to +Person.new+ or +update_attributes+. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of +attr_protected+ and +attr_accessible+. For further details on this, see the "Ruby On Rails Security Guide":security.html#_mass_assignment. +WARNING: If you are using +select+ (or similar helpers such as +collection_select+, +select_tag+) to set a +belongs_to+ association you must pass the name of the foreign key (in the example above +city_id+), not the name of association itself. If you specify +city+ instead of +city_id+ Active Record will raise an error along the lines of <tt> ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) </tt> when you pass the +params+ hash to +Person.new+ or +update_attributes+. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of +attr_protected+ and +attr_accessible+. For further details on this, see the "Ruby On Rails Security Guide":security.html#mass-assignment. h4. Option Tags from a Collection of Arbitrary Objects diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile index b1a09c0c05..747a4d6791 100644 --- a/railties/guides/source/security.textile +++ b/railties/guides/source/security.textile @@ -374,7 +374,7 @@ end Mass-assignment saves you much work, because you don't have to set each value individually. Simply pass a hash to the +new+ method, or +assign_attributes=+ a hash value, to set the model's attributes to the values in the hash. The problem is that it is often used in conjunction with the parameters (params) hash available in the controller, which may be manipulated by an attacker. He may do so by changing the URL like this: <pre> -"name":http://www.example.com/user/signup?user[name]=ow3ned&user[admin]=1 +http://www.example.com/user/signup?user[name]=ow3ned&user[admin]=1 </pre> This will set the following parameters in the controller: |