InterJinn

Development Framework For PHP

Documentation

FormJinn Forms

FormJinn forms are quite easy to use, and as you may well have seen in the FormJinn example, they are not very difficult to create. This section serves to describe the interface and provide explanations not found in the API documentation.

Creating a form

Creating a form is as simple as the following:

Example:
$formJinn = $this->getService( 'formJinn' );
$newForm = $formJinn->do->createForm( 'myForm' );

Creating a field

Creating a new field for a form is also incredibly easy:

Example:
$newField = $newForm->do->createField( 'myField' );
If the field with the given name already exists, then the original field will be returned and a new field will not be created.

Retrieving an existing field

If you have already created your form and it's fields, then quite often you will want to access a particular field for one reason or another (perhaps to save data to a database as part of a custom processor). This is done as follows:

Example:
$retrievedField = $myForm->do->getField( 'myField' );
If the field could not be found, then null will be returned.

Retrieving a list of fields

If you need to gain access to each of the fields in a form then you can use the following method:

Example:
$fieldNames = $myForm->do->getFieldNames();
This will return an array consisting of all the field names for the current form. You can then traverse this list and call the getField() method for each entry to obtain the actual field object.

Deleting a field

Many forms in the real world are dynamically generated. For this reason it is often necessary to create and delete fields as necessary. Deleting a field simple:

Example:
if( $myForm->do->deleteField( 'myField' ) )
{
    //
    // Field was successfully deleted.
    //
}
else
{
    //
    // Field did not exist.
    //
}

Configuring a form

As with most utilities, you will often want to customize how the utility will work. FormJinn forms provide a single point for all configuration variables -- namely the setData() method.

Example:
$myForm->do->setData( 'actionURL', '//registration/thankYou.php' );
There are several such fields available for you to configure to your needs.
  • actionURL
  • method
  • submitted
  • valid
  • multipart
  • maxUpload
Each of these is explained in the next section.

Retrieving information about a form

You can retrieve configuration and status information about your form via the getData() method.

Example:
if( !$myForm->do->getData( 'valid' ) )
{
    //
    // Do something for an invalid form.
    //
}
The following fields are available to provide information about the form:
  • name
  • actionURL
  • method
  • submitted
  • valid
  • multipart
  • maxUpload
  • open
Each of these fields can be used to handle particular situations with respect to your form. The following sections describe what each field means (though most are probably self-explanatory) and how you might use the information.

Attribute: name (get only)

This attribute holds the name of the form. Most useful when you don't know the name of the form you are working with and perhaps need to integrate some Javascript into the form or possibly generate an error.

Attribute: actionURL (get and set)

This determines what page to load when a form is successfully submitted. A form is successfully submitted when all fields pass any validation tests that have been assigned to them. You may use the InterJinn localized path formats when setting the destination (paths beginning with // are relative to the site's pageBase).

Attribute: method (get and set)

This determines how the form is submitted by the browser. The default is post; however, you may also set it to get. In almost all cases the default setting is recommended.

Attribute: submitted (get and set)

If the form has just been submitted, then this will be set to true; otherwise it will be false. Very rarely will you need to set this yourself, but in some case it may be necessary when using advanced form manipulation techniques.

Attribute: valid (get and set)

If the form has been submitted and all fields have passed pre-processing, validation, and post-processing, then this will be set to true; otherwise it will be false. This is another setting you will rarely need to set yourself since the processing system usually will set it for you.

Attribute: multipart (get and set)

This indicates that the form should be a multi-part form. This is the case for uploading files and perhaps other types of fields. This is set to true automatically if the form contains an upload widget, but there may be times when you will need to set it yourself.

Attribute: maxUpload (get and set)

This field mostly only applies when you have have an upload field. This field should be set to the maximum allowable filesize to be uploaded.

Attribute: open (get only)

When you open your form either with the getOpen() or open() methods, then this will be set to true. If you have not called any of these methods for your form, then it will be set to false. After opening the form, if you subsequently close it with either the getClose() or close() methods, then the value of this field will be changed from true to false. If this is set to true when the script finishes, then an error will be generated indicating that the form was never closed.

Outputting the form to the browser

Having gone to all the trouble of creating a form, you obviously want to display it on the browser. Notwithstanding having each of the fields displayed in the browser, you must first output the form. This can be done in a couple of ways:

Example 1:
$myForm->do->open();

//
// Code for outputting form fields and anything else.
//

$myForm->do->close();
Example 2:
echo $myForm->do->getOpen();

//
// Code for outputting form fields and anything else.
//

echo $myForm->do->getClose();
The second example is especially useful if you don't want to output HTML content and layout in the component managing your form. The following example illustrates an advanced technique for slicing up a form so that it can be used by the <jinn:render/> tag of the TemplateJinn system.
Advanced Example: Part 1 - The Component:
class ExamplesSlicedForm extends JinnbaseComponent
{
    var $filename = __FILE__;

    //
    // We'll pretend in this example that font and other properties
    // have been set up already in the $this->props array having been
    // retrieved from the following property path.
    //
    var $propertyPath = 'examples/slicedForm';

    var $slices = array();

    function execute()
    {
        //
        // We create the slices at this point since they must be
        // created before we start sending output to the browser.
        //
        $this->createSlices();
    }

    function render( $sliceSelector )
    {
        if( isset( $this->slices[$sliceSelector] ) )  
        {
            echo $this->widgets[$sliceSelector];
        }
        else
        { 
            $this->warning
            (
                'render',
                'Unknown slice "'.$sliceSelector.'" requested!'
            );
        }
    }

    function createSlices()
    {
        //
        // Obtain FormJinn service and create form.
        //
        $formJinn = $this->getService( 'formJinn' );

        $myForm = &$formJinn->do->createForm( 'myForm' );
        $myForm->do->setData(
            'actionURL', $this->props['targetPage'] );

        //
        // Now we need to create the form's fields.
        //
        $nameField   = $myForm->do->createField( 'name', 'input' );
        $ageField    = $myForm->do->createField( 'age', 'input' );
        $submitField = $myForm->do->createField( 'submit', 'submit' );

        //
        // Now we obtain the WidgetJinn service and create the field
        // widgets.
        //
        $widgetJinn = $this->getService( 'widgetJinn' );

        $nameWidget   = $widgetJinn->do->getWidget( $nameField );
        $ageWidget    = $widgetJinn->do->getWidget( $ageField );
        $submitWidget = $widgetJinn->do->getWidget( $submitField );

        //
        // Now we slice and dice the form.
        //
        $this->slices['formOpen'] = $myForm->do->getOpen();

        $this->slices['nameLabel'] =
            $nameWidget->do->getError(
                $this->props['errorFont'], '', '<br />' )
           .$nameWidget->do->getText( 'Please input your name: ' );

        $this->slices['nameField'] = $nameWidget->do->get();

        $this->slices['ageLabel'] =
            $ageWidget->do->getError(
                $this->props['errorFont'], '', '<br />' )
           .$ageWidget->do->getText( 'Please input your age: ' );

        $this->slices['ageField'] = $ageWidget->do->get();

        $this->slices['submitField'] = $submitWidget->do->get();

        $this->slices['formClose'] = $myForm->do->getClose();
    }
}
Now that we have sliced up the form into the $this->slices array, we now have the ability to access individual pieces. This is exactly what we do in our render function, which will be called often in the following TemplateJinn content. Note that in the following, slicedForm is an arbitrary name, that could have been set to anything.
Advanced Example: Part 2 - The TemplateJinn Source:
<jinn:module name="slicedForm" noRender="true">
    <jinn:component type="render" source="Examples/slicedForm.inc"/>
</jinn:module>

<html><body><div align="center">
<table border="0" cellpadding="0" cellspacing="0">
<jinn:render name="slicedForm" selector="formOpen"/>

<tr>
<td><jinn:render name="slicedForm" selector="nameLabel"/></td>
<td><jinn:render name="slicedForm" selector="nameField"/></td>
</tr>

<tr>
<td><jinn:render name="slicedForm" selector="ageLabel"/></td>
<td><jinn:render name="slicedForm" selector="ageField"/></td>
</tr>

<tr>
<td colspan="2"><jinn:render name="slicedForm" selector="submitField"/>
</td>
</tr>

<jinn:render name="slicedForm" selector="formClose"/>
</table>
</div></body></html>

Copyright © 2001-2009 Robert Cummings
All Rights Reserved