Overview

The 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, but with all rendering removed.

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

1. 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 the form with user input

3. Add filters to validate and sanitize user input

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

In addition, you load 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]]).

<?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->getValues();
        $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);
?>