<markdown>
=================
Populating Values
=================

If you want to provide a default value, just put it in the 'value' key
for that element, like so:

{{code: php
    $info = array(
      'type'  => 'text',
      'label' => 'Email Address:',
      'value' => 'nobody@example.com',
    );

    $form->setElement('user_email', $info);
}}

However, we'd like to automatically override the defaults with submitted
values. Let's extend the script so that it adds user input from POST
submissions. This is very easy to do: just add a
[[Solar_Form::populate()]] call before displaying the form.

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

    $form->populate();

    // ... create a Solar_View object, assign, and display.
}}

The [[Solar_Form::populate()]] method will examine the request for a
POST variable called `user_email` and put its value into the $form
object for you. If the user entered "nobody@example.com" as the address,
the view script would display something like this:

{{code: html
    <!-- ... -->
    <dt><label for="user_email">Email Address:</label></dt>
    <dd><input type="text" id="user_email" name="user_email" value="nobody@example.com" />
    <!-- ... -->
}}


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

The [[Solar_Form::populate()]] method takes values from the population source
and imports them into their corresponding form elements.

* If the source is null (the default), then the population source is the
  HTTP request (c.f. [[Solar_Request::HomePage | Solar_Request]] and the
  key is determined based on the [[Solar_Form::$attribs]] `'method'`
  value.  If 'get', then [[Solar_Request::get()]]; if 'post', then
  [[Solar_Request::post()]] is used.

* If the source is an array, then the array key-value pairs are
  recursively mapped to form element names and the values are imported
  into those elements.

* If the source is an object, then the object is recast as an array, and
  the properties are recursively mapped to form element names and the
  values are imported into those elements.

If you populate more than once, the later populations will reset and
overwrite previous populations.

Population Sources
==================

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]
    books[author]
    books[title]

All population sources are treated as arrays; if not an array to begin
with (as in the case of objects) they will be recast to arrays. Those
array elements would look like this in order to map into the above form
elements:

{{code: php
    $source = 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'
        ),
    );
}}
</markdown>