root/tags/RELEASE_0_9_0B1/examples/example_api_factory_detailed.php

<?php
/**
 * Example that shows the usage of the patForms factory calls
 * and its api to handle a form's elements. Detailed version
 * which shows the extended methods and manual creation of
 * elements.
 * 
 * $Id$
 *
 * @access        public
 * @package        patForms
 * @subpackage    Examples
 * @author        Sebastian Mordziol <argh@php-tools.net>
 * @license        LGPL, see license.txt for details
 * @link        http://www.php-tools.net
 */

    /**
     * Main examples prepend file, needed *only* for the examples framework!
     */
    include_once 'patExampleGen/prepend.php';
    $exampleGen->displayHead( 'Example' );

    
    // EXAMPLE START ------------------------------------------------------

    /**
     * main patForms class
     */
    require_once $neededFiles['patForms'];
    
    /**
     * patErrorManager class
     */
    require_once $neededFiles['patErrorManager'];


    // username element attribute collection
    $username    =    array(
            "required"        =>    "yes",
            "display"        =>    "yes",
            "edit"            =>    "yes",
            "label"            =>    "Username",
            "description"    =>    "Enter your username here. Maximum length: [ELEMENT_MAXLENGTH]",
            "default"        =>    "argh",
            "maxlength"        =>    "15",
            "minlength"        =>    "4",
            "title"            =>    "Username",
    );
    
    // password element attribute collection
    $password    =    array(
            "type"            =>    "password",
            "required"        =>    "yes",
            "display"        =>    "yes",
            "edit"            =>    "yes",
            "label"            =>    "Password",
            "description"    =>    "Enter your password here. Maximum length: [ELEMENT_MAXLENGTH]",
            "maxlength"        =>    "15",
            "minlength"        =>    "4",
            "title"            =>    "Password",
    );

    // create the form - static function call, creates a new
    // patForms object.
    $form    =&    patForms::createForm();
    
    // set the form's name (needed to generate the form tag itself).
    $form->setAttribute( 'name', 'myForm' );

    // create the needed elements via the patForms factory
    // using the attribute collections above
    $el1 = $form->createElement( "user", "String", $username );
    $el2 = $form->createElement( "pass", "String", $password );
    
    // now we can add our element objects to the form
    $form->addElement( $el1 );
    $form->addElement( $el2 );

    // create the needed renderer so patForms knows how to
    // display the elements. In this case the array renderer
    // is used, wich returns all serialized elements in an array.
    $renderer    =&    patForms::createRenderer( "Array" );
    
    // give patForms the array renderer
    $form->setRenderer( $renderer );
    
    // serialize the elements using the array renderer - in this
    // array are contained all serialized elements along with their
    // attribute collection for easy access. You decide where and
    // what to display.
    $elements = $form->renderForm();
    
    
    // ERROR DISPLAY ------------------------------------------------------

    // check if form has been submitted
    if( isset( $_POST['save'] ) )
    {
        // tell the form it has been submitted
        $form->setSubmitted( true );
        
        // validate the form - if the validation fails, this returns
        // false so it is easy to check.
        if( !$form->validateForm() )
        {
            // retrieve the validation errors
            $errors = $form->getValidationErrors();

            echo "<b>patForms:</b> validation failed. Errors:<br><br>";
            
            // each element can have several error messages.
            foreach( $errors as $elementName => $elementErrors )
            {
                if( empty( $elementErrors ) )
                    continue;
                    
                echo 'Field: <b>'.$elementName.'</b>';
                echo "<pre>";
                print_r( $elementErrors );
                echo "</pre>";
            }
        }
        else
        {
            echo "<b>patForms:</b> validation successful.<br><br>";
        }
    }


    // DISPLAY FORM ------------------------------------------------------

    // output the opening form tag
    echo     $form->serializeStart();

    // display all elements
    foreach( $elements as $element )
    {
        echo $element["label"]."<br>";
        echo "<div>".$element["element"]."</div>";
        echo "<i>".$element["description"]."</i><br><br>";
    }

    // submit button, closing form tag
    echo '<input type="submit" name="save" value="Save form"/><br><br>';
    echo $form->serializeEnd();


    
    
    // EXAMPLE END ------------------------------------------------------
    $exampleGen->displayFooter();
?>