ruby script/plugin install http://fluxvalidator.googlecode.com/svn/trunk/flux_validator

2) Now in your layout(s), (place in the head of the document)

<%= javascript_include_tag :defaults, 'lowpro' %>
<%= flux_validator_for 'form' %>

This will validate all forms rendered within the layout, so if placed in your application.rhtml layout, you have already setup the validator to work on all the forms on your site.

Notice: The flux_validator_for tag comes after all your other scripts and stylesheets.

3) Restart your server... and you're done!



===Detailed Instructions===


1) Include Flux Validator

To use Flux Validator, you will need to include the Prototype and Lowpro javascript libraries. Just add them to your layout if they are not already there:

<%= javascript_include_tag :defaults, 'lowpro' %>

Also, in your layout you will need to tell the Flux Validator which forms to watch. So the first argument to the flux_validator_for tag is a CSS selector. For example, to have Flux Validator work on all forms, add the following tag to the section of your layout:

<%= flux_validator_for 'form' %>

The first argument can be any valid CSS selector that references one or more form elements. So...

<%= flux_validator_for "div#content form" %>

Will validate any form contained inside a div tag with the id "content".

<%= flux_validator_for "form.validate_me" %>

Will validate any form having the class name "validate_me".

<%= flux_validator_for "form[name='registration_form']" %>

Will validate any form with the name "registration_form".

That is all you should need to do. You will now see validation error messages appear below each field while filling in your forms.

Read on to control the placement of your error messages.


2) Error Message Placement

In some scenarios, you may want to control where your error messages appear on the page. By default, Flux Validator will place error messages directly after the form field. However, you may want to group them all together, or possibly even place them all on the top of the page for some reason. This can easily be accomplished with the aptly named error_messages_on helper, which displays a list of error messages for a field.

This helper is not to be confused with the singular error_message_on or the error_messages_for helpers built into rails.

Just like other form_helper fields, the error_messages_on tag can take on two different forms:

1. As a standalone tag:

<%= text_field :user, :login %>
<%= error_messages_on :user, :login %>

2. Or along with form_for (and fields_for):

<% form_for(:user, :url => users_path) do |f| %>
<%= f.text_field :login %>
<%= f.error_message_on :login %>
<% end %>

The explicit use of the error_messages_on tag in your view will also allow your validation error messages appear after an invalid form has been submitted. For that reason, it is probably good practice to use it. In fact, this helper can also be used as a stand-alone tag to simply display validation error messages on forms that are not being watched by the flux_validator_for tag.


3) Customizing look and feel

Changing the default style of your Flux Validator error messages is easy. Simply modify the file flux_validator.css located in the public/stylesheets directory.


4) Custom field names

Read on if you want to know what's under the hood...

The Flux Validator is smart and will try to guess what models need to be validated by looking at the param names coming in from the form. So for instance, if your form has a field named "user[login]", then the Flux Validator will try to use the model class called User to validate that field.

All this works very nicely with the way Rails automatically labels your fields when using the form_for tag, or when just following standard Rails conventions:

<%= text_field :user, :login %>

However, if you give your fields names that differ from the name of your model class, you will need give Flux Validator some hints. Let's say you decide to label all your User fields with "my_user" instead of "user" like this:

<%= text_field :my_user, :login %>

Flux Validator needs to be told to try validating those my_user fields against the User model and not a model named MyUser. This can easily be done by defining an alias that points to the real model. Just place your alias in the same controller your form submits to, like this:

class UsersController < ApplicationController
	alias_model :my_user, :user
end

5) Initializing your own models

If for some reason you need to initialize your own models before they are validated, you must override the validate_form method in the same controller that your form submits to. For instance, you may want complete control of your param assignments:

class UsersController < ApplicationController
	def validate_form
	  @user = User.new
	  @user.name = params[:user][:first_name]
	  @user.email = params[:user][:email]
	  super
	end
end

This can also be handy when you need to setup your model before assigning params, as required with the following User model:

class User
	cattr_accessor :password_required
	validates_presence_of :password, :if => password_required
end

class UsersController < ApplicationController
	def validate_form
	  @user = User.new
	  @user.password_required = true
	  @user.attributes = params[:user]
	  super
	end
end

You can also override the validate_(action_name)_form method if each action in your controller requires a different model setup:

class UsersController < ApplicationController
	def validate_create_form
	  @user = User.new
	  @user.password_required = true # Required on create
	  @user.attributes = params[:user]
	  super
	end
	
	def validate_edit_form
	  @user = User.new
	  @user.password_required = false # Not required on edit
	  @user.attributes = params[:user]
	  super
	end
end

IMPORTANT: Don't forget to call super at the end of all your validate_form methods or they won't work!

Also remember, you are responsible for initializing any model objects you create inside an overridden validate_form method. So fields protected by attr_protected and attr_accessible need to be set manually.

GOTCHA: It is not necessary to override validate_form just because you have fields that are protected from mass assignment. By default, Flux Validator takes care of setting fields that are protected from mass assignment. This is safe because models used by Flux Validator are never saved. So for instance, if you have the following model:

class User
	attr_protected :password
	validates_confirmation_of :password
end

Flux Validator would automatically create a model called @user and initialize @user.password with params[:user][:password] even though password is attr_protected. However, if you override validate_form and create your own @user model, you must manually initialize all fields that are protected from mass assignment, like this:

class UsersController < ApplicationController
	def validate_form
	  @user = User.new
	  @user.attributes = params[:user]
	  @user.password = params[:user][:password]
	  super
	end
end

There is currently no advanced documentation for this plugin.