Updated Sep 20, 2007 by gumeson
Labels:	Phase-Deploy, Phase-Implementation

InstructionsForTheCompulsive

Detailed instructions for installing and configuring the Flux Validator

Instructions for the Compulsive

Requirements:

Prototype javascript library, version 0.5.x or greater
Scriptaculous javascript library
LowPro javascript library (installed automatically)

1) Install the Flux Validator

Simply install the Flux Validator like any other plugin.

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

2) Include the Flux Validator

To use the 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 the Flux Validator work on all forms on your site, add the following tag to the

<head>

section of your application.rhtml layout:

<%= flux_validator_for 'form' %>

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

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

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

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

<%= flux_validator_for "form.validate_me" %>

# Will validate any form with the name "registration_form"

<%= flux_validator_for "form[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.

3) Error Message Placement

In some scenarios, you may want to control where your error messages appear on the page. By default, the 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:

As a standalone tag:

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

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 form_flux_validator tag.

4) 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.

5) 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 the 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 %>

The 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

6) 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, The Flux Validator takes care of setting fields that are protected from mass assignment. This is safe because models used by the Flux Validator are never saved. So for instance, if you have the following model:

class User
  attr_protected :password
  validates_confirmation_of :password
end

The 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