================= Set Form Elements ================= 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". ---------------------- Create the Form Object ---------------------- First, we create the form object itself: {{code: php require_once 'Solar.php'; Solar::start('/path/to/config/Solar.config.php'); $form = Solar::factory('Solar_Form'); }} ------------ Add Elements ------------ 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:". {{code: php $form->setElement('user_email', array( 'type' => 'text', 'label' => 'Email Address:' )); }} Display the Form ================ 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::HomePage | Solar_View]] and its related [[Solar_View_Helper_Form::HomePage | 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.) {{code: 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. {{code: html

Email Address:

Action:

}} ----------------- Extended Examples ----------------- 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. Appending An Element ==================== 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. {{code: 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: {{code: html }} Appending An Element As Part Of An Array ======================================== 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). {{code: 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: {{code: html }} You can get the same effect by giving the element an array-like name to begin with... {{code: 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: {{code: html }} 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: {{code: 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): {{code: html Alabama California }} 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' ... {{code: php $form->setElements($elements, 'contact'); }} ... which would lead to output something like this: {{code: html Alabama California }} ------------------------ Adding Multiple Elements ------------------------ Use the [[Solar_Form::setElements()]] method to append multiple elements to a form at one time. For example: {{code: 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): {{code: html Alabama California }} 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' ... {{code: php $form->setElements($elements, 'contact'); }} ... which would lead to output something like this: {{code: html Alabama California }}