#summary Detailed instructions for installing and configuring the Flux Validator #labels Phase-Deploy,Phase-Implementation =Instructions for the Compulsive= ===Requirements:=== * Prototype javascript library, version 0.5.x or greater * Scriptaculous javascript library * [http://svn.danwebb.net/external/lowpro/tags/rel-0.4/dist/ 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 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 }}}