Railsify!

Flux Validator

Filed under Utilities, ActiveRecord, and Miscellaneous
Developed by Peter Gumeson (gumeson)

Flux Validator - Ajax Form Validation plugin for Rails
Project Home: http://fluxvalidator.googlecode.com

version 0.9.0


Flux Validator is a handy, Ajax based form validation plugin for Rails.
The Flux Validator auto-magically validates forms against their models
and displays a list of error messages for each invalid field, all without
a page refresh. The Flux Validator is what makes real-time Rails form
validation possible!

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

NOTE: Flux Validator has not been fully tested on edge rails

Instructions for the Impulsive


1) Install Flux Validator

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


2) Now in your layout(s),

  <head>
    <%= javascript_include_tag :defaults, 'lowpro' %>
    <%= flux_validator_for 'form' %>
  </head>
  
  Notice: The flux_validator_for tag comes after all your
  other scripts and stylesheets.

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

Instructions for the Compulsive


1) Install Flux Validator

  Simply install Flux Validator like any other plugin.
  $ ./script/plugin install http://fluxvalidator.googlecode.com/svn/trunk/flux_validator


2) 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 <head> 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.
  

3) 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 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 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


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,
  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.name = params[:user][:password]
      super
    end
  end

Last updated: September 23, 2007 15:54

Installing this Plugin

Flux Validator

version 0.9.0

Instructions for the Impulsive

Instructions for the Compulsive