InterJinn

Development Framework For PHP

Documentation

FormJinn Fields

FormJinn fields are just as easy to use as the form itself. This page aims to describe the interface and provide explanations not in the API documentation. For examples of form fields and their associated widget objects you can view the examples listed in the left navigation (the examples assume you know how to create FormJinn forms and a fields).

Creating a field

Creating a field is extremely simple. All you need is a form with which to create it (see section on forms if you don't know how to create a form).

Example:
$newField = $myForm->do->createField( 'myField' );

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 field's form

Sometimes you will want to obtain the form object that owns a field. This happens very often when you are performing post-processing and want the form and the rest of its fields so that you can save the data to a database or some similar action. You can easily obtain the form as follows:

Example:
$aForm = $nameField->do->getForm();

Setting the value of a field

Often you will want to set a default value for a form, or perhaps populate it with already known information -- perhaps the name stored in a permanent cookie. You can do this as follows:

Example:
$phoneField->do->setValue( '(613) 555-1234' );
It's important to note that if the field already contains a value, then using the above will have no effect on the value. This is because the form system is set up to remember input values for any given session. To bypass this feature, you can force the new value to take effect:
Example:
$phoneField->do->setValue( '(613) 555-1234', true );
Depending on the type of field having it's value set, you may need to provide an array. The following sections describe the expected value to be passed to the setValue() method for different field types.

Type: checkbox

This requires an array consisting of checkbox entry key names matched to either true or false. You may optionally just provide an array containing the keys matched to true for those checkboxes that should be checked.

Example:
//
// Long style.
//
$hobbiesField->do->setValue
(
    'coding'        => true,
    'reading'       => true,
    'bodyBuilding'  => true,
    'rollerBlading' => true,
    'cycling'       => false,
    'dancing'       => true,
    'swimming'      => false,
);

//
// Short style.
//
$hobbiesField->do->setValue
(
    'coding'        => true,
    'reading'       => true,
    'bodyBuilding'  => true,
    'rollerBlading' => true,
    'dancing'       => true,
);

Type: hidden

Takes any non-array value. All values will be converted to a string value.

Type: input

Takes any non-array value. All values will be converted to a string value.

Type: mselect

Requires an array consisting of multiple select entry key names matched to either true or false. You may optionally just provide an array containing the keys matched to true for those checkboxes that should be checked. See the setValue() description for checkbox fields for more information.

Type: password

Takes any non-array value. All values will be converted to a string value.

Type: radio

Takes any non-array value that should match a key in the entries array given to the radio field's widget. All values will be converted to a string value.

Type: select

Takes any non-array value that should match a key in the entries array given to the select list field's widget. All values will be converted to a string value.

Type: submit

In HTML the value of a submit field is usually its label. Interjinn handles this differently. The label should be set using the WidgetJinn submit widget. The value when set should be an array consisting of 2 entries -- namely the default x and y coordinates for an image based submission. Obviously these will be overwritten in the event that the submit button is clicked; however, in the event that a different submit button is clicked then these offer default values for the field. This feature may, or may not, be useful to you.

Type: textarea

Takes any non-array value. All values will be converted to a string value.

Type: upload

You shouldn't need to set the value of an upload field.

Retrieving the value of a field

You can retrieve the value of a field by using the getValue() method; however, more often than not you will want to use the getCurrentValue() method instead. This method returns the most recent valid value for the field. A value is valid when it has been either set using setValue() or has successfully passed all processing stages after having been submitted.

Example:
$value = $emailField->do->getValue();
Note that depending on the type of field, the return value may be an array instead of a string. The following sections describe the return value for different types of fields.

Type: checkbox

Returns an array of whose keys are the names of the checkboxes and whose values are either true for checked; otherwise false.

Example:
$value = $hobbiesField->do->getValue();
print_r( $value );
Output:
Array
(
    [coding] => 1
    [reading] => 1
    [bodyBuilding] => 1
    [rollerBlading] => 1
    [cycling] => 
    [dancing] => 1
    [swimming] =>
)

Type: hidden

Returns a string containing the value of hidden field. Hidden fields are often used to pass information along via a form that is related to the form's information, or for setting data via Javascript. The FormJinn engine makes use of hidden forms itself.

Type: input

Returns a string containing the contents of the input field.

Type: mselect

Returns an array of whose keys are the names of the checkboxes and whose values are either true for checked; otherwise false. See the return value description for checkbox fields for more information.

Type: password

Returns a string containing the contents of the password field.

Type: radio

Returns a string matching the key of one of the radio button's widget entries. The key returned will be for the entry selected.

Example:
//
// Set default value to 'male'.
//
$genderField->do->setValue( 'male' );

//
// Set the radio button entries.
//
$genderWidget->do->addEntries
(
    array
    (
        'male'   => 'Male',
        'female' => 'Female',
        'neuter' => 'Unknown'
    )
);
From the above example, the male option would be preselected, but upon submission any of the values male, female, or neuter might be returned.

Type: select

Returns a string matching the key of one of the select list's widget entries. The key returned will be for the entry selected. See the description for radio fields for more information.

Type: submit

Returns an array consiting of two entries -- name the x and y coordinates for an image based submission. If the submit button is not image based, then the values for the x and y entries will both be set to null. To determine if a specific submit button from several was clicked you should check the submitted data entry.

Example:
if( $clearButton->do->getData( 'submitted' ) )
{
    //
    // Code for resetting fields to default values.
    //
}

Type: textarea

Returns a string containing the contents of the textarea field.

Type: upload

Returns an area containing information about the uploaded file. The format of the array is as described in the PHP documentation for file uploads.

Retrieving the current value of a field

This function behaves exactly the same as the getValue() method, with one exception. This method returns either the set value of the field, or if the field has just been submitted, then it returns the submitted value of the field. The submitted value of a field may, or may not be valid. This function is especially usefull for retrieving the value to test in any custom validation routines you may have.

Example:
$value = $ageField->do->getCurrentValue();
if( $value > 120 )
{
    $ageField->do->setData( 'valid', false );
    $ageField->do->setData(
        'errorMessage', "Age cannot be more than 120 years!" );
}

Configuring a field

You will often want to customize how your field will function. FormJinn fields provide a single point for all configuration variables -- namely the setData() method.

Example:
$emailField->do->setData( 'type', 'input' );
There are several such fields available for you to configure to your needs.
  • type
  • submitted
  • valid
  • submittedValue
  • preProcess
  • validation
  • postProcess
  • errorMessage
Each of these is explained in the next section.

Retrieving information about a field

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

Example:
if( !$emailForm->do->getData( 'valid' ) )
{
    //
    // Do something for an invalid email field.
    //
}
The following fields are available to provide information about the form:
  • name
  • formName
  • type
  • submitted
  • valid
  • elements
  • submittedValue
  • preProcess
  • validation
  • postProcess
  • errorMessage
Each of these attributes can be used to handle particular situations with respect to your field. 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 field. Most useful when you don't know the name of the field you are working with and perhaps need to integrate some Javascript into the field or possibly generate an error.

Attribute: formName (get only)

This holds the name of the form to which the fields belongs. This name can be used to retrieve the form object via the FormJinn service; however, it is easier to obtain the form itself with the getForm() method. This attribute is primarily provided to ease the writing of dynamic Javascript functions for manipulating the field and it's associated form.

Attribute: type (get and set)

This indicates the type of the field. Normally this is set automatically when you create a field and set the second parameter of the createField() method. You may also set it manually. Once set it should not be re-set.

Attribute: submitted (get and set)

This attribute will be set to true if the field has just been submitted; otherwise it will be false. This can be especially useful if you have a form which is broken up across multiple pages; however, it is often unnecessary given the pre-processing, validation, and post-processing system built into FormJinn form fields.

Attribute: valid (get and set)

When a form is submitted, the form and all of it's fields are intially have this attribute set to true. During the course of pre-processing, validation, or postprocessing the value may change to false. When set to false then the field does not contain a valid value. You may also set this attribute yourself though generaly there is no need since returning true or false in your custom input processor cause it to be set appropriately.

Attribute: elements (get only)

This attribute only contains useful information for the checkbox, radio, selection, and mselect field types. The value of this attribute is set by the associated widget to the entries given for the associated choices. This value is set when the field is display via the open() or getOpen() method. It can be useful to use this value to determine the displayed value for a given chosen entry's key value since only the key values can be retrieved via getValue() or getCurrentValue().

Attribute: submittedValue (get and set)

When a field has just been submitted, this attribute will contain the submitted value. After the field has gone through pre-processing, validation, and post-processing, if the field is valid then this value will be copied to the field's actual value. You might want to set this attribute yourself if you perform some kind of processing on the value which you would like to be reflected in the final value. For instance post-processing a phone number to have a particular format after it has been validated is a common task.

Attribute: preProcess (get and set)

This attribute be set to an array containing the descriptions of input processors you would like to have applied to the field before it is validated. For the most part pre-processing entries are of the custom input processor type. For more information about input processors see the Input Processors documentation.

Attribute: validation (get and set)

This attribute be set to an array containing the descriptions of input processors you would like to have applied to the field for validation. For more information about input processors see the Input Processors documentation.

Attribute: postProcess (get and set)

This attribute be set to an array containing the descriptions of input processors you would like to have applied to the field after it has been validated. For the most part post-processing entries are of the custom input processor type. For more information about input processors see the Input Processors documentation.

Attribute: errorMessage (get and set)

During pre-processing, validation, or post-processing if an error occurs (perhaps the data is invalid) then this field should be set to an informative error message indicating why the data is erroneous. For the standard input processor types, this attribute will be set to an appropriate message for you. in the case of custom input processors, the onus is on the developer to provide the error message.

Copyright © 2001-2009 Robert Cummings
All Rights Reserved