<markdown>
========
Overview
========

The [[Class::Solar_Form | ]] class helps you create a data structure designed
to represent an XHTML form; it automates data population, filtering, and
validation for you.

While this class does not output the form (as that is the job of a view
or presentation layer), it does allow you to build "hints" as to how the
elements should be presented; you then pass the object instance into
your view, which can take those "hints" any way it likes. These "hints"
are called the form [[descriptor array]].

In addition, the class will draw in data from an array (typically POST
variables), validate the newly-populated structure against filters and
rules that you sets up, and set feedback messages based on which
elements were valid and which were not. In many ways, Solar_Form is a
cousin to [HTML_QuickForm](http://pear.php.net/HTML_QuickForm), but with
all rendering removed.

In general, the basic form processing cycle goes like this:

1. [[Set_form_elements | Set elements]] in a form object, including:

    * The element description (name, type, etc)

    * Filters to apply to the user input for this element

    * Validation to perform on the user input

2. [[Populate_values | Populate the form]] with user input

3. Add [[filters]] to validate and sanitize user input

4. [[Retrieve_values | Retrieve user input]] and perform further actions
   (save to a database, etc)

In addition, you load [[Auto_load_elements | load elements from other sources]],
build [[localized forms]], and [[add feedback]] messages of your own.

-------------
Quick Example
-------------

Here's a quick example to whet your curiosity. Note that we use a small bit of
localization (although a real form would have [[Localized_forms | everything
localized]]).

{{code: php
    require_once 'Solar.php';
    Solar::start('/path/to/config/Solar.config.php');

    // ---------------------------------------------------------------------
    // 
    // Build the form
    // 

    $form = Solar::factory('Solar_Form');
    $form->setElements(array(
        'user[handle]' => array(
            'type'     => 'text',
            'label'    => 'Your Username:',
            'require'  => true,
            'filters'  => array(
                'validateAlnum',
            ),
        ),
        'user[email]'  => array(
            'type'     => 'text',
            'label'    => 'Your Email Address:',
            'require'  => true,
            'filters'  => array(
                'validateEmail',
            ),
        ),
        'process' => array(
            'type'     => 'submit',
            // use a localized button value
            'value'    => 'save',
        ),
    ));

    // ---------------------------------------------------------------------
    // 
    // Process submissions
    // 

    // discover the request environment
    $request = Solar_Registry::get('request');
    
    // get the requested process
    $process = $request->post('process');
    
    // handle processes based on the localized button values
    if ($process == 'save') {
    
        // populate the form with submitted values
        $form->populate();
    
        // filter (validate and sanitize) the user input
        $is_valid = $form->validate();
        if ($is_valid) {
        
            // get the validated and filtered values...
            $values = $form->values();
            $user = $values['user'];
        
            // ... and save $user to a database table.
            // $table->save($user);
        }
    }

    // ---------------------------------------------------------------------
    // 
    // Output the form (with auto-generated feedback)
    // 

    // get a view object, assign the form to it, and display.
    $view = Solar::factory('Solar_View');
    echo $view->form($form);
}}
</markdown>