Let's start with a very simple example form, one that asks for one piece of input: an email address. We'll also need a submit button called "Save".
First, we create the form object itself:
<?php
require_once 'Solar.php';
Solar::start('/path/to/config/Solar.config.php');
$form = Solar::factory('Solar_Form');
?>As it stands now, the form has no elements. We want to set a "text" element named 'user_email' that uses a label of "Email Address:".
<?php
$form->setElement('user_email', array(
'type' => 'text',
'label' => 'Email Address:'
));
?>Just to show we're on the right track, let's display the form output. (This doesn't populate the values or validate the input, it just displays for now.)
We need to use Solar_View and its related form helper. This is because Solar_Form does not perform output functions, only collection and processing.
Here is a combined controller and view extended from the earlier code. (Normally you would separate your controller and view, but this example is about instant feedback.)
<?php
// Start Solar
require_once 'Solar.php';
Solar::start('/path/to/config/Solar.config.php');
// Create a Form object
$form = Solar::factory('Solar_Form');
// Set the "user_email" element
$form->setElement('user_email', array(
'type' => 'text',
'label' => 'Email Address:'
));
// Set a submit button called "process" with a value of "Save"
$form->setElement('process', array(
'type' => 'submit',
'label' => 'Action:',
'value' => 'Save',
));
// Create a view object and output the form
// using the form() helper
$view = Solar::factory('Solar_View');
echo $view->form($form);
?>The output will look something like this; note that the form helper uses semantic markup, and can by styled using CSS.
<form action="/test/index.php" method="post" enctype="multipart/form-data">
<dl>
<dt><label for="user_email">Email Address:</label></dt>
<dd><input type="text" id="user_email" name="user_email" value="" /></dd>
<dt><label for="process">Action:</label></dt>
<dd><input type="submit" id="process" name="process" value="Save" />
</dl>
</form>This method appends one element to the form; if the element name already exists (or if the element name and element array name already exist), the element is reset to reflect the values passed into the method.
All elements are placed into the Solar_Form::$elements public property; if you wish to manipulate that property directly, you may, but this method is generally more reliable.
To append one element to the form, you need three things: a Solar_Form object, a name for your element, and a description of the element hint information.
<?php
require_once 'Solar.php';
Solar::start('/path/to/config/Solar.config.php');
// create a form object
$form = Solar::factory('Solar_Form');
// we'll call our element 'email_addr'
$name = 'email_addr';
// describe the element information hints
$info = array(
// the XHTML element type
'type' => 'text',
// a short, human-readable label
'label' => 'Your email address:',
// a longer description for tooltips, etc.
'descr' => 'Your main email address, so we can contact you.',
// the default value before any new user input
'value' => null,
// what other XHTML attributes should be used for this
// element?
'attribs' => array(
'size' => 32,
'maxlength' => 64,
),
// an array of Solar_Filter calls to apply to user-input.
'filters' => array(
'validateEmail',
),
);
// now append the element to the form
$form->setElement($name, $info);
?>Remember that Solar_Form does not generate any output; instead, it is used as a set of "hints" for your template or view. With Solar_View, all of the hints are honored. Having said that, the above element name and description should generate something like the following output:
<input type="text" name="email_addr" value="" size="32" maxlength="64" />Sometimes you will want an element to be part of a larger array within a form; this is useful when the user input will be used in multiple different tables or data sources, and you need to know which elements go with which source. Using the above 'email_addr' element as an example, we can specify that the element should belong to an array called 'contact' (perhaps representing a contacts table).
<?php
// start Solar, create a form object,
// name the element, describe its info,
// and then:
$form->setElement($name, $info, 'contacts');
?>Now the generated element output should look something like this:
<input type="text" name="contacts[email_addr]" value="" size="32" maxlength="64" />You can get the same effect by giving the element an array-like name to begin with...
<?php
// start Solar, create a form object.
// name the element as part of an array:
$name = 'contacts[email_addr]';
// describe the info, and then:
$form->setElement($name, $info);
?>This will generate the same output, to wit:
<input type="text" name="contacts[email_addr]" value="" size="32" maxlength="64" />Note that when you add an element as part of an array, its name becomes the array-like name; thus, you will have to refer to the "email_addr" element as "contacts[email_addr]".
Also note that the array-like name is in the format for the XHTML form element, not a PHP array; that is, "contacts[email_addr]" and not "contacts['email_addr']" (pay attention to the lack of single quotes).
Use this method to append multiple elements to a form at one time.
The associative array of elements is a series of key-value pairs where the key is the element name, and the value is an element information array (see the Solar_Form::setElement() method for more on the info key-value pairs).
For example:
<?php
require_once 'Solar.php';
Solar::start('/path/to/config/Solar.config.php');
$form = Solar::factory('Solar_Form');
$elements = array(
'addr' => array(
'type' => 'text',
'label' => 'Street Address:',
'value' => '101 Main Street'
),
'city' => array(
'type' => 'text',
'label' => 'City:',
'value' => 'Beverly Hills'
),
'state' => array(
'type' => 'select',
'label' => 'State:',
'value' => 'CA',
'options' => array('AL' => 'Alabama', 'CA' => 'California'),
),
'zip' => array(
'type' => 'text',
'label' => 'ZIP:',
'value' => '90210',
'attribs' => array('maxlength' => 5, 'size' => 5),
),
);
$form->setElements($elements);
?>This code will hint an output generator to create a form something like this (labels and layout are excluded for the sake of brevity):
<input type="text" name="addr" value="101 Main Street" />
<input type="text" name="city" value="Beverly Hills" />
<select name="state">
<option value="AL" label="Alabama">Alabama</option>
<option value="CA" label="California" selected="selected">California</option>
</select>
<input type="text" name="zip" value="90210" size="5" maxlength="5" />As with Solar_Form::setElement(), you can specify that each element become part of an array within the form by adding a second parameter. For example, with the above set of elements, you can make them part of an array called 'contact' ...
<?php
$form->setElements($elements, 'contact');
?>... which would lead to output something like this:
<input type="text" name="contact[addr]" value="101 Main Street" />
<input type="text" name="contact[city]" value="Beverly Hills" />
<select name="contact[state]">
<option value="AL" label="Alabama">Alabama</option>
<option value="CA" label="California" selected="selected">California</option>
</select>
<input type="text" name="contact[zip]" value="90210" size="5" maxlength="5" />Use the Solar_Form::setElements() method to append multiple elements to a form at one time. For example:
<?php
require_once 'Solar.php';
Solar::start('/path/to/config/Solar.config.php');
$form = Solar::factory('Solar_Form');
$elements = array(
'addr' => array(
'type' => 'text',
'label' => 'Street Address:',
'value' => '101 Main Street'
),
'city' => array(
'type' => 'text',
'label' => 'City:',
'value' => 'Beverly Hills'
),
'state' => array(
'type' => 'select',
'label' => 'State:',
'value' => 'CA',
'options' => array('AL' => 'Alabama', 'CA' => 'California'),
),
'zip' => array(
'type' => 'text',
'label' => 'ZIP:',
'value' => '90210',
'attribs' => array('maxlength' => 5, 'size' => 5),
),
);
$form->setElements($elements);
?>The associative array of elements is a series of key-value pairs where the key is the element name, and the value is an element information array (see the Solar_Form::setElement() method for more on the info key-value pairs).
This code will hint an output generator to create a form something like this (labels and layout are excluded for the sake of brevity):
<input type="text" name="addr" value="101 Main Street" />
<input type="text" name="city" value="Beverly Hills" />
<select name="state">
<option value="AL" label="Alabama">Alabama</option>
<option value="CA" label="California" selected="selected">California</option>
</select>
<input type="text" name="zip" value="90210" size="5" maxlength="5" />As with Solar_Form::setElement(), you can specify that each element become part of an array within the form by adding a second parameter. For example, with the above set of elements, you can make them part of an array called 'contact' ...
<?php
$form->setElements($elements, 'contact');
?>... which would lead to output something like this:
<input type="text" name="contact[addr]" value="101 Main Street" />
<input type="text" name="contact[city]" value="Beverly Hills" />
<select name="contact[state]">
<option value="AL" label="Alabama">Alabama</option>
<option value="CA" label="California" selected="selected">California</option>
</select>
<input type="text" name="contact[zip]" value="90210" size="5" maxlength="5" />