Permalink
Browse files

update AC::StrongParameters documentation

  • Loading branch information...
1 parent f8478a7 commit 2417218476ce607471baf364e8f1ce660dbf761d Francesco Rodriguez committed Sep 20, 2012
Showing with 53 additions and 8 deletions.
  1. +53 −8 actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -25,7 +25,7 @@ def initialize(param) # :nodoc:
# and thus prevent accidentally exposing that which shouldn’t be exposed.
# Provides two methods for this purpose: #require and #permit. The former is
# used to mark parameters as required. The latter is used to set the parameter
- # as permitted and limit which attributes should be allowed for mass updating.
+ # as permitted and limit which attributes should be allowed for mass updating.
#
# params = ActionController::Parameters.new({
# person: {
@@ -43,13 +43,13 @@ def initialize(param) # :nodoc:
# Person.first.update_attributes!(permitted)
# # => #<Person id: 1, name: "Francesco", age: 22, role: "user">
#
- # It provides a <tt>permit_all_parameters</tt> option that
- # controls the top-level behaviour of new instances. If it's +true+,
- # all the parameters will be permitted by default. The default value
- # for <tt>permit_all_parameters</tt> option is +false+.
+ # It provides a +permit_all_parameters+ option that controls the top-level
+ # behaviour of new instances. If it's +true+, all the parameters will be
+ # permitted by default. The default value for +permit_all_parameters+
+ # option is +false+.
#
# params = ActionController::Parameters.new
- # params.permitted? # => false
+ # params.permitted? # => false
#
# ActionController::Parameters.permit_all_parameters = true
#
@@ -269,6 +269,46 @@ def each_element(object)
end
end
+ # == Strong Parameters
+ #
+ # It provides an interface for proctecting attributes from end-user
+ # assignment. This makes Action Controller parameters are forbidden
+ # to be used in Active Model mass assignmets until they have been
+ # whitelisted.
+ #
+ # In addition, parameters can be marked as required and flow through a
+ # predefined raise/rescue flow to end up as a 400 Bad Request with no
+ # effort.
+ #
+ # class PeopleController < ActionController::Base
+ # # This will raise an ActiveModel::ForbiddenAttributes exception because
+ # # it's using mass assignment without an explicit permit step.
+ # def create
+ # Person.create(params[:person])
+ # end
+ #
+ # # This will pass with flying colors as long as there's a person key in the
+ # # parameters, otherwise it'll raise a ActionController::MissingParameter
+ # # exception, which will get caught by ActionController::Base and turned
+ # # into that 400 Bad Request reply.
+ # def update
+ # redirect_to current_account.people.find(params[:id]).tap { |person|
+ # person.update_attributes!(person_params)
+ # }
+ # end
+ #
+ # private
+ # # Using a private method to encapsulate the permissible parameters is
+ # # just a good pattern since you'll be able to reuse the same permit
+ # # list between create and update. Also, you can specialize this method
+ # # with per-user checking of permissible attributes.
+ # def person_params
+ # params.require(:person).permit(:name, :age)
+ # end
+ # end
+ #
+ # See ActionController::Parameters.require and ActionController::Parameters.permit
+ # for more information.
module StrongParameters
extend ActiveSupport::Concern
include ActiveSupport::Rescuable
@@ -279,12 +319,17 @@ module StrongParameters
end
end
+ # Returns a new ActionController::Parameters object that
+ # has been instantiated with the <tt>request.parameters</tt>.
def params
@_params ||= Parameters.new(request.parameters)
end
- def params=(val)
- @_params = val.is_a?(Hash) ? Parameters.new(val) : val
+ # Assigns the given +value+ to the +params+ hash. If +value+
+ # is a Hash, this will create an ActionController::Parameters
+ # object that has been instantiated with the given +value+ hash.
+ def params=(value)
+ @_params = value.is_a?(Hash) ? Parameters.new(value) : value
end
end
end

0 comments on commit 2417218

Please sign in to comment.