= Using the Validate Request Plugin

== Arguments

+validate_request+ accepts three arguments, all of which are optional:

* +valid_request_methods+ - One or more (in an array) symbols representing the
  HTTP request methods that this action supports. The default is :get.
* +param_requirements+ - A hash that describes the arguments that are required
  for this action.
* +param_options+ - A hash that describes other arguments that this action 
  will accept, but which are not required.

== Parameter Types

When specifying parameters, you get to specify the type that the value should
have. These can take several forms:

=== Basic Types

Currently, +validate_request+ only recognizes two basic types: +:integer+ and
+:text+ (or +:string+, if you prefer). Basically, no checks are done on values
of type +:text+ or +:string+. Support for more basic types could probably be
added if it's requested enough.

I decided to only support positive integers, since they're mostly what you see
in rails applications. Currently, I think it's a feature to disallow negative
numbers. Let me know if you disagree with this decision.

=== Specific Values

If you specify a string or something other than one of the basic types, then
it will be compared directly to the value. For example, the declaration
<tt>:name => 'bob'</tt> specifies that the +:name+ parameter must have a value
equal to 'bob'. This is probably only useful in the param_options hash. 

Note that you can't specify multiple possible values for the same parameter
(yet -- it's on the to-do list).

=== Nested Hashes

It's important to support nested hashes, since rails uses them frequently in
the params hash. So, you can specify them the same way as you'd expect to be
able to:

  :id => :integer, :dog => {:name => :text, :age_in_years => :integer}
  
You can nest hashes as deeply as you'd like.  

=== ActiveRecord Models

Finally, you can use descendent classes of ActiveRecord::Base (your models) as
the requirements for a parameter type. This saves you a considerable amount of
typing, and DRYs up your code by getting rid of repetition. The column names
and types will be determined by examining the model itself. So we could have
written the previous example like this:

  :id => :integer, :dog => Dog
  
Now if we add a new column to the dogs table, it's automatically supported by
both our model and our request validation.

== Handling Bad Requests

+validate_request+ will always return true or false to indicate whether the
request met the definition or not. If you don't like the default behavior of
setting <tt>flash[:error]</tt> and redirecting, you can turn those options off
(see Configuration, below), and use this return value to implement your own
behavior.

It's usually a good idea to return immediately from the current action if
+validate_request+ returns false. This is because redirects in rails do not
take effect immediately; they only happen once the action has completed. So
you'll probably need to return explicitly (as in the examples here) to avoid
executing the rest of your action in the case of a bad request.

== Configuration

By default, invalid requests will be redirected to '/', and
<tt>flash[:error]</tt> will be set with a polite error message. You can change
this behavior by setting the following class variables (for example, within
<tt>config/application.rb</tt>):

* *@@redirect_for_bad_request* - Set this to the URL to redirect to if we get
  a bad request. Set to nil if you do not want a redirect (and just want to
  test the return value of validate_request). The default is the URL '/'.

* *@@flash_error_for_bad_request* - Set this to the string that should be
  assigned to <tt>flash[:error]</tt> if we should get a bad request. Set it to
  +nil+ if you do not want <tt>flash[:error]</tt> to be set at all. The
  default is a generic yet polite error message.

== More Information

If you still have questions, it may also be worthwhile to look in the +test+
directory to see a fairly wide range of examples. You'll primarily be
interested in +validate_request_test_helper.rb+, which sets up a test model
and controller against which tests can be run, and +validate_request_test.rb+,
which makes the different calls to the test controller and checks the
responses.

Finally, feel free to submit bug reports and feature requests to the project
page at http://rubyforge.org/projects/validaterequest .

  -- Scott A. Woods <scott at westarete dot com>