# sfFabulous Plugin - Form Ajax Binder for protoculous #


The `sfFabulousPlugin` is a symfony plugin that provides an ajax validation mecanism for the new sfForm (symfony 1.1 and 1.2).

This plugin comes with:

  * A generic method to Dispatch, Bind & Valid forms and extract the errors
  * A piece of javascript/css to handle the JSON response and interact with the form 
  * A helper to provide a Quick & easy integration
  
## Installation ##

  * Install the plugin

         symfony plugin-install http://plugins.symfony-project.com/sfFabulousPlugin

  * Enable the module in your `settings.yml` 
  
        [yml]
         all:
           .settings:
             enabled_modules:      [default, ..., sfFabulous]

  * Make the helper as standard in your `settings.yml` (optional, in case you want to use it anywhere)
  
        [yml]
          all:
            .settings:
              standard_helpers:       [I18N, ..., Fabulous]
  
  * Regenerate relative symbolic links in the web/ directory (for web elements such as JS and CSS).
  
          symfony plugin:publish-assets
  
  * Clear your cache
 
          symfony cc
 

## Making it work! ##

Making the plugin work, is easy as:

          <?php echo fabulous_form_tag(url_for('@somewhere'), $html_options = array(), $form, $options_fabulous = array()); ?>


The helper use the standard $form->renderFormTag(). All you need is to had two extra params __$form__ wich is your form object and a special options array __$options_fabulous__ :

          * 'show_required_field'  : show required fields (default: false)
          * 'show_masks' : bind fields & masks (default: false)
          * 'complete_func' : javascript function to execute if form is valid (default: this.form.submit()). For example, if you want to submit your form via ajax: array('complete_func'=>'new Ajax.Updater("container...)

## Dependencies ##

Form Ajax Binder for protoculous (sfFabulous) needs:
 
  * sfProtoculousPlugin (bundle by default with sf1.2). Any other prototype (>1.6.XX) / scriptaculous (>1.8.XX) installation is fine.
  * An [dwCryptPlugin](http://trac.symfony-project.com/trac/wiki/dwCryptPlugin "dwCryptPlugin"). Used to crypt form informations.
  
  

## Features ##

 * Auto focus the first error field
 * Auto enabling/disabling when submiting the form
 * Auto transform the text label for required fields (ie. Username* / Username (require))
 * Insert a div error and change the class of the error field (ie red border input)
 * Errors sent by HTTP headers (using X-JSON)  
 * Errors sent with the json format (light => performances) and auto eval by Prototype
 * Multi states submit buttons
  
## Demo ##

I'll post a link soon.

## Todo ##

 * Wait for scriptaculous 1.8.3. effect.shake impossible due to a callback bug. For more info, see: http://prototype.lighthouseapp.com/projects/8887/tickets/41-effect-shake-afterfinish-not-supported
 * Provide a way to ease conf
 * Render global errors
 * Implement prototype masks / widgets (sfWidgetFormPhoneNumber -> js phone mask). 
 
 ### Note: this release is in beta and is not recommended for production.  ###