<markdown>
=================
Retrieving Values
=================

-------------
Short Example
-------------

Now that you have [[Solar_Form::populate() | populated]] and
[[Solar_Form::validate() | validated]] the form, you will want to pull the
values out of the form and do something with them. You do this with the
[[Solar_Form::values()]] method.

{{code: php
    // ... start Solar, create the form object, set elements,
    // and then:

    // populate the form with user input
    $form->populate();

    // discover the request environment
    $request = Solar_Registry::get('request');
    
    // what was the submission request?
    $process = $request->post('process'); 

    // process a 'Save' submission
    if ($process == 'Save') {
    
        if ($form->validate();) {
            $values = $form->values();
            // then insert $values['user_email'] into a database,
            // or forward on to another page, or whatever.
        }
    }
}}

Note that the array returned by [[Solar_Form::values()]] will match the
array of POST variables in the request, so if you had sub-arrays in the
form, you will get sub-arrays from [[Solar_Form::values()]]. Wise use of
array key names will help you keep track of what information goes in
which table, and so on.

--------------
Longer Example
--------------

After a form is submitted, and values have been
[[Solar_Form::populate() | populated]] and
[[Solar_Form::validate() | validated]], you will need to retrive the
validated user input. You do so with the Solar_Form::values()
method.

Let's say we have a set of elements that combine plain and array-based
names, and in two different arrays:

    id
    user[email]
    user[name]
    contact[street]
    contact[city]
    contact[state]
    contact[zip]

After the form has been populated and validated, a call to values()
would result in something like this:

{{code: php
    // create the form
    $form = Solar::factory('Solar_Form');

    // set up the elements
    // ...

    // now populate, validate, and retrieve values
    $form->populate();
    $valid = $form->validate();

    if ($valid) {

        $values = $form->values();
    
        /*
        Now the $values array looks something like this:
        $values = array(
            'id' => '12345',
            'user' => array(
                'email' => 'nobody@example.com',
                'name'  => 'Nobody Example',
            ),
            'contact' => array(
                'street' => '101 Main Street',
                'city'   => 'Beverly Hills',
                'state'  => 'CA',
                'zip'    => '90210'
            ),
        );
        */
    }
}}

You can also call [[Solar_Form::values()]] with one parameter, the "group" of
elements you want to retrieve.

{{code: php
    $user  = $form->values('user');
    $contact = $form->values('contact');
    
    /*                                                            
    Now the arrays look something like this:
    
    $user = array(
        'email' => 'nobody@example.com',
        'name'  => 'Nobody Example',
    );
    
    $contact = array(
        'street' => '101 Main Street',
        'city'   => 'Beverly Hills',
        'state'  => 'CA',
        'zip'    => '90210'
    );
    */
}}
</markdown>