From 93ef857fbc93eb7f5970315624f06b84d65564c4 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Wed, 19 Sep 2012 20:53:34 -0500 Subject: update AC::Parameters documentation [ci skip] --- .../action_controller/metal/strong_parameters.rb | 150 ++++++++++++++++++++- 1 file changed, 149 insertions(+), 1 deletion(-) (limited to 'actionpack') diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb index 91161aec4f..3379bcfc98 100644 --- a/actionpack/lib/action_controller/metal/strong_parameters.rb +++ b/actionpack/lib/action_controller/metal/strong_parameters.rb @@ -19,27 +19,143 @@ module ActionController end end + # == Action Controller Parameters + # + # Allows to choose which attributes should be whitelisted for mass updating + # 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. + # + # params = ActionController::Parameters.new({ + # person: { + # name: 'Francesco', + # age: 22, + # role: 'admin' + # } + # }) + # + # permitted = params.require(:person).permit(:name, :age) + # permitted # => {"name"=>"Francesco", "age"=>22} + # permitted.class # => ActionController::Parameters + # permitted.permitted? # => true + # + # Person.first.update_attributes!(permitted) # => # + # + # 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 + # + # ActionController::Parameters.permit_all_parameters = true + # + # params = ActionController::Parameters.new + # params.permitted? # => true + # + # ActionController::Parameters is inherited from + # ActiveSupport::HashWithIndifferentAccess, this means + # that you can fetch values using either :key or "key". + # + # params = ActionController::Parameters.new(key: 'value') + # params[:key] # => "value" + # params["key"] # => "value" class Parameters < ActiveSupport::HashWithIndifferentAccess cattr_accessor :permit_all_parameters, instance_accessor: false - attr_accessor :permitted + attr_accessor :permitted # :nodoc: alias :permitted? :permitted + # Returns a new instance of ActionController::Parameters. + # Also, sets the +permitted+ attribute to the default value of + # ActionController::Parameters.permit_all_parameters. + # + # class Person + # include ActiveRecord::Base + # end + # + # params = ActionController::Parameters.new(name: 'Francesco') + # params.permitted? # => false + # Person.new(params) # => ActiveModel::ForbiddenAttributesError + # + # ActionController::Parameters.permit_all_parameters = true + # + # params = ActionController::Parameters.new(name: 'Francesco') + # params.permitted? # => true + # Person.new(params) # => # def initialize(attributes = nil) super(attributes) @permitted = self.class.permit_all_parameters end + # Sets the +permitted+ attribute to +true+. This can be used to pass + # mass assignment. Returns +self+. + # + # class Person < ActiveRecord::Base + # end + # + # params = ActionController::Parameters.new(name: 'Francesco') + # params.permitted? # => false + # Person.new(params) # => ActiveModel::ForbiddenAttributesError + # params.permit! + # params.permitted? # => true + # Person.new(params) # => # def permit! @permitted = true self end + # Ensures that a parameter is present. If it's present, returns + # the parameter at the given +key+, otherwise raises an + # ActionController::ParameterMissing error. + # + # ActionController::Parameters.new(person: { name: 'Francesco' }).require(:person) + # # => {"name"=>"Francesco"} + # + # ActionController::Parameters.new(person: nil).require(:person) + # # => ActionController::ParameterMissing: key not found: person + # + # ActionController::Parameters.new(person: {}).require(:person) + # # => ActionController::ParameterMissing: key not found: person def require(key) self[key].presence || raise(ParameterMissing.new(key)) end + # Alias of #require. alias :required :require + # Returns a new ActionController::Parameters instance that + # includes only the given +filters+ and sets the +permitted+ for the + # object to +true+. This is useful for limiting which attributes + # should be allowed for mass updating. + # + # params = ActionController::Parameters.new(user: { name: 'Francesco', age: 22, role: 'admin' }) + # permitted = params.require(:user).permit(:name, :age) + # permitted.permitted? # => true + # permitted.has_key?(:name) # => true + # permitted.has_key?(:age) # => true + # permitted.has_key?(:role) # => false + # + # You can also use +permit+ on nested parameters, like: + # + # params = ActionController::Parameters.new({ + # person: { + # name: 'Francesco', + # age: 22, + # pets: [{ + # name: 'Purplish', + # category: 'dogs' + # }] + # } + # }) + # + # permitted = params.permit(person: [ :name, { pets: [ :name ] } ]) + # permitted.permitted? # => true + # permitted[:person][:name] # => "Francesco" + # permitted[:person][:age] # => nil + # permitted[:person][:pets][0][:name] # => "Purplish" + # permitted[:person][:pets][0][:category] # => nil def permit(*filters) params = self.class.new @@ -68,20 +184,52 @@ module ActionController params.permit! end + # Returns a parameter for the given +key+. If not found, + # returns +nil+. + # + # params = ActionController::Parameters.new(person: { name: 'Francesco' }) + # params[:person] # => {"name"=>"Francesco"} + # params[:none] # => nil def [](key) convert_hashes_to_parameters(key, super) end + # Returns a parameter for the given +key+. If the +key+ + # can't be found, there are several options: With no other arguments, + # it will raise an ActionController::ParameterMissing error; + # if more arguments are given, then that will be returned; if a block + # is given, then that will be run and its result returned. + # + # params = ActionController::Parameters.new(person: { name: 'Francesco' }) + # params.fetch(:person) # => {"name"=>"Francesco"} + # params.fetch(:none) # => ActionController::ParameterMissing: key not found: none + # params.fetch(:none, 'Francesco') # => "Francesco" + # params.fetch(:none) { 'Francesco' } # => "Francesco" def fetch(key, *args) convert_hashes_to_parameters(key, super) rescue KeyError raise ActionController::ParameterMissing.new(key) end + # Returns a new ActionController::Parameters instance that + # includes only the given +keys+. If the given +keys+ + # don't exist, returns an empty hash. + # + # params = ActionController::Parameters.new(a: 1, b: 2, c: 3) + # params.slice(:a, :b) # => {"a"=>1, "b"=>2} + # params.slice(:d) # => {} def slice(*keys) self.class.new(super) end + # Returns an exact copy of the ActionController::Parameters + # instance. +permitted+ state is kept on the duped object. + # + # params = ActionController::Parameters.new(a: 1) + # params.permit! + # params.permitted? # => true + # copy_params = params.dup # => {"a"=>1} + # copy_params.permitted? # => true def dup super.tap do |duplicate| duplicate.instance_variable_set :@permitted, @permitted -- cgit v1.2.3