diff options
| -rw-r--r-- | README.rdoc | 8 | ||||
| -rw-r--r-- | actionmailer/lib/action_mailer/base.rb | 2 | ||||
| -rw-r--r-- | actionpack/lib/action_view/helpers/form_helper.rb | 412 | ||||
| -rw-r--r-- | guides/source/action_mailer_basics.md | 1 | ||||
| -rw-r--r-- | guides/source/action_view_overview.md | 2 | ||||
| -rw-r--r-- | guides/source/active_record_callbacks.md | 1 | ||||
| -rw-r--r-- | guides/source/active_record_validations.md | 7 | ||||
| -rw-r--r-- | guides/source/active_support_core_extensions.md | 31 | ||||
| -rw-r--r-- | guides/source/asset_pipeline.md | 3 | ||||
| -rw-r--r-- | guides/source/form_helpers.md | 2 | ||||
| -rw-r--r-- | guides/source/i18n.md | 2 | ||||
| -rw-r--r-- | guides/source/routing.md | 6 | ||||
| -rw-r--r-- | guides/source/security.md | 136 | ||||
| -rw-r--r-- | railties/lib/rails/generators/rails/migration/USAGE | 9 | ||||
| -rw-r--r-- | railties/lib/rails/info_controller.rb | 2 |
15 files changed, 435 insertions, 189 deletions
diff --git a/README.rdoc b/README.rdoc index 87ec64e3b5..91a5f27add 100644 --- a/README.rdoc +++ b/README.rdoc @@ -56,10 +56,10 @@ can read more about Action Pack in its {README}[link:/rails/rails/blob/master/ac 5. Follow the guidelines to start developing your application. You may find the following resources handy: * The README file created within your application. -* The {Getting Started with Rails}[http://guides.rubyonrails.org/getting_started.html]. -* The {Ruby on Rails Tutorial}[http://railstutorial.org/book]. -* The {Ruby on Rails Guides}[http://guides.rubyonrails.org]. -* The {API Documentation}[http://api.rubyonrails.org]. +* {Getting Started with Rails}[http://guides.rubyonrails.org/getting_started.html]. +* {Ruby on Rails Tutorial}[http://ruby.railstutorial.org/ruby-on-rails-tutorial-book]. +* {Ruby on Rails Guides}[http://guides.rubyonrails.org]. +* {The API Documentation}[http://api.rubyonrails.org]. == Contributing diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index 6056399cd2..4a61bac0a5 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -314,7 +314,7 @@ module ActionMailer # These options are specified on the class level, like # <tt>ActionMailer::Base.raise_delivery_errors = true</tt> # - # * <tt>default</tt> - You can pass this in at a class level as well as within the class itself as + # * <tt>default_options</tt> - You can pass this in at a class level as well as within the class itself as # per the above section. # # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available. diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 5710d1fc02..516492ca30 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -1226,6 +1226,255 @@ module ActionView RUBY_EVAL end + # Creates a scope around a specific model object like form_for, but + # doesn't create the form tags themselves. This makes fields_for suitable + # for specifying additional model objects in the same form. + # + # 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 :permission, @person.permission do |permission_fields| %> + # Admin? : <%= permission_fields.check_box :admin %> + # <% end %> + # + # <%= f.submit %> + # <% end %> + # + # 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 :permission do |permission_fields| %> + # Admin?: <%= permission_fields.check_box :admin %> + # <% end %> + # + # ...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>. + # + # 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. + # + # === Nested Attributes Examples + # + # When the object belonging to the current scope has a nested attribute + # writer for a certain attribute, fields_for will yield a new scope + # for that attribute. This allows you to create forms that set or change + # the attributes of a parent object and its associations in one go. + # + # Nested attribute writers are normal setter methods named after an + # association. The most common way of defining these writers is either + # with +accepts_nested_attributes_for+ in a model definition or by + # defining a method with the proper name. For example: the attribute + # writer for the association <tt>:address</tt> is called + # <tt>address_attributes=</tt>. + # + # Whether a one-to-one or one-to-many style form builder will be yielded + # depends on whether the normal reader method returns a _single_ object + # or an _array_ of objects. + # + # ==== One-to-one + # + # Consider a Person class which returns a _single_ Address from the + # <tt>address</tt> reader method and responds to the + # <tt>address_attributes=</tt> writer method: + # + # class Person + # def address + # @address + # end + # + # def address_attributes=(attributes) + # # Process the attributes hash + # end + # end + # + # This model can now be used with a nested fields_for, like so: + # + # <%= form_for @person do |person_form| %> + # ... + # <%= person_form.fields_for :address do |address_fields| %> + # Street : <%= address_fields.text_field :street %> + # Zip code: <%= address_fields.text_field :zip_code %> + # <% end %> + # ... + # <% end %> + # + # When address is already an association on a Person you can use + # +accepts_nested_attributes_for+ to define the writer method for you: + # + # class Person < ActiveRecord::Base + # has_one :address + # accepts_nested_attributes_for :address + # end + # + # If you want to destroy the associated model through the form, you have + # to enable it first using the <tt>:allow_destroy</tt> option for + # +accepts_nested_attributes_for+: + # + # class Person < ActiveRecord::Base + # has_one :address + # accepts_nested_attributes_for :address, allow_destroy: true + # end + # + # Now, when you use a form element with the <tt>_destroy</tt> parameter, + # with a value that evaluates to +true+, you will destroy the associated + # model (eg. 1, '1', true, or 'true'): + # + # <%= form_for @person do |person_form| %> + # ... + # <%= person_form.fields_for :address do |address_fields| %> + # ... + # Delete: <%= address_fields.check_box :_destroy %> + # <% end %> + # ... + # <% end %> + # + # ==== One-to-many + # + # Consider a Person class which returns an _array_ of Project instances + # from the <tt>projects</tt> reader method and responds to the + # <tt>projects_attributes=</tt> writer method: + # + # class Person + # def projects + # [@project1, @project2] + # end + # + # def projects_attributes=(attributes) + # # Process the attributes hash + # end + # end + # + # Note that the <tt>projects_attributes=</tt> writer method is in fact + # required for fields_for to correctly identify <tt>:projects</tt> as a + # collection, and the correct indices to be set in the form markup. + # + # When projects is already an association on Person you can use + # +accepts_nested_attributes_for+ to define the writer method for you: + # + # class Person < ActiveRecord::Base + # has_many :projects + # accepts_nested_attributes_for :projects + # end + # + # This model can now be used with a nested fields_for. The block given to + # the nested fields_for call will be repeated for each instance in the + # collection: + # + # <%= form_for @person do |person_form| %> + # ... + # <%= person_form.fields_for :projects do |project_fields| %> + # <% if project_fields.object.active? %> + # Name: <%= project_fields.text_field :name %> + # <% end %> + # <% end %> + # ... + # <% end %> + # + # It's also possible to specify the instance to be used: + # + # <%= form_for @person do |person_form| %> + # ... + # <% @person.projects.each do |project| %> + # <% if project.active? %> + # <%= person_form.fields_for :projects, project do |project_fields| %> + # Name: <%= project_fields.text_field :name %> + # <% end %> + # <% end %> + # <% end %> + # ... + # <% end %> + # + # Or a collection to be used: + # + # <%= form_for @person do |person_form| %> + # ... + # <%= person_form.fields_for :projects, @active_projects do |project_fields| %> + # Name: <%= project_fields.text_field :name %> + # <% end %> + # ... + # <% end %> + # + # When projects is already an association on Person you can use + # +accepts_nested_attributes_for+ to define the writer method for you: + # + # class Person < ActiveRecord::Base + # has_many :projects + # accepts_nested_attributes_for :projects + # end + # + # If you want to destroy any of the associated models through the + # form, you have to enable it first using the <tt>:allow_destroy</tt> + # option for +accepts_nested_attributes_for+: + # + # class Person < ActiveRecord::Base + # has_many :projects + # accepts_nested_attributes_for :projects, allow_destroy: true + # end + # + # This will allow you to specify which models to destroy in the + # attributes hash by adding a form element for the <tt>_destroy</tt> + # parameter with a value that evaluates to +true+ + # (eg. 1, '1', true, or 'true'): + # + # <%= form_for @person do |person_form| %> + # ... + # <%= person_form.fields_for :projects do |project_fields| %> + # Delete: <%= project_fields.check_box :_destroy %> + # <% end %> + # ... + # <% end %> + # + # When a collection is used you might want to know the index of each + # object into the array. For this purpose, the <tt>index</tt> method + # is available in the FormBuilder object. + # + # <%= form_for @person do |person_form| %> + # ... + # <%= person_form.fields_for :projects do |project_fields| %> + # Project #<%= project_fields.index %> + # ... + # <% end %> + # ... + # <% end %> + # + # Note that fields_for will automatically generate a hidden field + # to store the ID of the record. There are circumstances where this + # hidden field is not needed and you can pass <tt>hidden_field_id: false</tt> + # to prevent fields_for from rendering it automatically. def fields_for(record_name, record_object = nil, fields_options = {}, &block) fields_options, record_object = record_object, nil if record_object.is_a?(Hash) && record_object.extractable_options? fields_options[:builder] ||= options[:builder] @@ -1255,23 +1504,186 @@ module ActionView @template.fields_for(record_name, record_object, fields_options, &block) end + # Returns a label tag tailored for labelling an input field for a specified attribute (identified by +method+) on an object + # assigned to the template (identified by +object+). The text of label will default to the attribute name unless a translation + # is found in the current I18n locale (through helpers.label.<modelname>.<attribute>) or you specify it explicitly. + # Additional options on the label tag can be passed as a hash with +options+. These options will be tagged + # onto the HTML as an HTML element attribute as in the example shown, except for the <tt>:value</tt> option, which is designed to + # target labels for radio_button tags (where the value is used in the ID of the input tag). + # + # ==== Examples + # label(:post, :title) + # # => <label for="post_title">Title</label> + # + # You can localize your labels based on model and attribute names. + # For example you can define the following in your locale (e.g. en.yml) + # + # helpers: + # label: + # post: + # body: "Write your entire text here" + # + # Which then will result in + # + # label(:post, :body) + # # => <label for="post_body">Write your entire text here</label> + # + # Localization can also be based purely on the translation of the attribute-name + # (if you are using ActiveRecord): + # + # activerecord: + # attributes: + # post: + # cost: "Total cost" + # + # label(:post, :cost) + # # => <label for="post_cost">Total cost</label> + # + # label(:post, :title, "A short title") + # # => <label for="post_title">A short title</label> + # + # label(:post, :title, "A short title", class: "title_label") + # # => <label for="post_title" class="title_label">A short title</label> + # + # label(:post, :privacy, "Public Post", value: "public") + # # => <label for="post_privacy_public">Public Post</label> + # + # label(:post, :terms) do + # 'Accept <a href="/terms">Terms</a>.'.html_safe + # end def label(method, text = nil, options = {}, &block) @template.label(@object_name, method, text, objectify_options(options), &block) end + # Returns a checkbox tag tailored for accessing a specified attribute (identified by +method+) on an object + # assigned to the template (identified by +object+). This object must be an instance object (@object) and not a local object. + # It's intended that +method+ returns an integer and if that integer is above zero, then the checkbox is checked. + # Additional options on the input tag can be passed as a hash with +options+. The +checked_value+ defaults to 1 + # while the default +unchecked_value+ is set to 0 which is convenient for boolean values. + # + # ==== Gotcha + # + # The HTML specification says unchecked check boxes are not successful, and + # thus web browsers do not send them. Unfortunately this introduces a gotcha: + # if an +Invoice+ model has a +paid+ flag, and in the form that edits a paid + # invoice the user unchecks its check box, no +paid+ parameter is sent. So, + # any mass-assignment idiom like + # + # @invoice.update_attributes(params[:invoice]) + # + # wouldn't update the flag. + # + # To prevent this the helper generates an auxiliary hidden field before + # the very check box. The hidden field has the same name and its + # attributes mimic an unchecked check box. + # + # This way, the client either sends only the hidden field (representing + # the check box is unchecked), or both fields. Since the HTML specification + # says key/value pairs have to be sent in the same order they appear in the + # form, and parameters extraction gets the last occurrence of any repeated + # key in the query string, that works for ordinary forms. + # + # Unfortunately that workaround does not work when the check box goes + # within an array-like parameter, as in + # + # <%= fields_for "project[invoice_attributes][]", invoice, index: nil do |form| %> + # <%= form.check_box :paid %> + # ... + # <% end %> + # + # because parameter name repetition is precisely what Rails seeks to distinguish + # the elements of the array. For each item with a checked check box you + # get an extra ghost item with only that attribute, assigned to "0". + # + # In that case it is preferable to either use +check_box_tag+ or to use + # hashes instead of arrays. + # + # # Let's say that @post.validated? is 1: + # check_box("post", "validated") + # # => <input name="post[validated]" type="hidden" value="0" /> + # # <input checked="checked" type="checkbox" id="post_validated" name="post[validated]" value="1" /> + # + # # Let's say that @puppy.gooddog is "no": + # check_box("puppy", "gooddog", {}, "yes", "no") + # # => <input name="puppy[gooddog]" type="hidden" value="no" /> + # # <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" /> + # + # check_box("eula", "accepted", { class: 'eula_check' }, "yes", "no") + # # => <input name="eula[accepted]" type="hidden" value="no" /> + # # <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" /> def check_box(method, options = {}, checked_value = "1", unchecked_value = "0") @template.check_box(@object_name, method, objectify_options(options), checked_value, unchecked_value) end + # Returns a radio button tag for accessing a specified attribute (identified by +method+) on an object + # assigned to the template (identified by +object+). If the current value of +method+ is +tag_value+ the + # radio button will be checked. + # + # To force the radio button to be checked pass <tt>checked: true</tt> in the + # +options+ hash. You may pass HTML options there as well. + # + # # Let's say that @post.category returns "rails": + # radio_button("post", "category", "rails") + # radio_button("post", "category", "java") + # # => <input type="radio" id="post_category_rails" name="post[category]" value="rails" checked="checked" /> + # # <input type="radio" id="post_category_java" name="post[category]" value="java" /> + # + # radio_button("user", "receive_newsletter", "yes") + # radio_button("user", "receive_newsletter", "no") + # # => <input type="radio" id="user_receive_newsletter_yes" name="user[receive_newsletter]" value="yes" /> + # # <input type="radio" id="user_receive_newsletter_no" name="user[receive_newsletter]" value="no" checked="checked" /> def radio_button(method, tag_value, options = {}) @template.radio_button(@object_name, method, tag_value, objectify_options(options)) end + # Returns a hidden input tag tailored for accessing a specified attribute (identified by +method+) on an object + # assigned to the template (identified by +object+). Additional options on the input tag can be passed as a + # hash with +options+. These options will be tagged onto the HTML as an HTML element attribute as in the example + # shown. + # + # ==== Examples + # hidden_field(:signup, :pass_confirm) + # # => <input type="hidden" id="signup_pass_confirm" name="signup[pass_confirm]" value="#{@signup.pass_confirm}" /> + # + # hidden_field(:post, :tag_list) + # # => <input type="hidden" id="post_tag_list" name="post[tag_list]" value="#{@post.tag_list}" /> + # + # hidden_field(:user, :token) + # # => <input type="hidden" id="user_token" name="user[token]" value="#{@user.token}" /> + # def hidden_field(method, options = {}) @emitted_hidden_id = true if method == :id @template.hidden_field(@object_name, method, objectify_options(options)) end + # Returns a file upload input tag tailored for accessing a specified attribute (identified by +method+) on an object + # assigned to the template (identified by +object+). Additional options on the input tag can be passed as a + # hash with +options+. These options will be tagged onto the HTML as an HTML element attribute as in the example + # shown. + # + # Using this method inside a +form_for+ block will set the enclosing form's encoding to <tt>multipart/form-data</tt>. + # + # ==== Options + # * Creates standard HTML attributes for the tag. + # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input. + # * <tt>:multiple</tt> - If set to true, *in most updated browsers* the user will be allowed to select multiple files. + # * <tt>:accept</tt> - If set to one or multiple mime-types, the user will be suggested a filter when choosing a file. You still need to set up model validations. + # + # ==== Examples + # file_field(:user, :avatar) + # # => <input type="file" id="user_avatar" name="user[avatar]" /> + # + # file_field(:post, :image, :multiple => true) + # # => <input type="file" id="post_image" name="post[image]" multiple="true" /> + # + # file_field(:post, :attached, accept: 'text/html') + # # => <input accept="text/html" type="file" id="post_attached" name="post[attached]" /> + # + # file_field(:post, :image, accept: 'image/png,image/gif,image/jpeg') + # # => <input type="file" id="post_image" name="post[image]" accept="image/png,image/gif,image/jpeg" /> + # + # file_field(:attachment, :file, class: 'file_input') + # # => <input type="file" id="attachment_file" name="attachment[file]" class="file_input" /> def file_field(method, options = {}) self.multipart = true @template.file_field(@object_name, method, objectify_options(options)) diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index aaf04f4256..6bb3439e5e 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -516,7 +516,6 @@ The following configuration options are best made in one of the environment file |`perform_deliveries`|Determines whether deliveries are actually carried out when the `deliver` method is invoked on the Mail message. By default they are, but this can be turned off to help functional testing.| |`deliveries`|Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful for unit and functional testing.| |`default_options`|Allows you to set default values for the `mail` method options (`:from`, `:reply_to`, etc.).| -|`async`|Setting this flag will turn on asynchronous message sending, message rendering and delivery will be pushed to `Rails.queue` for processing.| ### Example Action Mailer Configuration diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md index 6c2871d478..4cdac43a7e 100644 --- a/guides/source/action_view_overview.md +++ b/guides/source/action_view_overview.md @@ -1264,7 +1264,7 @@ Creates a field set for grouping HTML form elements. Creates a file upload field. ```html+erb -<%= form_tag {action: "post"} do %> +<%= form_tag {action: "post"}, {multipart: true} do %> <label for="file">File to Upload</label> <%= file_field_tag "file" %> <%= submit_tag %> <% end %> diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md index 971c1cdb25..0a93f61f6d 100644 --- a/guides/source/active_record_callbacks.md +++ b/guides/source/active_record_callbacks.md @@ -150,6 +150,7 @@ The following methods trigger callbacks: * `create!` * `decrement!` * `destroy` +* `destroy!` * `destroy_all` * `increment!` * `save` diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index 2e2f0e4ea9..88d52cb829 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -503,8 +503,8 @@ end ``` If you want to be sure that an association is present, you'll need to test -whether the foreign key used to map the association is present, and not the -associated object itself. +whether the associated object itself is present, and not the foreign key used +to map the association. ```ruby class LineItem < ActiveRecord::Base @@ -513,7 +513,8 @@ class LineItem < ActiveRecord::Base end ``` -You should also be sure to have a proper `:inverse_of` as well: +In order to validate associated records whose presence is required, you must +specify the `:inverse_of` option for the association: ```ruby class Order < ActiveRecord::Base diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 1d79ee2565..23736020ec 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -2678,13 +2678,6 @@ If the receiver responds to `convert_key`, the method is called on each of the a {a: 1}.with_indifferent_access.except("a") # => {} ``` -The method `except` may come in handy for example when you want to protect some parameter that can't be globally protected with `attr_protected`: - -```ruby -params[:account] = params[:account].except(:plan_id) unless admin? -@account.update_attributes(params[:account]) -``` - There's also the bang variant `except!` that removes keys in the very receiver. NOTE: Defined in `active_support/core_ext/hash/except.rb`. @@ -3599,7 +3592,7 @@ Time.zone_default # => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...> # In Barcelona, 2010/03/28 02:00 +0100 becomes 2010/03/28 03:00 +0200 due to DST. -t = Time.local_time(2010, 3, 28, 1, 59, 59) +t = Time.local(2010, 3, 28, 1, 59, 59) # => Sun Mar 28 01:59:59 +0100 2010 t.advance(seconds: 1) # => Sun Mar 28 03:00:00 +0200 2010 @@ -3654,26 +3647,6 @@ Time.current Analogously to `DateTime`, the predicates `past?`, and `future?` are relative to `Time.current`. -Use the `local_time` class method to create time objects honoring the user time zone: - -```ruby -Time.zone_default -# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...> -Time.local_time(2010, 8, 15) -# => Sun Aug 15 00:00:00 +0200 2010 -``` - -The `utc_time` class method returns a time in UTC: - -```ruby -Time.zone_default -# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...> -Time.utc_time(2010, 8, 15) -# => Sun Aug 15 00:00:00 UTC 2010 -``` - -Both `local_time` and `utc_time` accept up to seven positional arguments: year, month, day, hour, min, sec, usec. Year is mandatory, month and day default to 1, and the rest default to 0. - If the time to be constructed lies beyond the range supported by `Time` in the runtime platform, usecs are discarded and a `DateTime` object is returned instead. #### Durations @@ -3692,7 +3665,7 @@ now - 1.week They translate to calls to `since` or `advance`. For example here we get the correct jump in the calendar reform: ```ruby -Time.utc_time(1582, 10, 3) + 5.days +Time.utc(1582, 10, 3) + 5.days # => Mon Oct 18 00:00:00 UTC 1582 ``` diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index ff6787dae5..743a04ed42 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -272,7 +272,8 @@ $('#logo').attr src: "<%= asset_path('logo.png') %>" ### Manifest Files and Directives -Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ — instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if `Rails.application.config.assets.compress` is true). By serving one file rather than many, the load time of pages can be greatly reduced because the browser makes fewer requests. +Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ — instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if `Rails.application.config.assets.compress` is true). By serving one file rather than many, the load time of pages can be greatly reduced because the browser makes fewer requests. Compression also reduces the file size enabling the browser to download it faster. + For example, a new Rails application includes a default `app/assets/javascripts/application.js` file which contains the following lines: diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md index ee563e72d5..8ab44ea0bb 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -458,7 +458,7 @@ As with other helpers, if you were to use the `select` helper on a form builder <%= f.select(:city_id, ...) %> ``` -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 ` ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) ` 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 ` ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) ` 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. ### Option Tags from a Collection of Arbitrary Objects diff --git a/guides/source/i18n.md b/guides/source/i18n.md index 399a4963d7..2e61bea5ea 100644 --- a/guides/source/i18n.md +++ b/guides/source/i18n.md @@ -96,7 +96,7 @@ This means, that in the `:en` locale, the key _hello_ will map to the _Hello wor The I18n library will use **English** as a **default locale**, i.e. if you don't set a different locale, `:en` will be used for looking up translations. -NOTE: The i18n library takes a **pragmatic approach** to locale keys (after [some discussion](http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like `:en`, `:pl`, not the _region_ part, like `:en-US` or `:en-GB`, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as `:cs`, `:th` or `:es` (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the `:en-US` locale you would have $ as a currency symbol, while in `:en-GB`, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a `:en-GB` dictionary. Various [Rails I18n plugins](http://rails-i18n.org/wiki) such as [Globalize2](https://github.com/joshmh/globalize2/tree/master) may help you implement it. +NOTE: The i18n library takes a **pragmatic approach** to locale keys (after [some discussion](http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like `:en`, `:pl`, not the _region_ part, like `:en-US` or `:en-GB`, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as `:cs`, `:th` or `:es` (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the `:en-US` locale you would have $ as a currency symbol, while in `:en-GB`, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a `:en-GB` dictionary. Various [Rails I18n plugins](http://rails-i18n.org/wiki) such as [Globalize3](https://github.com/svenfuchs/globalize3) may help you implement it. The **translations load path** (`I18n.load_path`) is just a Ruby Array of paths to your translation files that will be loaded automatically and available in your application. You can pick whatever directory and translation file naming scheme makes sense for you. diff --git a/guides/source/routing.md b/guides/source/routing.md index 241a7cfec6..14f23d4020 100644 --- a/guides/source/routing.md +++ b/guides/source/routing.md @@ -471,7 +471,7 @@ resources :photos do end ``` -This will recognize `/photos/1/preview` with GET, and route to the `preview` action of `PhotosController`. It will also create the `preview_photo_url` and `preview_photo_path` helpers. +This will recognize `/photos/1/preview` with GET, and route to the `preview` action of `PhotosController`, with the resource id value passed in `params[:id]`. It will also create the `preview_photo_url` and `preview_photo_path` helpers. Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use `get`, `patch`, `put`, `post`, or `delete` here. If you don't have multiple `member` routes, you can also pass `:on` to a route, eliminating the block: @@ -481,6 +481,8 @@ resources :photos do end ``` +You can leave out the `:on` option, this will create the same member route except that the resource id value will be available in `params[:photo_id]` instead of `params[:id]`. + #### Adding Collection Routes To add a route to the collection: @@ -791,7 +793,7 @@ root to: 'pages#main' root 'pages#main' # shortcut for the above ``` -You should put the `root` route at the top of the file, because it is the most popular route and should be matched first. You also need to delete the `public/index.html` file for the root route to take effect. +You should put the `root` route at the top of the file, because it is the most popular route and should be matched first. NOTE: The `root` route only routes `GET` requests to the action. diff --git a/guides/source/security.md b/guides/source/security.md index 532a1ae5cc..8096ea2383 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -374,141 +374,6 @@ The common admin interface works like this: it's located at www.example.com/admi * _Put the admin interface to a special sub-domain_ such as admin.application.com and make it a separate application with its own user management. This makes stealing an admin cookie from the usual domain, www.application.com, impossible. This is because of the same origin policy in your browser: An injected (XSS) script on www.application.com may not read the cookie for admin.application.com and vice-versa. -Mass Assignment ---------------- - -WARNING: _Without any precautions `Model.new(params[:model]`) allows attackers to set -any database column's value._ - -The mass-assignment feature may become a problem, as it allows an attacker to set -any model's attributes by manipulating the hash passed to a model's `new()` method: - -```ruby -def signup - params[:user] # => {name:"ow3ned", admin:true} - @user = User.new(params[:user]) -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: - -``` -http://www.example.com/user/signup?user[name]=ow3ned&user[admin]=1 -``` - -This will set the following parameters in the controller: - -```ruby -params[:user] # => {name:"ow3ned", admin:true} -``` - -So if you create a new user using mass-assignment, it may be too easy to become -an administrator. - -Note that this vulnerability is not restricted to database columns. Any setter -method, unless explicitly protected, is accessible via the `attributes=` method. -In fact, this vulnerability is extended even further with the introduction of -nested mass assignment (and nested object forms) in Rails 2.3. The -`accepts_nested_attributes_for` declaration provides us the ability to extend -mass assignment to model associations (`has_many`, `has_one`, -`has_and_belongs_to_many`). For example: - -```ruby - class Person < ActiveRecord::Base - has_many :children - - accepts_nested_attributes_for :children - end - - class Child < ActiveRecord::Base - belongs_to :person - end -``` - -As a result, the vulnerability is extended beyond simply exposing column -assignment, allowing attackers the ability to create entirely new records -in referenced tables (children in this case). - -### Countermeasures - -To avoid this, Rails provides an interface for protecting attributes from -end-user assignment called Strong Parameters. This makes Action Controller -parameters forbidden until they have been whitelisted, so you will have to -make a conscious choice about which attributes to allow for mass assignment -and thus prevent accidentally exposing that which shouldn’t be exposed. - -NOTE. Before Strong Parameters arrived, mass-assignment protection was a -model's task provided by Active Model. This has been extracted to the -[ProtectedAttributes](https://github.com/rails/protected_attributes) -gem. In order to use `attr_accessible` and `attr_protected` helpers in -your models, you should add `protected_attributes` to your Gemfile. - -Why we moved mass-assignment protection out of the model and into -the controller? The whole point of the controller is to control the -flow between user and application, including authentication, authorization, -and, as part of that, access control. - -Strong Parameters provides two methods to the `params` hash to control -access to your attributes: `require` and `permit`. The former is used -to mark parameters as required and the latter limits which attributes -should be allowed for mass updating using the slice pattern. For example: - -```ruby -def signup - params[:user] - # => {name:"ow3ned", admin:true} - permitted_params = params.require(:user).permit(:name) - # => {name:"ow3ned"} - - @user = User.new(permitted_params) -end -``` - -In the example above, `require` is checking whether a `user` key is present or not -in the parameters, if it's not present, it'll raise an `ActionController::MissingParameter` -exception, which will be caught by `ActionController::Base` and turned into a -400 Bad Request reply. Then `permit` whitelists the attributes that should be -allowed for mass assignment. - -A good pattern to encapsulate the permissible parameters is to use a private method -since you'll be able to reuse the same permit list between different actions. - -```ruby -def signup - @user = User.new(user_params) - # ... -end - -def update - @user = User.find(params[:id] - @user.update_attributes!(user_params) - # ... -end - -private - def user_params - params.require(:user).permit(:name) - end -``` - -Also, you can specialize this method with per-user checking of permissible -attributes. - -```ruby -def user_params - if current_user.admin? - params.require(:user).permit(:name, :admin) - else - params.require(:user).permit(:name) - end -end -``` - User Management --------------- @@ -689,7 +554,6 @@ NOTE: _When sanitizing, protecting or verifying something, whitelists over black A blacklist can be a list of bad e-mail addresses, non-public actions or bad HTML tags. This is opposed to a whitelist which lists the good e-mail addresses, public actions, good HTML tags and so on. Although sometimes it is not possible to create a whitelist (in a SPAM filter, for example), _prefer to use whitelist approaches_: * Use before_action only: [...] instead of except: [...]. This way you don't forget to turn it off for newly added actions. -* Use attr_accessible instead of attr_protected. See the mass-assignment section for details * Allow <strong> instead of removing <script> against Cross-Site Scripting (XSS). See below for details. * Don't try to correct user input by blacklists: * This will make the attack work: "<sc<script>ript>".gsub("<script>", "") diff --git a/railties/lib/rails/generators/rails/migration/USAGE b/railties/lib/rails/generators/rails/migration/USAGE index af74963b01..f340ed97f2 100644 --- a/railties/lib/rails/generators/rails/migration/USAGE +++ b/railties/lib/rails/generators/rails/migration/USAGE @@ -15,15 +15,8 @@ Example: `rails generate migration AddTitleBodyToPost title:string body:text published:boolean` - This will create the AddTitleBodyToPost in db/migrate/20080514090912_add_title_body_to_post.rb with - this in the Up migration: + This will create the AddTitleBodyToPost in db/migrate/20080514090912_add_title_body_to_post.rb with this in the Change migration: add_column :posts, :title, :string add_column :posts, :body, :text add_column :posts, :published, :boolean - - And this in the Down migration: - - remove_column :posts, :published - remove_column :posts, :body - remove_column :posts, :title diff --git a/railties/lib/rails/info_controller.rb b/railties/lib/rails/info_controller.rb index fe1e25d88c..e296637f39 100644 --- a/railties/lib/rails/info_controller.rb +++ b/railties/lib/rails/info_controller.rb @@ -1,6 +1,6 @@ require 'action_dispatch/routing/inspector' -class Rails::InfoController < ActionController::Base +class Rails::InfoController < ActionController::Base # :nodoc: self.view_paths = File.expand_path('../templates', __FILE__) layout 'application' |