Forms Generation and Validation Documentation

Add arbitrary data to the output that is generated for the form with the Output method. Usually this method is used to add the HTML code that will define the layout of the form, but it could be anything else as programmer defined Javascript code.

Usage

The $data argument is a text string that contains the data to be added to the form output.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.

AddFunction

Synopsis

$error=$my_form_object->AddFunction($arguments)

Purpose

Add the definition of a Javascript function that is meant to be generated as part of the output of the form with the Output method. The function to be generated is meant to execute actions related with the elements of the form.

The function may be called from an event handler associated with any element of the page. For instance, the function may be called from the page <BODY> ONLOAD event handler to activate a give input field when the page is loaded.

Usage

The $arguments argument is an associative array that takes pairs of tag names and values that define the properties of the function to be added to the form output.

Arguments

Element

Identifier of the input field to be associated with the function. The field must have been previously added to the form output with the AddInputPart method.

Function

Name of the function to be added.

Type

Type of the action that the function is meant to perform when executed. Not all types of actions supported by the class are supported by all browsers. However, this class generates conditional code in such way, that if the specified action is not supported by a browser, no Javascript errors will occur as the code is not run.

Supported function types are: focus to activate the input of the given field, select to select all the text in a text input field, select_focus to activate and select the text of the field, disable to prevent the field to receive user input, enable to let the field receive user input, and markValidated to set the style or CSS class of input depending whether it is valid or not.

AddInput

Synopsis

$error=$my_form_object->AddInput($arguments)

Purpose

Add an input field to the form definition.

Usage

The $arguments argument is an associative array that takes pairs of tag names and values that define the properties of the input field to be added to the form definition.

Arguments

ACCEPT

MIME file types to be accepted by the file fields as defined for the ACCEPT attribute of the <INPUT> HTML tag.

ACCESSKEY

Key to be associated as shortcut to activate the given input field for keyboard control. The shortcut key may also be defined with the function AddLabelPart but for input fields without a label the shortcut key has to be defined with AddInput function.

ALT

Alternative text argument for image fields as defined for the ALT attribute of the <INPUT> HTML tag.

ALIGN

Alignment argument for image fields as defined for the ALIGN attribute of the <INPUT> HTML tag.

ApplicationData

Arbitrary application defined data.

CHECKED

Flag argument for radio and checkbox fields as defined for the CHECKED attribute of the <INPUT> HTML tag.

CLASS

Name of the presentation style class with which the input field should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.

COLS

Number of columns of a textarea field as defined for the COLS attribute of the <INPUT> HTML tag.

Content

HTML content to display in input buttons of type submit, reset and button. When this option is defined, the input is rendered with the HTML BUTTON tags instead of INPUT tags.

DisableResubmitCheck

Boolean flag that indicates whether the Javascript code to avoid form resubmission should not be generated for submit type inputs.

ID

Identifier of the field as defined for the ID attribute of the <INPUT> HTML tag. This attribute is required if the NAME attribute is missing. The ID is used as unique reference to the input fields in the class if the NAME is missing.

IgnoreAnonymousSubmitCheck

Boolean flag that indicates whether calls to the WasSubmitted function, without specifying an input to check, should ignore this input when checking whether it was submitted.

InvalidCLASS

Name of the CSS class used to render the input when it is invalid.

The specified value replaces the input CSS class attribute when it is listed in the Invalid forms class variable.

The specified CSS class name is also used to replace invalid fields' CSS class, when the form is validated on the client side using Javascript.

InvalidSTYLE

CSS style attributes used to render the input when it is invalid.

The specified styles are merged with the input default CSS style attributes when it is listed in the Invalid forms class variable.

The specified CSS attributes are also used to replace there input CSS attributes, when the form is validated on the client side using Javascript.

LABEL

Default data value that is outputted as the definition of the input label. See the function AddLabelPart for more information.

LabelCLASS

Name of the presentation style class with which the label associated to this input field should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.

LabelExtraAttributes

Associative array with a list of extra attributes that should be added to the input label HTML tag when the form output is generated.

LabelID

Identifier of the label document element associated to this input field as defined for the ID attribute of the <LABEL> HTML tag.

LabelSTYLE

Definition of the presentation style attributes with which the label associated to this input field should be rendered.

LabelTITLE

Label title text as defined for the TITLE attribute of the <LABEL> HTML tag. Usually browsers present this text as tool tip that appears when the user leaves the mouse pointer stopped over the label.

MAXLENGTH

Maximum number of characters that a text, password or file field may contain as defined for the MAXLENGTH attribute of the <INPUT> HTML tag. The LoadInputValues class function enforces this limit on the server side.

MULTIPLE

Flag argument for select and checkbox fields. The meaning of this argument is the same for select as defined for the MULTIPLE attribute of the <SELECT> HTML tag. For checkbox fields, the use of this argument indicates that that the field belongs to a group of checkbox fields with the same NAME attribute value that should be validated together.

NAME

Name of the field as defined for the NAME attribute of the <INPUT> HTML tag. This attribute is optional if the ID attribute is specified. The NAME is used as unique reference to the input fields in the class if the ID is missing.

NoParent

Boolean flag that indicates whether the input should be considered independent when it is added by custom inputs.

ONBLUR

ONCHANGE

ONCLICK

ONDBLCLICK

ONFOCUS

ONKEYDOWN

ONKEYPRESS

ONKEYUP

ONMOUSEDOWN

ONMOUSEMOVE

ONMOUSEOUT

ONMOUSEOVER

ONMOUSEUP

ONSELECT

Client side script commands to execute when the field value changes as defined for the event handling definition attribute of the same name of the <INPUT> HTML tag.

OPTIONS

Associative array that defines the values and text of a select field as defined for the OPTION HTML tag.

ROWS

Number of rows of a textarea field as defined for the COLS attribute of the <INPUT> HTML tag.

SELECTED

Flag argument for select fields that indicates the value of an option is to appear selected as defined for the SELECTED attribute of the <OPTION> HTML tag. If the select field is of type MULTIPLE, the SELECTED argument should be an array with the values of the options that should be pre-selected.

SIZE

Number of characters that a text field displays at once as defined for the SIZE attribute of the <INPUT> HTML tag.

SRC

URL argument for image fields as defined for the SRC attribute of the <INPUT> HTML tag.

STYLE

Definition of the presentation style attributes with which the input field should be rendered.

TABINDEX

Number that defines the order position of the field in the sequence of fields that are activated when the TAB key is used as defined for the TABINDEX attribute of the <INPUT> HTML tag.

TYPE

Type of the field as defined for the TYPE attribute of the <INPUT> HTML tag. Supported input types are: textarea, select, text, file, password, checkbox, radio, submit, reset, button and hidden.

Additionally, there is a special type named custom that should be specified to add custom inputs defined by separate plug-in classes.

VALUE

Default value of a field as defined for the VALUE attribute of the <INPUT> HTML tag. This property is required for select type fields and it must have a value that is the index of an entry of the OPTIONS property associative array.

Accessible

Boolean flag that determines whether the field should outputted as an accessible input when it is added to the form output definition with the AddInputPart function.

If this flag is set to 0, the field is outputted as text that represents its current state or value, preserving the presentation style defined by the STYLE and CLASS attributes.

If this flag is set to 1, the field is outputted as an usual accessible input, regardless of the value of the form ReadOnly flag. If the field Accessible property is not specified, the form ReadOnly flag value is considered to determine how the field is outputted.

Capitalization

Type of case conversion that is meant to be done on the field text value. If the argument value is lowercase the text is converted to lower case. If the argument value is uppercase the text is converted to upper case. If the argument value is words the first letter of each word is converted to upper case and the other letters are converted to lower case.

ClientScript

Javascript code to be inserted when the field is added to the form output. The argument should be a string that may have line breaking or other types of white space characters. It may be used to define functions to perform custom validation or event handling.

CustomClass

Name of a class that implements the behavior of a custom input implemented as a separate plug-in.

DependentValidation

Identifier of another input that determines whether the validation of the current input will be performed depending on the state of the other input.

If the other input check state is true, the current input will be validated. Otherwise, the current input validation will be skipped.

The other input must support checking its state. So it must be of the type checkbox, radio, or custom.

DiscardInvalidValues

Flag argument that indicates whether invalid values should be discarded when the function LoadInputValues is called.

This is meant to help preventing security exploits performed by attackers that may spoof values passed in fields that usually are not editable by real users, like for instance context values passed in hidden fields.

If this argument is 1, the inputs are validated from within the LoadInputValues function. If the submitted values are invalid, it is ignored and the input default values are restored.

If the argument is 0, validation is only performed when the Validate function is called. In the case of the select type inputs, invalid option values that may have been submitted are not discarded by the LoadInputValues function.

EncodedField

Identifier of the field that will hold the result of the encoding of the value of a password field. If this argument is specified the password field value is cleared after storing the encoded value in the given field. Usually, this field is of type hidden.

Encoding

Name of the Javascript function to be called to encode a password field when a form is submitted.

EncodingFunctionScriptFile

URL of an external Javascript file that needs to be loaded from within the form HTML output to include the definition of the Encoding function.

EncodingFunctionVerification

A Javascript expression (function call or variable) that should be used if function defined by the Encoding argument is available. This argument may be used in the case that the Encoding function is meant to be loaded from an external Javascript file and that file may only be loaded in some browser versions.

ExtraAttributes

List of extra attributes that should be added to the field's HTML tag when the form output is generated. These extra attributes are ignored if the field is added to the form output as a hidden input part with the AddInputHiddenPart class function.

The list should be defined as an associative array with the attribute names as array entry indexes and the attribute values as array entry values.

ReadOnlyMark

Mark that should be outputted in the place of the field when the form is displayed as read-only or when the field is set as not accessible. If this argument is not specified, it is displayed the current field value.

The read-only mark is outputted without being encoded, so it can include actual HTML markup to display images or other types of marks instead of the submitted field values.

This is useful for instance to mask password values or display nice alternate images for read-only radio buttons or checkboxes.

Notice that this mark data is not encoded by this class when it is outputted as part of the form output. Therefore, be careful when using data for the mark that is submitted by the user or other untrusted external data source, as it may contain tags that may open the potential security abuse with cross-site scripting exploits.

ReadOnlyMarkUnchecked

Mark that should be outputted in the place of a radio or checkbox field when it is not checked and the form is displayed as read-only or when the field is set as not accessible.

ReplacePatterns

List of transformations that may be applied to a text input value when it is changed by the user. The transformations are defined in the form of regular expressions patterns that define the form of the text that should be searched and the corresponding replacement expressions.

The transformations may occur on the server side when the class function LoadInputValues is called. The transformations may also occur on the client side if the user browser has enabled Javascript with regular expression based text replacement support. The generated form Javascript code automatically detects whether client side transformations can be applied.

The transformations list should be defined as an associative array with the search regular expressions as array entry indexes and the replacement text as array entry values.

It is beyond the scope of this document to give a full explanation of how regular expressions work and their syntax. You may want to study the PHP function ereg_replace to learn the syntax of search and replacement regular expressions.

In general terms you should know that the parts of the text input value that match the search regular expression are substituted by the replacement expression.

The replacement expression may contain place holders that will be substituted by matching parts of the original value. Place holders are specified by a backslash character \ followed by the number of the part of the original value. A matching part is denoted in the search regular expression by enclosing its definition within brackets ( ) .

Given this, \1 in the replacement expression represents the first search match text, \2 the second, \3 the third and so on up to \9.

Here follows the definition of a few examples of useful replacement expressions:


 "ReplacePatterns"=>array(

   /*
    * trim whitespace at the beginning of the text value
    */
   "^\\s+"=>"",

   /*
    * trim whitespace at the end of the text value
    */
   "\\s+\$"=>"",

   /*
    * Prepend the text http:// in values that start with www.
    */
   "^([wW]{3}.)"=>"http://\\1"

 )

ReplacePatternsOnlyOnClientSide

When this option is specified the action of replacing patterns, defined by the ReplacePatterns attribute, is only performed on the client side with the Javascript code generated by the class within the form HTML output.

ReplacePatternsOnlyOnServerSide

When this option is specified the action of replacing patterns, defined by the ReplacePatterns attribute, is only performed on the server side. Therefore, no Javascript code is generated by the class within the form HTML output to perform this action on the client side.

SubForm

Name of the sub-form within which the field is contained. When the user presses a submit button that is contained in a given sub-form, only the values of the fields that belong to that sub-form are subject of validation.

If the submit button that is pressed is not contained in any sub-form or the form is submitted in any way other than using a submit button, the values of all the fields in the form are subject of validation.

TITLE

Input title text as defined for the TITLE attribute of the <INPUT> HTML tag. Usually browsers present this text as tool tip that appears when the user leaves the mouse pointer stopped over the input.

ValidateAsCreditCard

Type argument that indicates that the field value should be validated as a credit card number. Supported types are: amex, carteblanche, dinersclub, discover, enroute, jcb, mastercard and visa.

If the argument is set to unknown, the class will just validate the number by verifying the digit checksum using the MOD10 algorithm and will not perform any extra card type specific verifications. Any spaces, dashes ('-') or dots ('.') within the number digits are ignored.

If the argument is set to field, the class will determine the card type verification to perform according to the value of a given select type field defined by the ValidationCreditCardTypeField argument.

ValidateAsCreditCardErrorMessage

Error message to be used when the field value is meant to contain a credit card number but it is invalid.

ValidateAsDifferentFrom

Name of another field that the field value should be different. This type of validation is useful for password reminder fields where the reminder text should not be the same as the password value.

ValidateAsDifferentFromErrorMessage

Error message to be used when the field value is meant to be different from another given field value but it is not.

ValidateAsDifferentFromText

Text that the field value should be different. This type of validation is useful rejecting the default value of select fields to make the user choose another option explicitly.

ValidateAsDifferentFromTextErrorMessage

Error message to be used when the field value is meant to be different from a given text value but it is not.

ValidateAsEmail

Flag argument that indicates that the field value should be validated as an e-mail address.

ValidateAsEmailErrorMessage

Error message to be used when the field value is meant to contain an e-mail address but it is invalid.

ValidateAsEqualTo

Name of another field that the field value should be equal to. This type of validation is useful for password confirmation fields.

ValidateAsEqualToErrorMessage

Error message to be used when the field value is meant to be equal to another given field value but it is not.

ValidateAsFloat

Flag argument that indicates that the field value should be validated to verify that it contains a valid floating point number.

ValidateAsFloatErrorMessage

Error message to be used when the field value is meant to be a valid floating point number but it is not.

ValidateAsInteger

Flag argument that indicates that the field value should be validated to verify that it contains a valid integer number.

ValidateAsIntegerErrorMessage

Error message to be used when the field value is meant to be a valid integer number but it is not.

ValidateAsNotEmpty

Flag argument that indicates that the field value should not be empty. For file fields, the class also verifies that a valid file was uploaded.

ValidateAsNotEmptyErrorMessage

Error message to be used when the field value is meant to not be empty but it is not.

ValidateAsNotRegularExpression

Parameter that indicates that the field value should be validated to not match the one or more given regular expressions. This parameter value can be a single regular expression string or an array of regular expressions.

ValidateAsNotRegularExpressionErrorMessage

One or more error messages to be used when the field value is meant to not match given regular expressions but it is does. It should be an error message string except when the ValidateAsNotRegularExpression parameter is an array of regular expressions. In that case this parameter should be an array with an equal number of error messages.

ValidateAsSet

Flag argument that indicates that at least one option of a multiple select type field, or one of a radio type field of the same group of the field being defined, or a checkbox should be set.

radio and checkbox fields should be set to the same NAME attribute value to be considered of the same group, but should have different ID attribute values.

checkbox fields of the same group should also be defined setting MULTIPLE attribute to indicate that they belong to a group and at least one of the group fields should be checked.

ValidateAsSetErrorMessage

Error message to be used when on select option or a radio or checkbox field value is meant to be set but it is not.

ValidationErrorMessage

Default error message to be used when no validation type specific message is defined.

ValidateMinimumLength

Integer argument that indicates the minimum length of the field value in number of characters.

ValidateMinimumLengthErrorMessage

Error message to be used when the field value length is less than the specified by the ValidateMinimumLength option.

ValidateOnlyOnClientSide

When this option is specified the validation checks that would be done by the Validate function for this input are not performed.

ValidateOnlyOnServerSide

When this option is specified the validation checks that would be done on the client side by the Javascript code are not performed and the validation code is not generated by the Output function.

ValidateOptionalValue

When this option is specified, it indicates a field value that is accepted without further validation. This option is useful to specify a value that is meant to be always accepted as default even if it does not satisfy any validation conditions.

ValidateRegularExpression

Parameter that indicates that the field value should be validated to match the one or more given regular expressions. This parameter value can be a single regular expression string or an array of regular expressions.

ValidateRegularExpressionErrorMessage

One or more error messages to be used when the field value is meant to match given regular expressions but it is does not. It should be an error message string except when the ValidateRegularExpression parameter is an array of regular expressions. In that case this parameter should be an array with an equal number of error messages.

ValidationClientFunction

Name of a programmer defined Javascript function to be called to validate the field value on the client side. The form field object is passed as argument to that function. It should return true if the field value is valid.

ValidationClientFunctionErrorMessage

Error message to be used when the client side validation function returns false.

ValidationCreditCardTypeField

Name of the select type field that defines the credit card type to be assumed when the ValidationAsCreditCard argument is set to field.

ValidationDecimalPlaces

Maximum number of decimal places to the right of the decimal point that a field validated as floating point may have. If this argument is specified, floating point values with exponents represented in the scientific notation (e.g. 10.3E+11) are no longer accepted as valid.

ValidationLowerLimit

Lower limit value to be accepted when the field is meant to be validated as integer or floating point number. If this argument is not specified, no lower limit checking is done.

ValidationServerFunction

Name of a programmer defined PHP function to be called to validate the field value on the server side. The field value is passed as argument to that function. It should return true if the field value is valid.

ValidationServerFunctionErrorMessage

Error message to be used when the server side validation function returns false.

ValidationUpperLimit

The $arguments argument is an associative array that takes pairs of tag names and values that define the properties of the label to be added to the form output.

Arguments

ACCESSKEY

Key to be associated as shortcut to activate the given input field for keyboard control as defined for the ACCESSKEY attribute of the <LABEL> HTML 4 tag. Keyboard activation only happens on browsers that fully support the HTML 4 standard. On some platforms the user has to hold the Alt key when the activation key is pressed. This argument may be omitted as long as it was specified when it is defined the input field with the AddInput function.

CLASS

Name of the presentation style class with which the label should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.

FOR

Identifier of the input field to which the label is meant to be associated as defined by the ID argument passed when calling the AddInput. That input field has to be added to the form output by calling the AddInputPart either before or after calling this method but always before calling the Output method.

ExtraAttributes

Associative array with a list of extra attributes that should be added to the label HTML tag when the form output is generated.

ID

Identifier of the label document element as defined for the ID attribute of the <LABEL> HTML tag.

LABEL

Data that is outputted as the definition of the label. Usually it is some text eventually with character style HTML markup that is used to denote the access key that is associated with the given input field. This argument may be omitted as long as it was specified when it is defined the input field with the AddInput function.

Notice that the label data is not encoded by this class when it is outputted as part of the form output. Therefore, be careful when using data for the label that is submitted by the user or other untrusted external data source, as it may contain tags that may open the potential security abuse with cross-site scripting exploits.

STYLE

Definition of the presentation style attributes with which the label should be rendered.

TITLE

Connect

Synopsis

$error=$my_form_object->Connect($from, $to, $event, $action, $context)

Purpose

Connect two form inputs in such way that when a given event occurs in the connection origin input on the client side (user browser), it is triggered an action that is executed in the context of the target input.

Usage

The $from argument is the identifier of the connection origin input on which it may occur the trigger event.

The $to argument is the identifier of the connection target input that will execute an action after the trigger event occurs in the origin input.

The $event argument is the name of event that may occur in the connection origin input in the client side (user browser). All event types that may be triggered by the base input types are supported. Custom input types may support other types of events.

The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input. Currently, several actions are supported by all base input types, except for the hidden type.

The Click action emulates the same effect of an user clicking in the target input. The Focus action gives the focus to the target input. The Select action selects all the text of a text target input. The Enable action enables the target input. The Disable action disables the target input. The MarkValidated action sets the style or CSS class of input depending whether it is valid or not.

Custom input types may support other types of actions.

The $context argument is an associative array that may pass additional context information to configure details of the action that will be executed. Most actions do not require any additional context information. In that case the $context argument may be an empty array.

ConnectFormToInput

Synopsis

$error=$my_form_object->ConnectFormToInput($input, $event, $action, $context)

Purpose

Connect the form to an input in such way that when a given event occurs in the form on the client side (user browser), it is triggered an action that is executed in the context of the target input.

Usage

The $input argument is the identifier of the connection target input that will execute an action after the trigger event occurs in the form.

The $event argument is the name of event that may occur in the form in the client side. Currently, the supported events are: ONSUBMIT for when the form is submitted but before validation or any other action occurs, ONSUBMITTING for when the the form is submitted but after validation or other any actions occurs, ONRESET for when the form is reset, ONLOAD for when the form page is loaded, ONUNLOAD for when the form page is unloaded, and ONERROR when a validation error occurred.

The $action argument is the name of an action that will be executed in the context of the target input after the trigger event occurs in the form. Currently, several actions are supported by all base input types, except for the hidden type.

The Click action emulates the same effect of an user clicking in the target input. The Focus action gives the focus to the target input. The Select action selects all the text of a text target input. The Enable action enables the target input. The Disable action disables the target input. Custom input types may support other types of actions.

The $context argument is an associative array that may pass additional context information to configure details of the action that will be executed. Most actions do not require any additional context information, so the $context argument should be an empty array.

DisplayOutput

Synopsis

$error=$my_form_object->DisplayOutput()

Purpose

Output the HTML generate for the form.

Usage

EncodeJavascriptString

Synopsis

$encoded=$my_form_object->EncodeJavascriptString($string)

Purpose

Encode a string value for use as a string expression in Javascript code.

Usage

The $string argument specifies the string value to be encoded.

The $encoded return value is a string that defines a Javascript string expression that represents the encoded string value.

EndLayoutCapture

Synopsis

$error=$my_form_object->EndLayoutCapture()

Purpose

Stop capturing the current script output to compose the form layout.

Usage

FetchOutput

Synopsis

$output=$my_form_object->FetchOutput()

Purpose

Fetch the generated form output into a string.

Usage

The $output return value contains a string that contains the generated form output. If there was an error, an empty string is returned.

FlagInvalidInput

Synopsis

$sub_form=$my_form_object->FlagInvalidInput($input, $error)

Purpose

Flag a given input as invalid.

Usage

The $input argument specifies the identifier of the input to be flagged as invalid.

The $error argument specifies the validation error message to associate to the invalid input.

The $sub_form return value is a string of the sub-form that the flagged input belongs.

GetFileValues

Synopsis

$name=$my_form_object->GetFileValues($input,$values)

Purpose

Retrieve the values that identify a file uploaded when the form is submitted.

Usage

The $input argument defines the identifier of the file field from which the values are meant to be retrieved.

The $values argument is a reference to an associative array variable that will hold the values that identify the uploaded file. If the file was uploaded successfully, this associative array contains the following entries:

name - name of the file
tmp_name - path of a temporary file that holds the file contents.
type - MIME content type of the file
size - size of the file

The return value $name contains the name of the file. If the specified input does not exist or if it was not uploaded a valid file, the return value is an empty string.

GetCheckedRadio

Synopsis

$input=$my_form_object->GetCheckedRadio($name)

Purpose

Retrieve the form radio input of a given name that is currently checked.

Usage

The $name argument defines the name of the radio inputs that should be looked up to see which one is checked.

The return $input value is a string value that indicates the identifier of the radio input field of the given name that is currently checked. If the specified name does not correspond to an existing field or it is not a radio field or it is but it is not checked, the return value is an empty string.

GetCheckedRadioValue

Synopsis

$value=$my_form_object->GetCheckedRadioValue($name,$default)

Purpose

Retrieve the value of the form radio input of a given name that is currently checked.

Usage

The $name argument defines the name of the radio inputs that should be looked up to see which one is checked.

The $default argument defines the value that should be returned if there is no radio field with the given name that is checked. If this argument is not specified the default value is an empty string.

The return $value value is a string that indicates the value assigned to the radio input field of the given name that is currently checked. If the specified name does not correspond to an existing field or it is not a radio field or it is but it is not checked, the return value is the value passed by to the $default argument.

GetCheckedState

Synopsis

$checked=$my_form_object->GetCheckedState($input)

Purpose

Retrieve the current checked state of a radio or checkbox input.

Usage

The $input argument defines the identifier of the input to determine its checked state.

The return $checked value is a boolean value that indicates the checked state of the given field. If the specified input does not exist or it is not a radio or a checkbox, the return value is an error string.

GetContainedInputs

Synopsis

$error=$my_form_object->GetContainedInputs($input, $kind, $contained)

Purpose

Retrieve the list of inputs contained within a given input of the form.

Usage

The $input argument is a string that specifies the identifier of the input.

The $kind argument is a string that specifies the kind of contained input to be retrieved. Currently this argument is ignored. Set to an empty string for future compatibility.

The $contained argument is a reference to a variable that will be assigned by this function to an array of identifier strings of the contained inputs.

GetInputProperty

Synopsis

$error=$my_form_object->GetInputProperty($input, $property, $value)

Purpose

Retrieve the current value of an input field property.

Usage

The $input argument defines the identifier of the field.

The $property argument defines the name of the property of the field to be retrieved. Currently supported properties are:

ApplicationData

Arbitrary application defined data.

LABEL

HTML text value of the input label, if set.

SelectedOption

Value the option of a select input that is currently selected.

TYPE

Type of the given input.

ApplicationData

Arbitrary application defined data.

The $value argument should be a reference to a variable that is assigned by the function to the value of the given field property.

GetInputValue

Synopsis

$value=$my_form_object->GetInputValue($input)

Purpose

Retrieve the current value that is set to the given field.

Usage

The $input argument defines the identifier of the field from which the value is to be retrieved.

The return $value contains the current value of the given field. If the specified input does not exist, the return value is an error string.

GetInputEventURL

Synopsis

$error=$my_form_object->GetInputEventURL($input, $event, $parameters, $url)

Purpose

Retrieve an URL that can be used on the client side to submit a request to handle a given event to be associated with a give input.

This function is useful to write plug-in classes that implement capabilities of custom inputs that require accessing the server to execute input event handling actions or retrieve information necessary on the client side that is only available on the server side.

For instance, if a custom input needs to present an image that is served dynamically, this function can be used to generate an URL that can be used as the image source. When the browser accesses the URL returned by this function, the form processing script would have to call the HandleEvent method of this class, so the event handling request can be routed to the specified custom input class.

Usage

The $input argument is a string that specifies the identifier of the given custom input field.

The $event argument is a string that specifies the name of the event that is going to be passed to the custom input class so it can execute the corresponding event handling action.

The $parameters argument is an associative array that specifies a list of optional parameters that are going to be passed to the custom input class so it can execute the corresponding event handling action.

The $error return value contains an error message if the function call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.

GetInputs

Synopsis

$inputs=$my_form_object->GetInputs($parent)

Purpose

Retrieve the list of inputs of the form.

Usage

The $parent argument is a string that specifies the identifier of the parent input when it is intended to retrieve all private inputs managed by a given custom input. Specify an empty string as argument to retrieve all inputs except any managed private inputs.

The $inputs return value is an array with the identifiers of the requested inputs.

GetJavascriptCheckedRadioValue

Synopsis

$javascript_value=$my_form_object->GetJavascriptCheckedRadioValue($form_object, $name, $default)

Purpose

Generate a Javascript expression that represents the value of the currently checked radio input field with a given name to be used to on client side scripts in Javascript.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the radio input belongs.

The $name argument defines the name of the radio inputs that should be looked up to see which one is checked.

The $default argument defines the value that should be returned if there is no radio field with the given name that is checked. If this argument is not specified, the default value is an empty string.

The $javascript_value return value is a string that represents the value of the checked radio input field in Javascript.

GetJavascriptCheckedState

Synopsis

$javascript_value=$my_form_object->GetJavascriptCheckedState($form_object, $input)

Purpose

Generate a Javascript expression that represents the checked state of a given checkbox, radio, or custom input field to be used to on client side scripts in Javascript.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.

The $input argument is a string that specifies the identifier of the given input field.

The $javascript_value return value is a string that represents the given input field checked state in Javascript.

GetJavascriptConnectionAction

Synopsis

$error=$my_form_object->GetJavascriptConnectionAction($form_object, $from, $to, $event, $action, $context, $javascript)

Purpose

Generate the necessary Javascript code that will be used to implement the action that is executed when the trigger event occurs in a connected input.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs. If this parameter is an empty string, the function will automatically determine the form object expression using either the form NAME or ID class variables, if these variables are not set to empty strings.

The $from argument is the identifier of the connection origin input on which it may occur the trigger event.

The $to argument is the identifier of the connection target input on which the event action is executed.

Generate a Javascript expression to set the checked state of a given checkbox, radio, or custom input field.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.

The $input argument is a string that specifies the identifier of the given input field.

The $checked argument is a string that specifies the Javascript expression to set the given input checked state.

The $javascript return value is a string with Javascript statements to set the given input checked state.

GetJavascriptSetFormProperty

Synopsis

$javascript=$my_form_object->GetJavascriptSetFormProperty($form_object, $property, $value)

Purpose

Generate a Javascript expression to assign the value of a form property.

Usage

The $form_object argument is a string that represents the Javascript object of the form.

The $property argument is a string that specifies the name of the form property to be assigned. Currently, only the property SubForm.

The $value argument is a string that specifies the Javascript expression to assign to the given form property.

The $javascript return value is a string with Javascript statements to assign the given form property.

GetJavascriptSetInputProperty

Synopsis

$javascript=$my_form_object->GetJavascriptSetInputProperty($form_object, $input, $property, $value)

Purpose

Generate a Javascript expression to assign the value of a property of a given input field.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.

The $input argument is a string that specifies the identifier of the given input field.

The $property argument is a string that specifies the name of the input property to be assigned. Currently, only the property VALUE is supported for regular input types. Custom inputs may support other properties.

The $value argument is a string that specifies the Javascript expression to assign to the given input property.

The $javascript return value is a string with Javascript statements to assign the given input property.

GetJavascriptSetInputValue

Synopsis

$javascript=$my_form_object->GetJavascriptSetInputValue($form_object, $input, $value)

Purpose

Generate a Javascript expression to assign the value of a given input field.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.

The $input argument is a string that specifies the identifier of the given input field.

The $value argument is a string that specifies the Javascript expression to assign to the given input value.

The $javascript return value is a string with Javascript statements to assign the given input value.

GetNextMessage

Synopsis

$has_messages=$my_form_object->GetNextMessage($message)

Purpose

Retrieve the next event message pending on the message queue.

Usage

A message describes an event that has occurred on the client side. Usually an event is captured and processed by a custom input class when the HandleEvent function is called.

When the event is not completely handled by the custom input, it may post a message to the form message queue to let the application complete the event handling process.

The message queue may hold multiple messages. The GetNextMessage function should be called to retrieve and reply to the messages until there are no more queued messages.

The $message argument is a reference to an associative array variable that is initialized by this function with the first message pending on the message queue. The variable is not initialized when there are no more queued messages.

The $has_messages return value is a boolean flag that indicates whether there were any queued messages.

GetSubmittedValue

Synopsis

$value=$my_form_object->GetSubmittedValue($input)

Purpose

Retrieve the value of a given input that is being submitted.

Usage

The $input argument defines the identifier of the field from which the submitted value is to be retrieved.

The return $value contains the current value of the given field. If the specified input does not exist, the return value is an error string.

HandleEvent

Synopsis

$error=$my_form_object->HandleEvent($processed)

Purpose

Handle requests to process events in order to execute an action resulting from a client side user interaction or serve additional information that could not be served when the page with the form was served.

This function is usually necessary to call when there are custom form inputs implemented by plug-in classes that need to interact with the server.

Usage

If the current form has custom inputs, this function should be called right after all form fields are defined and before any form processing functions are called.

This function examines the arguments passed to the current page either via a GET or POST methods to determine whether the current request is for handling an event or for normal form processing.

The $processed argument is used to return a boolean value by reference that is set by this function to indicate whether it is a request for handling an event in case it returns 1, or it is a normal form processing access in case it returns 0.

The $error return value contains an error message if the function call did not succeed. Otherwise it contains an empty string.

If the $processed argument is set to 1, or the $error is set to a non-empty error message string, the current script should exit immediately. Otherwise, the form processing should proceed normally.

This function examines the request arguments with the names defined by the class variables event_parameter and input_parameter to determine if the request is for event handling and which custom form input is expected to handle the event.

LoadInputValues

Synopsis

$error=$my_form_object->LoadInputValues($submitted)

Purpose

Set the form fields with values passed to the script by the Web server.

Usage

The $submitted argument lets this method know if the script was called to handle a form submitted by the user or the form is just being loaded by the first time, eventually with some initial values defined in the page URL. This argument only affects the interpretation of the values to be loaded in checkbox and multiple select fields.

Note: Currently this method is implemented by loading the field values from the global variables $HTTP_POST_VARS, or from $HTTP_GET_VARS or from the global variables with the same names of the input fields. If you relied on changing the global variables to change the field values that are used by this method, that may not work. Instead, use the SetInputValue method after you call LoadInputValues.

Also, if your PHP configuration has the option magic_quotes_gpc set to On, the LoadInputValues method also tries to strip any ' or \ characters that are added by PHP. This way, the original values submitted with the form are restored. However, that will not fix those values in $HTTP_POST_VARS, $HTTP_GET_VARS or global variables from where the input values are loaded. Use the function GetInputValue to retrieve the fixed values.

Output

Synopsis

$error=$my_form_object->Output($arguments)

Purpose

Generate the output of the form.

Usage

The $arguments argument is an associative array that takes pairs of tag names and values that define options that control the way the form output is generated.

Arguments

EndOfLine

Text data that defines the character sequence that should be used to break the output lines. If this argument is not specified the text lines of the output will not be broken, except for eventual Javascript code that may be generated and the text lines needs to be broken at least with a line feed. A line feed (\n) or character sequence with a carriage return followed by a line feed (\r\n) are usual line breaking sequences in most platforms.

Function

Name of the function to be called to output the form data that is generated. The function is usually called multiple times to output the HTML code that defined the form output. The function takes only an argument that is a text string with HTML code.

OutputDebug

Synopsis

$my_form_object->OutputDebug($message)

Purpose

Output debugging information using the function specified by the debug variable, if set.

This function is usually called by custom input classes that handle client side events.

The $message argument is an associative array that describes message. The array may contain some common entries that all event messages have. It may also have some entries that describe event specific details. Here follows a list of common entries:

Event

Name of the event associated to this message.
From

Identifier of the input that is posting the message.
ReplyTo

Identifier of the input that should handle the reply to the message.
Target

Identifier of the input that should handle the message. The target input should be a custom input that implements the PostMessage function. If this entry is missing, the message should be handled by the application using the GetNextMessage function.

RemoveFunction

Synopsis

$error=$my_form_object->RemoveFunction($name)

Purpose

Remove a previously added function from the form output to be generated by the Output method.

Usage

The $name argument is the name of the function to be removed from the form output.

ReplyMessage

Synopsis

$error=$my_form_object->ReplyMessage($message, $processed)

Purpose

Send a reply to the message retrieved from the form message queue.

Usage

This function should be called after processing a client side event message retrieved with the GetNextMessage function.

The $message argument is the same associative array of the message retrieved with the GetNextMessage function. It may contain new or altered entries to specify details that may trigger different actions when the message reply is processed.

The $processed argument is used to return a boolean value by reference that is set by this function to indicate whether the response to the current request is finished when it returns 1, or the script may continue with normal form processing in case it returns 0.

ResetFormParts

Synopsis

$my_form_object->ResetFormParts()

Purpose

Reset the definition of the form output as it is initially when the form object is created.

SetCheckedRadio

Synopsis

$radio=$my_form_object->SetCheckedRadio($name, $value)

Purpose

Set the current checked state of all radio inputs of a given name.

Usage

The $name argument defines the name of all the radio inputs to check or uncheck.

The $value argument is the value of the radio input that should be checked. All the other radio inputs with the same name that have a different value will be unchecked.

The $radio return value contains the identifier of the radio button that was checked. An empty string is returned if no radio input was found with the given name and value.

SetCheckedState

Synopsis

$error=$my_form_object->SetCheckedState($input,$checked)

Purpose

Set the current checked state of a radio or checkbox input.

Usage

The $input argument defines the identifier of the input to be set.

The $checked argument is a boolean value that specifies whether the given input is going to be checked or unchecked.

SetInputProperty

Synopsis

$error=$my_form_object->SetInputProperty($input, $property, $value)

Purpose

Redefine the current value of an input field property.

Usage

The $input argument defines the identifier of the field to be set.

The $property argument defines the name of the property of the field to be redefined. Currently supported properties are:

ACCEPT

ALT

COLS

LABEL

MAXLENGTH

ONBLUR

ONCHANGE

ONCLICK

ONDBLCLICK

ONFOCUS

ONKEYDOWN

ONKEYPRESS

ONKEYUP

ONMOUSEDOWN

ONMOUSEMOVE

ONMOUSEOUT

ONMOUSEOVER

ONMOUSEUP

ONSELECT

ROWS

SIZE

SRC

TABINDEX

Accessible

ApplicationData

Capitalization

ClientScript

Content

ReadOnlyMark

ReadOnlyMarkUnchecked

SubForm

VALUE

ValidationServerFunctionErrorMessage

STYLE

CLASS

The $value argument defines the value to be assigned to the given field property.

SetInputValue

Synopsis

$error=$my_form_object->SetInputValue($input,$value)

Purpose

Redefine the current value of an input field.

Usage

The $input argument defines the identifier of the field to be set.

The $value argument defines the value to be assigned to the given field.

SetSelectOptions

Synopsis

$error=$my_form_object->SetSelectOptions($input, $options, $selected)

Purpose

Set the list of options and selected values of a select type input.

Usage

The $input argument defines the identifier of the select input to be set.

The $options argument is an associative array that defines the list of options, like for the OPTIONS argument passed to AddInput function.

The $selected argument is array that defines the values of the list of options that should be selected, like for the SELECTED argument passed to AddInput function. For non MULTIPLE select inputs, it should be passed an array with a single value of the option to be selected.

StartLayoutCapture

Synopsis

$error=$my_form_object->StartLayoutCapture()

Purpose

Start capturing the current script output to compose the form layout.

Usage

Validate

Synopsis

$error_message=$my_form_object->Validate($verify,$sub_form)

Purpose

Determine if the values set in the form input fields are valid.

The validation of each input is performed according to the respective definition that was passed to the AddInput function. The order of the validation types is as follows:

ValidateAsNotEmpty

ValidateAsDifferentFromText

ValidateMinimumLength

ValidateRegularExpression

ValidateAsNotRegularExpression

ValidateAsInteger

ValidateAsFloat

ValidateAsEmail

ValidateAsCreditCard

ValidateAsEqualTo

ValidateAsDifferentFrom

ValidateAsSet

ValidationServerFunction

As a side note, the order of the client side validation types implemented by the Javascript code generated by the class is the same, except that, obviously, the ValidationClientFunction validation will be performed instead of ValidationServerFunction.

Usage

The $verify argument is an associative array that should be passed by reference to return the identifiers of the fields that are set with invalid values. The index of each entry in the array is the respective invalid field identifier. The value of each entry is set with the field sub-form name.

The $sub_form argument is the name of the sub-form to which the validation should be restricted. If this argument is an empty string, all fields in the form are validated. Otherwise, only the fields with the same sub-form name are validated.

The $error_message return value contains the error message defined for the first invalid field that was found. If all fields are set with valid values, the function returns an empty string.

WasSubmitted

Synopsis

$submitted_input=$my_form_object->WasSubmitted($input)

Purpose

Determine if a form was submitted by a given input field.

Usage

The $input argument specifies the identifier of the input field that this method should verify whether it was used to submit the form.

The $submitted_input return value contains the identifier of the field that was used to submit the form. If the $input argument is not an empty string and the field was not used to submit the form, the method returns an empty string.

Usually the specified input is of type submit or image, but if it is specified a field of another type the method just verifies if the respective input value was passed when the form was submitted. So, it is ok to specify for instance a dummy hidden that will only act as a flag to determine if the form was submitted or is meant to be displayed for the first time.

If the $input argument is an empty string the method tries to find whether any submit or image field was used to submit the form and returns its name. If no field was found, the method returns an empty string.

Whenever possible it is recommended to specify the name of an actual field because it takes less time to verify only one field than traversing the whole list of fields of the form.

Properties

ACTION

URL of the resource (Web page script) that is meant to handle the form submission as defined for the ACTION attribute of the <FORM> HTML tag.

Usually, Web developers define a form in with page script and process it with another. However, since you always have to create the same object to output the HTML code to display the form and validate it, it is convenient to use the same script handle both circumstances. Doing this is also convenient to handle the situation where you need to redisplay the form because some fields where submitted with invalid values.

One simple way to define the ACTION property to make the form be handled by the same script is to set it with an empty string or with ? if you want to avoid passing forward any parameters previously passed with the current page URL.

Default value: ""

ENCTYPE

MIME Content type of the data that is sent when the form is submitted as defined for the ENCTYPE attribute of the <FORM> HTML tag.

This property only applies when the data is submitted using the POST method. If no encoding type is specified, the browsers use the MIME type application/x-form-urlencoded. If the form includes file input fields, the class uses the MIME type multipart/form-data automatically.

Default value: ""

ID

Identifier of the form document element as defined for the ID attribute of the <FORM> HTML tag.

Default value: ""

METHOD

Method that is used to submit the form as defined for the METHOD attribute of the <FORM> HTML tag.

The method that is recommended to be used is POST, but if the amount of information to be submitted to the server between form field names and values is very small (less than 255 characters) the method GET may be used.

If the form being submitted has file inputs, the POST method is used automatically.

Default value: ""

Associative array that enumerates the form fields that had their values changed after calling the function LoadInputValues. This variable may be used to determine which fields the user has changed before submitting the form. The loaded values are compared against the initial values of the fields as they were set with AddInput and SetInputValue functions.

The indexes of the entries of the array are set to the identifier names of the changed fields. The entry values are set to the values that the respective fields had before calling the LoadInputValues function.

Entries for radio and checkbox are set to an empty string if their prior state was not CHECKED. Entries for MULTIPLE select fields are set to an associative array that enumerates the values that changed in the selection list. The respective values are set to 0 for entries that were deselected and 1 for entries that were selected.

Default value: empty array

DisableReadOnlyInputs

Boolean flag that determines if the form inputs in read-only mode should be outputted as normal inputs with the DISABLED HTML attribute, or otherwise, as formatted text that represents the the input value.

Default value: 0

ExtraAttributes

List of extra attributes that should be added to the form's HTML tag when the form output is generated. The list should be defined as an associative array with the attribute names as array entry indexes and the attribute values as array entry values.

Default value: array()

Invalid

Associative array that enumerates the form fields that have invalid values after calling the function Validate.

The indexes of the entries of the array are set to the identifier names of the invalid fields. The entry values are set to the error messages associated to the first validation rule that the respective fields do not satisfy.

If the Validate function is called passing a specific sub-form name, only the fields that belong to that sub-form are considered.

The Validate function resets the Invalid variable before it starts validating the fields. The information about any fields considered invalid in previous Validate function calls is lost.

Default value: empty array

InvalidCLASS

Name of the default CSS class used to render invalid fields.

When set to a non-empty string, the specified value replaces the default CSS class attribute of the invalid fields listed in the Invalid forms class variable.

The specified CSS class name is also used to replace invalid fields' CSS class, when the form is validated on the client side using Javascript.

The value of the forms class InvalidCLASS variable can be overriden for fields defined with its own InvalidCLASS argument.

Default value: ""

InvalidSTYLE

Default CSS style attributes used to render invalid fields.

When set to a non-empty string, the specified styles are merged with the default CSS style attributes of the invalid fields listed in the Invalid forms class variable.

The specified CSS attributes are also used to replace invalid fields' CSS attributes, when the form is validated on the client side using Javascript.

The value of the forms class InvalidSTYLE variable can be overriden for fields defined with its own InvalidSTYLE argument.

Default value: ""

OptionsSeparator

String that is used to separate the values of MULTIPLE select fields when the form is outputted in ReadOnly mode.

Default value: "\n"

OutputPasswordValues

Boolean flag that determines if the form password fields values should be outputted with the respective field <input> tags.

For security reasons it is recommended to keep this flag set to 0. If a page with a form with a password field set to some value is cached when this flag is set to 1, somebody with access to the machine of the user browser may recover the password from the page cache file.

If you absolutely need to set this flag to 1, make sure you use the appropriate page headers to tell the user browsers to not cache the pages.

Default value: 0

ReadOnly

Boolean flag that determines if the form should be outputted as if the fields were set to a read-only mode. If this flag is set to 1 fields are outputted as text that represents their current state and values.

This flag must be set before starting defining the form output adding input parts. The read-only mode may be overridden individually for each input field using the Accessible property. Form output field parts added as hidden parts with the AddHiddenInputsParts function are always outputted as hidden input fields regardless of the value of the form ReadOnly flag and the input Accessible property.

Default value: 0

ResubmitConfirmMessage

Message to display when the user attempts to submit the same form more than once without waiting for the submission results to be displayed. This property may be used to prevent users from submitting the form multiple times inadvertently.

When the user attempts to submit the form again a confirmation requester is shown displaying the message defined by this property if it is set to a non-empty string. If this property is not set, the user is not stopped from submitting the form multiple times.

Default value: ""

Options

Options are special properties that only need to be changed in particular circumstances. Their default values are appropriate for normal operation.

ErrorMessagePrefix

Text to prepend to the error messages that are displayed or returned when invalid inputs are found.

Default value: ""

ErrorMessageSuffix

Text to append to the error messages that are displayed or returned when invalid inputs are found.

Default value: ""

ShowAlertOnError

Boolean flag that determines whether an alert message box should be used to display error messages when client side validation fails.

Set this option to 0 if you want to implement custom client side error message displaying overriding the default alert message box.

Default value: 1

ShowAllErrors

Boolean flag that determines whether after the form validation the class should show error messages associated to all invalid inputs or just the first invalid input.

This option affects the error messages shown in the error alert window displayed by the browser when a form with invalid inputs is submitted. It also affects the return value of the Validate function.

Multiple error messages are split by the end of line character sequence defined by the end_of_line.

Default value: 0

ValidateAsCreditCard

Name of the client side credit card number validation function that the Output method generates. Change this option only when you need to output more than one form with fields that require credit card number validation to avoid function name collision.

Default value: "ValidateCreditCard"

ValidateAsEmail

Name of the client side e-mail address validation function that the Output method generates. Change this option only when you need to output more than one form with fields that require e-mail address validation to avoid function name collision.

Default value: "ValidateEmail"

ValidationErrorFunctionName

Name of a client side validation function that the Output method generates. This function is called when the form is submitted but has validation errors. Change this option only when you need to output more than one form with fields that require client side validation to avoid function name collision.

Default value: "ValidationError"

ValidationFunctionName

Name of the client side validation function that the Output method generates. This function is called when the form is submitted. Change this option only when you need to output more than one form with fields that require client side validation to avoid function name collision.

Default value: "ValidateForm"

accessibility_tab_index

Name of the global function that is called to determine the number that should be assigned to the TABINDEX attribute the corresponding form field <INPUT> HTML tag. If the field does not have the TABINDEX attribute set and this option is set to a non-empty string the specified function is called passing the identifier of each input field as argument. The return value is assigned to the respective TABINDEX attribute.

Default value: ""

debug

Name of the global function that is called when one of the methods of the class fails due to invalid arguments. The error message is passed to the debug function right before returning from the failing method call. Change this option when you need to debug the code that uses the class to determine if is there any method call that is failing.

Default value: ""

decimal_regular_expression

Regular expression that is used to fields set with the option ValidateAsFloat and ValidationDecimalPlaces. The word PLACES in this variable value will be replaced by the value of the ValidationDecimalPlaces option.

Default value: "^-?[0-9]+(\\.[0-9]{0,PLACES})?\$"

event_parameter

Name of the parameter that is used to pass the name of the event that is passed by custom inputs in requests to handle events on the server side by the respective custom input classes.

The value of this option is use by the GetInputEventURL function to form an event handling URL.

Default value: "___event"

email_regular_expression

Regular expression that is used to validate an e-mail address text field.

Default value: "^([-!#\$%&'*+./0-9=?A-Z^_`a-z{|}~])+@([-!#\$%&'*+/0-9=?A-Z^_`a-z{|}~]+\\.)+[a-zA-Z]{2,6}\$"

encoding

Type of encoding that is used in the HTML document within which the form is integrated. This option determines how 8 bit characters are encoded. Currently, only iso-8859-1 (ISO Latin 1) encoding is supported. Change this option if your HTML document uses any other type of encoding. If you specify a different encoding, only <, > and " characters are encoded.

Default value: "iso-8859-1"

end_of_line

Sequence of characters that will be used to break the lines of the generated Javascript code.

Default value: \n

float_regular_expression

Regular expression that is used to fields set with the option ValidateAsFloat but not with the option ValidationDecimalPlaces.

Default value: "^-?[0-9]+(\\.[0-9]*)?([Ee][+-]?[0-9]+)?\$"

form_submitted_test_variable_name

Name of the client side global variable that it is used to store temporary information of whether there was a previous attempt to submit a form by the time the form is being submitted. Change this option if the default value defines a name that collides with global variables unrelated with the client side code generated by this class.

Default value: "form_submitted_test"

form_submitted_variable_name

Name of the client side global variable that it is used to store the information of whether the form was already submitted by the user. Change this option if the default value defines a name that collides with global variables unrelated with the client side code generated by this class.

Default value: "form_submitted"

input_parameter

Name of the parameter that is used to pass the identifier of a custom input field in requests to handle events on the server side by the respective custom input classes.

The value of this option is use by the GetInputEventURL function to form an event handling URL.

Default value: "___input"

sub_form_variable_name

Name of the client side global variable that it is used to store the sub-form name corresponding to the submit button that was used to submit the form. Change this option if the default value defines a name that collides with global variables unrelated with the client side code generated by this class.

Default value: "sub_form"

tolower_function

Name of the function to be called to convert a text string to lower case. This function is used when the Capitalization attribute of a text field is set to lowercase. Change this option when you can not guarantee that the system locale support is able to do case conversion of non-ASCII characters like those with accents and cedillas.

Default value: "strtolower"

toupper_function

Name of the function to be called to convert a text string to upper case. This function is used when the Capitalization attribute of a text field is set to uppercase. Change this option when you can not guarantee that the system locale support is able to do case conversion of non-ASCII characters like those with accents and cedillas.

Default value: "strtoupper"

Functions

FormCaptureOutput

Synopsis

$output=FormCaptureOutput($form,$arguments)

Purpose

Capture the output of a form object in a result text string.

Usage

The $form argument is a reference to an object created by this class. Make sure you pass the form object argument by reference to prevent inadvertent object replication when passing by value.

The $arguments argument is an associative array that takes pairs of tag names and values as defined for the class Output method. The Function argument is overridden by a custom global function that does the output capture.

The $output return value contains the form HTML output if the function call succeed. Otherwise it contains an empty string.

Template processing

Separating presentation from logic

To compose the layout of a form, the class needs to be called alternating HTML data definitions using AddInputPart calls and input field or label placements. However, this does not help the work of Web developers and designers because HTML code produced by the Web designer needs to be mixed with the programming of the developers, making the work of both harder to conceal and maintain.

To help solving this problem, a template engine could be used to separate the presentation work files from the programming logic work files. Currently there are two supported solutions to use templates to compose the output of forms: using plain HTML template files with embedded PHP commands to place the form inputs and labels, or using the Smarty template engine with a special plug-in to capture the template processing.

Plain HTML template files with embedded PHP code

PHP itself is already a template language. Since this form class needs to know in advance all the HTML data that will make part of the output and where the form inputs are located, the form layout HTML data needs to be added with the AddDataPart function before generating the whole form output.

An alternative way of defining the layout HTML data for the form output composition is to use PHP script output capturing support available since version 4.

This class is capable of capturing the current PHP script output by calling the function StartLayoutCapture. After calling this function and until the EndLayoutCapture function is called, all the script output is captured to compose the form output.

Plain HTML template files can be used to define the form layout by using the PHP include command. Just place PHP code sections in the points of the HTML template where the inputs and their labels will appear, using the class functions like AddInputPart and AddLabelPart. Here follows an example:

File: my_form_script.php


 <?php

   $form=new form_class;

   $form->AddInput(array(
     "NAME"=>"user_name",
     "TYPE"=>"text",
     "ValidateAsNotEmpty"=>1,
     "ValidationErrorMessage"=>"You have not specified the user name"
   ));

   $form->AddInput(array(
     "NAME"=>"password",
     "TYPE"=>"text",
     "ValidateAsNotEmpty"=>1,
     "ValidationErrorMessage"=>"You have not specified the password"
   ));

   $form->AddInput(array(
     "ID"=>"submit",
     "TYPE"=>"submit"
   ));

   $form->StartLayoutCapture();
   include("my_form_template.html.php");
   $form->EndLayoutCapture();

   $form->DisplayOutput();
?>

File: my_form_template.html.php


 <table>

 <tr>
 <th><?php
   $form->AddLabelPart(array(
     "FOR"=>"user_name",
     "LABEL"=>"<u>U</u>ser name",
     "ACCESSKEY"=>"U"
   ));
 ?>:</th>
 <td><?php $form->AddInputPart("user_name"); ?></td>
 </tr>

 <tr>
 <th><?php
   $form->AddLabelPart(array(
     "FOR"=>"password",
     "LABEL"=>"<u>P</u>assword",
     "ACCESSKEY"=>"P"
   ));
 ?>:</th>
 <td><?php $form->AddInputPart("password"); ?></td>
 </tr>

 <tr>
 <td colspan="2"><?php $form->AddInputPart("submit"); ?></td>
 </tr>

 </table>

Smarty template engine

One of the most popular template engines for PHP is Smarty. It generates PHP scripts that merge the HTML data from templates with the commands of code that execute actions and produce dynamically generated data. Once these scripts are generated, they do not need to be updated as long as the template files are not changed.

Given that even with the generation of processed templates in the form of PHP scripts that are cache, this solution is usually faster than most alternative template engines. However, keep in mind in the end you still need to load a large class that is the Smarty execution engine besides the compiled template script. So, the consumption of CPU and memory resources often is not negligible.

Smarty plug-in filter for form composition

Since the flexibility that is earned by separating presentation from logic motivates many developers to use Smarty, along with this forms class it is provided a plug-in pre-filter function that can be used with the Smarty engine to compose the forms presentation using templates.

The plug-in function is provided in a PHP include file named prefilter.form.php. Currently there are two versions of the plug-in, one for Smarty 2 and another for Smarty 3.

There is also an example form handling script named test_smarty_form.php that uses Smarty 2 with this plug-in function. The version for Smarty 3 is named test_smarty3_form.php. These scripts use a template file named form.tpl that contains the layout of the form defined in HTML.

Besides the HTML markup and the Smarty commands, the form template files may have special place holder marks that define where the form fields will be placed. Currently only three types of marks are supported: {input name="input"}, {hiddeninput name="input"} and {label for="input"}. If you changed Smarty mark left and right delimiters to other characters besides { and }, the form input and label marks must use those other delimiter characters.

The {input} mark specifies an input to be added to the form as it would be added with the AddInputPart. The {hiddeninput} mark specifies an input to be added to the form as a hidden input as it would be added with the AddInputHiddenPart. The {label} mark specifies where a label of a specified input to be added to the form as it would be added with the AddLabelPart.

The current version of this plug-in makes Smarty generate processed template scripts that refer to the object of the forms class referring to a global variable named $form. Make sure your forms class object is assigned to this global variable.

Enhancing forms with custom input type plug-ins

The forms class provides support for using custom form input types that can implement enhanced functionality over the basic HTML form input types.

The custom input types can provide support for sophisticated form handling features, like for instance, managing complex inputs made of several tightly coupled inputs, or providing enhanced usability by the means of special Javascript event handlers that can make the forms more interactive, thus avoiding long delays that make the user wait for needless Web server access round trips to perform special types of manipulation of the input values.

New custom form input types can be implemented by the means of separate plug-in classes, that can provide new form input functionality without requiring the developers to change the code of the main forms class.

Any developer can create new custom form input plug-in classes. Such classes may be distributed with their own license. Since the license of the main forms class is BSD like, it allows unrestricted distribution including of dependent components. So, the license of a plug-in class may be proprietary and it may even be distributed in a closed source format as a commercial product.

Custom input classes

A form input of a custom type is used very much like the regular types of input. It should be defined also using the forms class function AddInput. The main difference is that you need to specify the name of the class of the custom input using the CustomClass parameter of the AddInput function.

All custom input classes have a common API that is used by the main forms class to provide the custom behavior. New custom input classes should extend the form_custom_class. This class is defined in the forms.php file right before the main forms class.

The form_custom_class base class provides default behavior for all custom input classes by the means of several functions and variables. Some of those functions and variables have necessarily to be reimplemented in the custom input classes. The other functions and variables may be redefined only when necessary.

Basic steps for developing new custom input classes

If you are interested in developing a new custom input class, here follows a list of common steps that you should take:

Create a new custom input class

A new custom custom input class should be created by extending the form_custom_class base class. This base class provides default behavior that reduces significantly the effort that is necessary to implement a new custom input.

Implement the input initialization

The most important function of a custom input class is the AddInput function. It should check the parameter arguments passed to the function and initialize the class variables according to the needs.

If the new custom input is intended to manage a set of one or more new inputs, the AddInput function is the place where such inputs should be defined by using the main forms class AddInput function. Use the GenerateInputID function to create unique identifiers for those new inputs.

If the class is supposed to benefit from the automatic support for rendering from format templates, it should initialize the format and valid_marks class variables using the ParseNewInputFormat function.

This will let the class benefit from inheriting several functions from the base class without having to reimplement them like AddInputPart, AddHiddenInputPart, AddLabelPart and AddFunction.

Define the page head section or the load and unload events

Some inputs may need to load Javascript code, CSS styles or page meta tags that need to be inserted in the page head section, thus outside the form tags. If the new custom input needs this, it must implement the PageHead function.

If the custom input needs to define head tags only once, even when the form has multiple custom inputs of the same class, the ClassPageHead function should be implemented to define such tags.

Additionally, if it needs to execute Javascript code during the page load or unload events, it must implement the PageLoad or PageUnload functions respectively.

Retrieve input values

If the new custom input will have an associated input value that can be set or changed by the user, implement the GetInputValue function to provide a means for the applications that use the new form custom input to retrieve its current value.

Also, if the new custom input will emulate the behavior of a checkbox or radio, implement the GetCheckedState function to provide a means for the applications that use the new form custom input to retrieve its checked state.

Setting properties

If there are any properties that can be changed by the applications after the custom input is added to the form, implement the SetInputProperty function to handle property change requests, including for the main input VALUE property if supported.

Also, if the new custom input will emulate the behavior of a checkbox or radio, implement the SetCheckedState function to provide a means for the applications that use the new form custom input to change its checked state.

Validate input values

If the custom input value has to be validated according to specific rules, implement the ValidateInput function to enforce such rules. Make sure it is possible to configure details of such validation rules with either the AddInput or SetInputProperty functions, including the text to present to the user every time a rule is not satisfied. If the custom input does not need to perform server side validation, set the server_validate variable needs to be set to 1. In this case, the ValidateInput function does not need to be redefined.

If possible implement the GetJavascriptValidations function to specify the Javascript code and other details that will be used to enforce some or all of the types of validation rules on the client side. This helps improving the usability of the forms that use the new custom input. If the custom input needs to perform client side validation, make sure you set the client_validate variable to 1.

If the custom input is expected to be managed by another custom input, implement GetJavascriptInputValue function to make possible for the manager input to retrieve the custom input value on the client side with Javascript and perform any special type of validation or manipulation.

Load submitted input values

If the custom input class needs to perform some special action like updating its internal state values when the form values are loaded, implement the LoadInputValues function to define how to execute such special action.

Connecting inputs to trigger special actions upon client side events

In certain circumstances it may be useful to connect two or more inputs in such way that when a client side (user browser) event occurs in the context of a given input, it triggers the execution of actions in the context of other inputs.

For instance, when updating the quantity of a product in an order form, it would be useful to immediately update another field that shows the total value of the order.

This can be achieved using the Connect function. It associates a client side event in the origin input to an action that is executed in the context of a target input.

The base input types support a limited number of events and actions. New custom input classes can be developed to support more events and actions. Such custom input classes need to implement the Connect to handle new events and GetJavascriptConnectionAction to generate the necessary Javascript code that implements new actions.

Registering custom client side input events

The base custom input class provides means to automatically register custom input events.

An application just calls the Connect function to trigger the execution of an action on the context of a given input when the event occurs.

The base class implementation of that function registers the details of the event connection. The connections class variable is updated to keep event connection information. The Connect function only accepts registrations of connections for events with an entry already initialized in the connections variable.

When a custom input class needs to generate the Javascript code to execute the registered actions that handle the custom event, it just needs to call the base class GetEventActions function.

That function returns the Javascript code for the actions associated to the registered event connections. The actions Javascript code also includes the value for the respective event default action set in the events class variable.

Handling client side events on the server side

In certain circumstances a custom input may need to execute actions on the server side to handle special user interaction events.

This is the case, for instance, of highly interactive inputs that may communicate with the server using special purpose Javascript to pass request parameters to the server side in order to execute actions or retrieve information necessary to update their client side state or details of its presentation in the user browser.

In other circumstances a custom input may need to serve dynamically generated information to the browser that cannot be served when the form HTML is generated, like for instance, to present images with graphics generated dynamically.

In either case, these interactions with custom input on the client side and the respective custom input class, can be implemented with the HandleEvent function.

The HandleEvent class function examines the request parameters to determine which custom input is responsible for processing the request. Then it calls the HandleEvent function of the respective custom input class passing the name of the event and any additional parameters that may have been passed to the request.

A custom input class that expects to process event handling requests should execute the necessary actions and eventually server HTTP response headers and body that the browser will use to complete the interaction.

Forward client side events to custom inputs

A custom input may forward the request to handle an event received by the HandleEvent function. This may be useful to delegate the response of a client side event to a child input.

The class of the custom input receiving a event handling request just needs to call the PostMessage function of the main forms class, setting the message Target parameter to the identifier of the input to which the event should be forwarded. An input receiving a forwarded message must implement the PostMessage function.

Emulating form submit inputs

A custom input may emulate form submit inputs to provide additional behaviour. In that case, an input emulating form submit inputs may implement the WasSubmitted function.

The following sections provide detailed information on all the custom input public class functions and variables that are inherited from the custom input base class and can be reimplemented in new custom input classes.

Class variables

`children`

Array that stores the names of all the children inputs that have has parent the current custom input.

This variable is updated by the AddChild function and should not be redefined by the custom input class.

Format of an HTML template that defines how the custom input will be rendered. This format template is used by the AddInputPart function of the custom input base class to implement the default rendering method.

The syntax of the template consists of arbitrary HTML with special marks that define the position of place holder marks. These marks can appear in any position the format template value.

The special marks start and end with characters defined by the mark_start and mark_end respectively. The text value between the start and end marks defines the mark name.

The meaning of the mark name is defined by the valid_marks variable. Usually it specifies that the mark corresponds to one of several input fields that are managed by the custom input.

This variable should be redefined by the custom input class if it is intended to use the default rendering method provided by the custom input base class.

Default value: ""

Example value: "{day}/{month}/{year}"

`focus_input`

Identifier of the default input that is meant to get the input focus. That input may get the focus when:

A function of type focus or select_focus defined with AddFunction function is called.

The user clicks on the label associated with the input field using the AddLabelPart function.

The input has an invalid value when the user submits the form.

If this variable is set to an empty string, no input will get the focus.

This variable should be redefined by the custom input class if it is intended to use the automatic focus input association by the custom input base class.

Default value: ""

Example value: "date_day"

`input`

Identifier name of the current custom input. This is set by the main forms class when the custom input object is created.

It is assigned to the ID or NAME value specified by the current script as parameter of the AddInput function of the main forms class to add the custom input to the form definition.

It is meant to be used by any functions of the custom input class that need to know what is the name by which the main forms class registers the current custom input.

Default value: set by the main forms class

`mark_start`

Text that identifies the beginning of a place holder mark in format templates.

Usually this variable does not need to be redefined by the custom input class.

Default value: "{"

`mark_end`

Text that identifies the end of a place holder mark in format templates.

Usually this variable does not need to be redefined by the custom input class.

Default value: "}"

`server_validate`

Boolean flag that tells whether the custom input performs server side validation that occurs after any validations of base inputs that it may have as children.

This variable should be redefined or initialized when the AddInput function is called, if the custom input does not perform any server side validation.

Default value: 1

`valid_marks`

Associative array that specifies the meaning of names used in place holder marks used in the format template specified by the format variable.

This array has as entry indexes the types of elements to which each place holder is mapped when it is rendered by the custom input base class implementation of the AddInputPart function. Currently it supports the elements of type input, label and data.

The array values should be also associative arrays that map place holder mark names to the names of the elements that they will represent when the custom input is rendered.

This variable should be redefined by the custom input class if it is intended to use the default rendering method provided by the custom input base class.

Default value: array()

Example value:


 array(
   "input"=>array(
     "year"=>"date_year",
     "month"=>"date_month",
     "day"=>"date_day"
   ),
   "label"=>array(
     "year"=>"date_year"
   ),
   "data"=>array(
     "clock"=>'<img src="clock.gif" width="16" height="16" alt="Clock">'
   )
 )

Class functions

AddChild

Synopsis

$error=$input_object->AddChild($form, $name)

Purpose

Add the information of the name of a successfully added child input of a custom input.

This function is called when the AddInput function of the main forms class is called by the custom input class to add a child input.

This function should not need to be reimplemented in the actual custom input classes. The default implementation of the custom input base class stores the name of the child input in the children array class variable, so it may be used whenever the class needs to iterate over the children inputs.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $name argument is the identifier name of the just added child input.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

AddFunction

Synopsis

$error=$input_object->AddFunction($form, $arguments)

Purpose

Add the definition of a Javascript function that is meant to be generated as part of the output of the form. The function to be generated is meant to execute actions related with the elements of the form.

This function is called when the AddFunction function of the main forms class is called to add a function on a custom input element.

Usually this function does not need to be reimplemented in the actual custom input classes. The default implementation of the custom input base class calls the main forms class AddFunction on the input specified by the focus_input variable of the custom input object.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.

The $arguments argument is the array passed to the main forms class AddFunction function.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

AddInput

Synopsis

$error=$input_object->AddInput($form, $arguments)

Purpose

Initialize the custom input object with parameters that are meant to configure details of its behavior.

Usually it is used the create any basic inputs to be managed by the object of the custom input class, processing the format template and any other parameters specified by the input definition arguments.

This function is called when the AddInput function of the main forms class is called to add a custom input to the form.

This function needs to be reimplemented in the actual custom input classes.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used. Make sure you declare the $form argument to be passed by reference.

The $arguments argument is the array passed to the main forms class AddInput function.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

AddInputHiddenPart

Synopsis

$error=$input_object->AddInputHiddenPart($form)

Purpose

Add the input to the output that is generated for the form as if it was a hidden field.

Usually this function does not need to be reimplemented in the actual custom input classes if a format template and the list of valid marks is specified in the format and valid_marks custom input object variables.

Usage

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

AddInputPart

Synopsis

$error=$input_object->AddInputPart($form)

Purpose

Add the input to the output that is generated for the form.

Usage

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

AddLabelPart

Synopsis

$error=$input_object->AddLabelPart(&$form, $arguments)

Purpose

Add the label of the custom input to the output that is generated for the form with the main forms class Output method.

Usually this function does not need to be reimplemented in the actual custom input classes.

Usage

The $arguments argument is an associative array that takes pairs of tag names and values that define the properties of the label to be added to the form output, like it is defined for the AddLabelPart function of the main forms class.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

ClassPageHead

Synopsis

$html=$input_object->ClassPageHead($form)

Purpose

Retrieve the HTML code that is necessary to insert in the page head section to make all custom inputs of the same class work correctly.

This function is called once from the main forms class PageHead function for each class of the custom inputs.

This function needs to be reimplemented in the custom input classes that need special Javascript code, CSS styles, link or meta tags to be defined in the page head section.

Usage

The $html return value contains the necessary HTML tags that should be inserted in the page head section.

Connect

Synopsis

$error=$input_object->Connect($form, $to, $event, $action, $context)

Purpose

Handle the request to connect another form input to the custom form input in such way that when a given event occurs in the other input on the client side (user browser), it is triggered an action that is executed in the context of the custom input.

This function is called when the Connect function of the main forms class is called and the custom input is the connection target input.

This function needs to be reimplemented in the actual custom input classes that support executing actions in result of handling input events that occur in other inputs connected to the custom input.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $from argument is the identifier of the connection origin input on which it may occur the trigger event.

The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).

The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.

The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

DefaultConnect

Synopsis

$error=$input_object->DefaultConnect($form, $to, $event, $action, $context)

Provide a default implementation for the Connect function.

This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the Connect function to register actions to be associated to events supported by the custom input.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $from argument is the identifier of the connection origin input on which it may occur the trigger event.

The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).

The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.

The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

DefaultJavascriptGetConnectionAction

Synopsis

$error=$input_object->DefaultJavascriptGetConnectionAction($form, $form_object, $from, $event, $action, $context, $action)

Purpose

Provide a default implementation for the GetJavascriptConnectionAction function.

This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the GetJavascriptConnectionAction function to generate Javascript code for actions that are not directly generated by the custom input class. Currently, it just fails returning an error but that behavior may change in the future.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.

The $from argument is the identifier of the connection origin input on which it may occur the trigger event.

The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).

The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.

The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.

The $action argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

DefaultHandleEvent

Synopsis

$error=$input_object->DefaultHandleEvent($form, $event, $parameters, $processed)

Purpose

Provide a default implementation for the HandleEvent function.

This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the HandleEvent function to handle events that are not directly handled by the custom input class. Currently, it just fails returning an error but that behavior may change in the future.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $event argument is the name of the event that has occurred.

The $parameters argument is an associative array with all the parameters that were passed in the event handling request.

The $processed argument is used to pass a boolean variable by reference that is set by this function to indicate whether the event was processed by the function.

The $error return value contains an error message if there was an error while trying to process the specified event. Otherwise it contains an empty string.

DefaultPostMessage

Synopsis

$error=$input_object->DefaultPostMessage($form, $message, $processed)

Purpose

Provide a default implementation for the PostMessage function.

This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the PostMessage function to handle messages that are not directly handled by the custom input class. Currently, it just sends a reply to the posted message.

Usage

This function is usually called to handle forwarded messages to delegate the handling of client side events. It only needs to be implemented by custom classes that expect handling forwarded messages.

The $processed argument is used to return a boolean value by reference that is set by this function to indicate whether it finished handling the posted message or it generated more messages that need to be handled by other inputs.

DefaultSetInputProperty

Synopsis

$error=$input_object->DefaultSetInputProperty($form, $property, $value)

Purpose

Provide a default implementation for the SetInputProperty function.

This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the SetInputProperty function to support properties that are not directly implemented by the custom input class. Currently, it only implements the following properties:

Accessible
Format
SubForm

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $property argument is the name of the property to be changed.

The $value argument is the new value of the property.

The $error return value contains an error message if the specified property is not supported, or cannot be changed after the input has been created, or for some other reason the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.

GenerateInputID

Synopsis

$id=$input_object->GenerateInputID($form, $input, $kind)

Purpose

Helper function to generate input identifier names. It is meant to create names for basic inputs that make part of composite complex custom inputs.

For instance, a custom date input may be made of three basic inputs for the year, month and day. This function can be used to generate their names based on the identifier name of the custom input.

Usually this function does not need to be reimplemented in the actual custom input classes.

Usage

The $input argument is the base name of the input identifier to be generated. Usually it is the identifier name of the current custom input.

The $kind argument is a unique name of the kind input to which the resulting identifier will be assigned.

The $id return value is the generated input identifier.

GetContainedInputs

Synopsis

$error=$input_object->GetContainedInputs($form, $kind, $contained)

Purpose

Retrieve the list of inputs contained within the custom input.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $kind argument is a string that specifies the kind of contained input to be retrieved. Currently this argument is ignored. Set to an empty string for future compatibility.

The $contained argument is a reference to a variable that will be assigned by this function to an array of identifier strings of the contained inputs.

GetEventActions

Synopsis

$actions=$input_object->GetEventActions($form, $form_object, $event)

Purpose

Generate the necessary Javascript code that will be used to implement the actions registered with the Connect function.

This function is meant to be called by custom input classes that need to generate Javascript that will be associated to a given event.

This function is implemented by the base custom input class and should not be reimplemented by any other custom input class.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $event argument is the name of event for which it is being generated the handling Javascript code.

The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.

The $actions return value is the generated event handling Javascript code.

GetInputValue

Synopsis

$value=$input_object->GetInputValue($form)

Purpose

Retrieve the current value of the custom input, eventually combining the current values of any of the inputs that compose the custom input.

This function is called when the main forms class GetInputValue is called specifying the current custom input identifier as argument.

This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.

Usage

The $value return value is the current input value. It usually is a string but special types of inputs may return input values of other types. The custom input base class always returns an empty string.

GetJavascriptCheckedState

Synopsis

$javascript_value=$input_object->GetJavascriptCheckedState($form, $form_object)

Purpose

Generate a Javascript expression that represents the checked state of a the custom input field to be used to on client side scripts in Javascript.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.

The $javascript_value return value is a string that represents the given input field checked state in Javascript.

GetJavascriptConnectionAction

Synopsis

$error=$input_object->GetJavascriptConnectionAction($form, $form_object, $from, $event, $action, $context, $javascript)

Purpose

Generate the necessary Javascript code that will be used to implement the action that is executed when the trigger event occurs in a connected input.

This function is called when the main forms class generates the form output for the connection origin input, so it can assign the generated action Javascript code to the trigger event attribute definition.

This function needs to be reimplemented in the actual custom input classes that support executing actions in result of handling input events that occur in other inputs connected to the custom input.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.

The $from argument is the identifier of the connection origin input on which it may occur the trigger event.

The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).

The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.

The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.

The $javascript argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

GetJavascriptInputValue

Synopsis

$javascript_value=$input_object->GetJavascriptInputValue($form, $form_object)

Purpose

Generate a Javascript expression that represents the value of the custom input field expression that be used to on client side scripts in Javascript to retrieve the input value.

This function is called when the main forms class GetJavascriptInputValue is called specifying the current custom input identifier as argument.

This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.

The $javascript_value return value is a string that represents the custom input field value in Javascript.

GetJavascriptSetCheckedState

Synopsis

$javascript=$my_form_object->GetJavascriptSetCheckedState($form, $form_object, $checked)

Purpose

Generate a Javascript expression to set the checked state of the custom input field.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.

The $checked argument is a string that specifies the Javascript expression to set the given input checked state.

The $javascript return value is a string with Javascript statements to set the custom input checked state.

GetJavascriptSetInputProperty

Synopsis

$javascript=$input_object->GetJavascriptSetInputProperty($form, $form_object, $property, $value)

Purpose

Generate Javascript commands to assign the value of a property of the custom input field.

This function is called when the main forms class GetJavascriptSetInputProperty function is called specifying the current custom input identifier as argument.

This function needs to be reimplemented in the actual custom input classes if it supports changing any input properties from Javascript.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.

The $property argument is a string that specifies the name of the input property to be assigned. It should be VALUE for assigning the main input value.

The $value argument is a string that specifies the Javascript expression to assign to the given input property.

The $javascript return value is a string with Javascript statements to assign the given input property.

GetJavascriptValidations

Synopsis

$error=$input_object->GetJavascriptValidations($form, $form_object, $validations)

Purpose

Retrieve a list of validation tests that are meant to be performed on the client side using Javascript.

This function is called by the main forms class to generate the part of the form output that has the Javascript code that is going to be used to perform the client side validation tests.

The custom input tests are performed after all other input values are validated on the client side. So it is safe to assume that when the custom input tests are executed, all other input fields that are validated on the client side contain valid values.

This function needs to be reimplemented in the actual custom input classes if there are special types of validation tests that can be performed on the client side, besides other tests that are eventually performed on individual inputs that make part of a composite custom input.

Usage

The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.

The $validations argument is a reference to an array that will be initialized with entries that define details of each client side validation test.

Each entry of the $validations array is set to an associative array that specifies parameters of an individual test. Here follows the list of currently supported parameters:

Commands

Array that defines a list of arbitrary Javascript commands to be executed right before evaluating the actual validation test condition. These commands can be used to compute the expressions that will be used in the test condition.

Each entry in the array defines a line that will be added to the Javascript function generated by the class to validate the form on the client side. Entries with emptry strings are suppressed.

Condition

String that specifies a Javascript boolean expression that is evaluated to determine whether the input is valid. If the expression value is true, the field is invalid and no other validation tests are performed.

If the condition string is empty, no validation condition is evaluated.

ErrorMessage

String that specifies the error message that is displayed to let the user know why the input value is not valid. This error message must not be missing or empty, unless the condition string is empty.

Focus

String the specifies the identifier of the input that may get the input focus. Giving the focus to an input helps the user start correcting the input value right away.

This parameter is optional. If it is missing, the custom input class variable focus_input determines which input will get the focus. If this parameter is set to an empty string, no input will get the focus regardless of the value of the focus_input variable.

If you reimplement this function in custom input class, make sure you declare the $validations argument to be passed by reference.

Here follows an example of defined a special validation test that checks whether the day of a given month and year is valid:


 $day=$form->GetJavascriptInputValue($form_object,$this->day);

 $month=$form->GetJavascriptInputValue($form_object,$this->month);

 $year=$form->GetJavascriptInputValue($form_object,$this->year);

 $validations=array(
   array(
     "Commands"=>array(
       "month=".$month,
       "if(month=='04'",
       "|| month=='06'",
       "|| month=='09'",
       "|| month=='11')",
       "  month_days=30",
       "else",
       "{",
       "  if(month=='02')",
       "  {",
       "    year=parseInt(".$year.")",
       "    if((year % 4)==0",
       "    && ((year % 100)!=0",
       "    || (year % 400)==0))",
       "      month_days=29",
       "    else",
       "      month_days=28",
       "  }",
       "  else",
       "    month_days=31",
       "}",
       "date_day=".$day
     ),
     "Condition"=>"month_days<parseInt(date_day)",
     "ErrorMessage"=>$this->invalid_day_error_message,
     "Focus"=>$this->day
   )
 );

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

HandleEvent

Synopsis

$error=$input_object->HandleEvent($form, $event, $parameters, $processed)

Purpose

Execute any actions or return information in response to a request to handle an event sent by the by the browser that is presenting the form to the user.

This function is called by the forms class function also named HandleEvent when it determines that a given event handling request should be routed to this custom input object class.

$error=$input_object->ParseNewInputFormat()

Purpose

Validate and process the current input display format template.

It parses the format template defined by the format variable and validates it to verify whether it complies with definition of place holders specified by the valid_marks variable.

This function is used by the custom input base class when it renders the input with the AddInputPart function. It may also be used to validate a new format template defined from the parameters of the AddInput or SetInputProperty functions.

Usually this function should not be reimplemented in the actual custom input classes.

Usage

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

PostMessage

Synopsis

$error=$input_object->PostMessage($form, $message, $processed)

Purpose

Handle a message targetted to the input.

Usage

This function is usually called to handle forwarded messages to delegate the handling of client side events. It only needs to be implemented by custom classes that expect handling forwarded messages.

ReplyMessage

Synopsis

$error=$input_object->ReplyMessage($form, $message, $processed)

Purpose

Handle a message sent in reply to a previously posted event message.

Usually this function should be reimplemented in the actual custom input classes that post event handling messages.

Usage

The $message argument is the same associative array of the message sent with the PostMessage function. It may contain new or altered entries to specify details that may trigger different actions when the message reply is processed.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

SetInputProperty

Synopsis

$error=$input_object->SetInputProperty($form, $property, $value)

Purpose

Change the value of a specific property of the custom input.

This function needs to be reimplemented in the actual custom input classes to support setting properties that can be changed after the creation of the custom input with the AddInput function.

Usage

The $property argument is the name of the property to be changed.

The $value argument is the new value of the property.

SetSelectOptions

Synopsis

$error=$input_object->SetSelectOptions($form, $options, $selected)

Purpose

Set the list of options and selected values of a custom input that implements a behavior similar to a select input type.

This function is called when the SetSelectInput function of the main forms class is called for a custom input class.

This function needs to be reimplemented in the actual custom input classes that implement inputs similar to the select input type.

Usage

The $form argument is a reference to the forms class object on which this custom input is being used.

The $options argument is an associative array that defines the list of options, like for the OPTIONS argument passed to AddInput function.

The $selected argument is array that defines the values of the list of options that should be selected, like for the SELECTED argument passed to AddInput function.

The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.

ValidateInput

Synopsis

$error_message=$input_object->ValidateInput($form)

Purpose

Validate the current value of the custom input.

This function is called by the main forms class Validate function after it has successfully validated all the basic type inputs. So, it is safe to retrieve from the ValidateInput function valid values of any basic inputs managed by a custom input class.

This function needs to be reimplemented in the actual custom input classes if they need to perform special types of validation besides the validations that are already performed on the basic inputs managed by custom input classes.

Usage

The $error_message return value is a message suitable to present to the user that explains why the current input value is invalid. If the input value is valid, this return value should be an empty string.

WasSubmitted

Synopsis

$submitted_input=$my_form_object->WasSubmitted($form, $input)

Purpose

Determine if a form was submitted by the custom input.

Usage

The $input argument specifies the identifier of the custom input or an empty string of the class is checking which of the form fields was submitted.

Available custom input plug-ins classes

The forms class distribution comes with separate custom input plug-in classes that are ready to implement Web forms based user interfaces with sophisticated controls that provide complex functionality and enhanced usuability.

Here follows the list of available custom input classes. More will be made available later.

`form_ajax_submit_class`

Purpose

Submit a form in the background without reloading the current page.

Features

Submits the current form using an hidden inline frame. It works with most browsers that support inline frames, including to submit forms with file upload inputs.

Can perform global or sub-form validation before submitting the form.

Can set the values of one or more inputs right before submitting the form. This can be used to trigger the form submission upon distinct browser side events, each one setting different input values. That makes possible to distinguish on the server side which browser side event triggered the form submission.

Can send AJAX GET requests with custom parameters. This can be used to send AJAX requests to perform interaction with the server without submitting the form.

Can set the feedback messages to appear in a given page element when certain browser side events happen like form submission, submission response completely sent, or server communication timeout.

Handles timeout events by aborting the form submission when the server does not respond within a configurable timeout period. The action that is executed when a timeout occurs is also configurable.

Prevents submitting a form more than once using the same inline frame.

Implements several types of actions defined on the server side to be executed on the browser side in response to a form submission.

Multiple actions may be defined dynamically to be executed within the same form submission. The definition of an action does not require that the developer has prior Javascript knowledge.

Currently supported actions include altering the HTML contents of parts of the current page, redirecting the browser to a new page, setting the value of document element, waiting for a given period, etc..

Can emit custom headers before outputting the AJAX response. It can be useful to signal the Web server that it is an AJAX response that may need special treatment, like avoiding HTTP dechunking or compression in order to reduce response delivery delays.

A debug console can be opened in the form page to exhibit information about the data being sent and received from the browser, as well the actions being executed in response to the AJAX request.

Properties

CompleteFeedback

HTML code to display within the page feedback element when the form submission response is completely sent to the browser by this plug-in class.

Default value: ""

DebugConsole

Identifier of the page element within which a debug console should appear displaying information about the communication that happens during AJAX requests.

Default value: ""

Feedback (changeable)

Contents of the feedback page element.

This property can only be set while the AJAX response to a form submission is being sent. If it is set as an AddInput parameter, its value is ignored.

Default value: ""

FeedbackElement (changeable)

Identifier of a page element within which feedback messages may appear when certain browser side events occur. Usually, the feedback page element is a <div> or <span>, but it may be of other type. This plug-in is not responsible for generating feedback elements. It only updates the contents of the specified page feedback element when a certain event occurs.

Currently, the events that can make the feedback page element be updated are the form submission and server communication timeout. The messages that appear in the feedback element are defined by the SubmitFeedback and TimeoutFeedback properties respectively. It may also be set using the Feedback property while the AJAX response to a form submission is being sent.

Default value: ""

SubmitFeedback

HTML code to display within the page feedback element when the form is submitted by this plug-in class.

Default value: ""

TargetInput

Identifier of the input to which the form submission event messages will be forwarded. If this property is not set, the event messages will be queued for retrieval by the application.

Default value: none

Timeout

Limit of time in seconds that a browser should wait to retrieve the form submission response from the server.

Default value: 60

TimeoutFeedback

HTML code to display within the page feedback element when the communication with the server times out.

Default value: ""

ONCOMPLETE

String with Javascript code to execute the form submission is completely sent to the browser.

Default value: none

ONTIMEOUT

String with Javascript code to execute the form submission takes more time to return its response than the configured timeout value.

Default value: "alert('The communication with the server has timed out.');"

ONSUBMITTED

String with Javascript code to execute after an AJAX form submission is sent.

Default value: none

ResponseHeader

Custom HTTP response header that may be sent before outputting the AJAX response. An empty string, means no custom header is outputted.

Default value: ""

Example: "X-no-gzip-compress: yes"

Event connection actions

This custom input implements two types of action that can be triggered on the browser side: Submit and Load.

The Submit action is used to trigger the AJAX POST form submission. The Submit action supports the context arguments SetInputValue, SubForm and Validate.

The SetInputValue argument can be used to specify a list of inputs that should be set right before submitting the form. The argument value must be an associative array. The indexes of the array are the input names. The array values are the respective values of there inputs to set.

The SubForm argument can be used to restrict the validation that is performed before the form is submitted to a sub-form with the specified name.

The Validate argument is a boolean flag that indicates whether the form should be validated before submitting it via AJAX. By default the form is always validated.

The Load action is used to submit an AJAX GET request with custom parameters, thus without having to submit the form. The Submit action supports two context arguments named Parameters and RandomParameter.

The Parameters argument should be an associative array that defines the names and values of the parameters to send with the AJAX GET request.

The RandomParameter argument should be the name special parameter that will be initialized with a random value with the purpose to avoid eventual browser caching of the GET response.

Messages

When an AJAX submit custom input captures an AJAX form submission, it can post messages to the form message queue to let an application process the AJAX request and define how it should be responded to execute the desired actions on the browser page from which the form was submitted.

submit

Currently, the AJAX submit input only posts submit type messages.

Message parameters

Immediate

Immediate is a boolean parameter preset to 0. Applications should set it to 1 before replying to a message to instruct the AJAX submit input immediately send the response defined by the Actions response parameter, even if the response is not finished.

More

More is a boolean parameter preset to 0. Applications should set it to 1 before replying to a message, to instruct the AJAX submit input send the response defined by the Actions response parameter, but the response is not finished.

When the AJAX submit input receives a message response with this parameter set to 1, it posts the submit message again.

Window

Window is a string parameter set to an expression that evaluates to the main browser Javascript Window object. It can be used to generate Javascript expressions that need to access to that object.

Document

Document is a string parameter set to an expression that evaluates to the main browser Javascript Document object. It can be used to generate Javascript expressions that need to access to that object.

Form

Form is a string parameter set to an expression that evaluates to the current Javascript Form object. It can be used to generate Javascript expressions that need to access to that object.

SubForm

SubForm is a string parameter that may be set to the name of the sub-form associated to the form submission. This parameter is only set if the submit action context also specifies a sub-form parameter.

Response parameters

Actions

Actions is an array response parameter that should contain one or more entries to define which actions must be executed when the AJAX request response is sent to the browser.

Each action entry is defined by an associative array that defines the detail parameters of the action.

Common action parameters

Action

Action is the name of the type action. Currently supported actions are:

AppendContent

Append HTML to a given document element.

Command

Execute an arbitrary Javascript code.

Connect

Execute Javascript associated to an action executed in the context of another input.

PrependContent

Prepend HTML to a given document element.

Redirect

Instruct the browser to redirect to a new page URL.

ReplaceContent

Replace a given document element with new HTML content.

SetInputProperty

Change a property of a given input.

SetInputValue

Change the value of a given input.

SetValue

Change the value of a given document element property.

Wait

Wait for a given period of time.

Action specific parameters

AppendContent
PrependContent
ReplaceContent

Container

Identifier of the document element that will be altered.

Content

HTML data that defines the content alteration.

Command

Command

Javascript code to execute.

Content

HTML data that defines the content alteration.

Connect

To

Identifier of the input which will execute the connection action.

ConnectionAction

Name of the action to execute.

Context

Array with context data to pass when executing the action.

Redirect

URL

URL of the new page to redirect.

SetInputProperty

Input

Identifier of the input.

Property

Name of the input property to set.

Value

Expression that defines the value to set the input property.

SetInputValue

Input

Identifier of the input.

Value

Expression that defines the value to set the input.

SetValue

Element

Identifier of the document element.

Property

Identifier of the document element property to set. If the property is a variable of the document element object, you can use . to specify which object is it.

Value

Value to set the document element property.

(Optional) Type

Type of the value to set. Currently supported data types are: string, number, float, integer, boolean, undefined, null, opaque. opaque should be used for a value defined by an expression of an arbitrary type.

Default: "string"

Wait

Time

Period of time to wait in seconds. It must not be zero. It may be an integer or a floating point number to specify decimal periods of time.

Example


 /*
  * Create a form object.
  */
 $form = new form_class;
 $form->NAME = 'some_form_name';

 /*
  * The form submission method must be POST.
  */
 $form->METHOD = 'POST';

 /*
  * Make the form be submitted to the current script.
  */
 $form->ACTION = '';

 /*
  * Add some fields.
  */
 $form->AddInput(array(
  'TYPE' => 'text',
  'NAME' => 'login',
  'ID' => 'login',
  'LABEL' => '<u>L</u>ogin',
  'ACCESSKEY' => 'L'
 ));
 $form->AddInput(array(
  'TYPE' => 'text',
  'NAME' => 'password',
  'ID' => 'password',
  'LABEL' => '<u>P</u>assword',
  'ACCESSKEY' => 'P'
 ));
 $form->AddInput(array(
  'TYPE' => 'submit',
  'NAME' => 'doit',
  'ID' => 'doit',
  'VALUE' => 'Submit'
 ));

 /*
  * Add the AJAX form submit custom input.
  */
 $form->AddInput(array(
  'TYPE' => 'custom',
  'NAME' => 'sender',
  'ID' => 'sender',
  'CustomClass' => 'form_ajax_submit_class',
  'Timeout' => 60,
  'ONTIMEOUT' => 'alert('The communication with the server has timed out.');'
 ));

 /*
  *  Make the submit button to the AJAX form submit custom input to make
  *  the form be submitted via AJAX when the submit button is clicked.
  *  Other client side events could trigger AJAX form submission.
  */
 $form->Connect('doit', 'sender', 'ONCLICK', 'Submit', array());

 /*
  *  Call HandleEvent to let the custom input to let
  *  the class handle the AJAX form submission
  *
  *  Do not output anything before these lines.
  */
 $form->HandleEvent($processed);
 if($processed)
  exit;

 /*
  *  Was the form submitted via AJAX?
  *  Check whether the AJAX form submit input posted a message.
  */
 if($form->GetNextMessage($message))
 {

  /*
   *  The form was submitted via AJAX.
   *  Lets process the messages to build an AJAX response and
   *  update only the relevant parts of the page on the browser
   */
  do
  {
   /*
    * Check what kind of events did occur on the browser?
    */
   switch($message['Event'])
   {
    case 'submit':

     /*
      * The form was submitted. Lets validate and process it.
      */
     $form->LoadInputValues();
     $error_message = $form->Validate($verify);

     /*
      * If the form fields are valid, make any other
      * server side only validations
      */
     if(strlen($error_message)==0)
     {
      $error_message = ValidateLoginAndPassword(
       $form->GetInputValue('login'),
       $form->GetInputValue('password')
      );
     }

     /*
      *  Are there any form validation errors?
      */
     if(strlen($error_message))
     {

      /*
       * Tell the form submitter input to send to the browser
       * an order to display validation error feedback message.
       *
       * Replace the contents of the tags <div id="feedback"></div>
       * with a validation error message.
       *
       * Make sure the message is correctly encoded in HTML using
       * HTMLSpecialChars function.
       */

      $message['Actions'] = array(
       array(
        'Action' => 'ReplaceContent',
        'Container' => 'feedback',
        'Content' => 'Validation error: '.HtmlSpecialChars($error_message);
       )
      );
     }
     else
     {

      /*
       *  The form was validated without errors.
       *  Lets execute the form processing actions
       */

       /* Some processing actions should be executed here */

      /*
       *  Show some feedback on the browser page.
       */
      $message['Actions'][] = array(
       'Action' => 'ReplaceContent',
       'Container' => 'feedback',
       'Content' => 'The form was submitted and processed successfully!'
      );

      /*
       * Wait a few seconds before redirecting
       * the browser to a new page.
       */
      $message['Actions'][] = array(
       'Action' => 'Wait',
       'Time' => 3
      );
      /*
       * Redirect the browser to a new page.
       */
      $new_page = GetEnv('REQUEST_URI');
      $message['Actions'][] = array(
       'Action' => 'Redirect',
       'URL' => 'http://'.GetEnv('HTTP_HOST').$new_page
      );
     }
     break;
   }

   /*
    * Reply to the form submit event to make it respond
    * to the AJAX request in such way to make the browser
    * execute to response actions.
    */
   if(strlen($form->ReplyMessage($message, $processed)))
    exit;
  }

  /*
   * Loop until there are no more event messages
   * or the processing was finished
   */
  while(!$processed
  && $form->GetNextMessage($message));

  /*
   * If the request was fully processed, lets exit the script.
   */
  if($processed)
   exit;
 }

 /*
  * Here validate, process and output the form
  * like with any normal non-AJAX form submission
  */

`form_animation_class`

Purpose

Manage visual effects to be applied to elements of a form page.

Features

It can manage any number of animations running simultaneously. Each animation consists of a sequence of distinct visual effects. The effects are executed one after another until the sequence ends.

The animations can be defined to run when events on other form page elements occur.

Different animations can be configured to run in debugging mode. On this mode, error messages are displayed when animation setup errors are detected.

Requirements

Javascript animation class

This class requires a Javascript animation class to actually perform the animation effects. The Javascript class is available with this PHP class as a separate file named animation.js.

This PHP class generates the necessary HTML script tags to include the Javascript class file in the HTML page head section. Applications should use the main forms class PageHead function to retrieve the page head section tags that include the animation Javascript class file.

Properties

JavascriptPath

Directory of the URI of the Javascript class file animation.js. If the directory of the URI of the current script if the same of the animation.js file, just leave this property set to an empty string.

Default value: ""

Event connection actions

This plug-in class implements only one action that can be triggered on the browser side. That action is named AddAnimation. It is used to a given animation to the list of running animation.

The definition of the animation should be passed to the action context parameter. This parameter is an associative array with entries to define several animation properties. Currently, it supports the following properties:

Debug

Integer value that defines the level of the debug mode. 0 means that debugging is disabled. 1 or more makes the class display alert messages when animations define effects that may not be applied due to animation definition errors or impossible situations.

Effects (Required)

Array with the definition of each effect in the animation sequence. Each entry of the array is an associative that describes the effect properties. Currently, the following properties are supported:

Animation

Name of the animated associated to the effect. It is required by the CancelAnimation effect.

Content

HTML tags of the content to use by the effect. It is required by the AppendContent, PrependContent and ReplaceContent effects.

Duration

Duration of the effect in seconds. It is required by the FadeIn, FadeOut and Wait effects.

DynamicElement

Javascript expression that defines dynamically the identifier of the page element to apply the effect. It is required in alternative to the Element property.

Element

Identifier of the page element to apply the effect. It is required by the AppendContent, FadeIn, FadeIn, Hide, PrependContent and ReplaceContent and Show effects.

Type (Required)

Name of the type of effect. Currently it supports the following effect types:

AppendContent

Insert more HTML tags at the end of the content of a given page element.

CancelAnimation

Stop and remove an animation given its name.

FadeIn

Make a given hidden page element appear smoothly until it becomes completely visible.

FadeOut

Make a given page element disappear smoothly until it becomes completely invisible.

Hide

Turn a given page element invisible.

PrependContent

Insert more HTML tags at the beginning of the content of a given page element.

ReplaceContent

Replace the HTML tags contained within a given page element.

Show

Turn a given page element visible.

Wait

Wait a given period of time.

Visibility

Defines the CSS property that will be used to control the visibility of an element for the effects: FadeIn, FadeIn, Hide, and Show. It may be set to either visibility or display. The default is visibility.

Name

Name to associate to the animation being defined.

Window

Javascript expression that defines the Window object on which the animation will run. It is necessary if it is intended to run an animation on a browser window or frame distinct from the one that is starting the animation.

`form_auto_complete_class`

Purpose

Automatically complete the values typed by the user in a text input by presenting a menu with a list of possible words that start with the text typed so far.

Features

A menu is displayed below the text input with the list of possible completion words.

The text completion is case insensitive.

The completion values can be retrieved on demand from the server using AJAX, or loaded all at once within the form page.

The completion words can be rendered in the menu with arbitrary HTML formatting.

The completion words menu can be browsed using the up or down cursor keys. The enter and escape keys close the menu.

An optional button input may be used to make the menu show all the possible options at once, regardless of what the user typed in the text input.

Requirements

AJAX form submit class

In dynamic mode, this class needs the custom input plug-in class form_ajax_submit_class to retrieve the completion values on demand from the server.

Properties

CompleteDelay

Delay in seconds that the input should wait after the last keystroke before it attempts to complete the text typed by the user.

Default value: 0.5

CompleteInput

Identifier of the text input that will have the typed text automatically completed. This class does not add the text input to the form. It must be added separately by the application.

Default value: none

CompleteMinimumLength

Minimum number of characters that the user must have typed before the class attempts to complete the text.

Default value: 3

CompleteFeedback

HTML code to display within the page feedback element when the completion AJAX request is finished. This option is only relevant in the dynamic mode.

Default value: ""

CompleteValues

Associative array that enumerates all possible completion values. The indexes of the array are the completion text strings. The array values define the HTML code used to present the completion options in the menu.

Default value: not set

Dynamic

Boolean flag that determines whether the completion values are retrieved on demand from the server using AJAX, or are loaded all at once within the page Javascript code generated by this class.

Default value: 0

FeedbackElement

Identifier of a page element within which feedback messages may appear when the completion is performed dynamically using AJAX. This option is only relevant in the dynamic mode.

Default value: ""

ItemClass

Name of the presentation style class with which the menu items should be rendered.

Default value: not set

ItemStyle

Definition of the presentation style attributes with which the menu items should be rendered.

Default value: "padding: 1px; color: #000000;"

MenuClass

Name of the presentation style class with which the menu should be rendered.

Default value: not set

MenuStyle

Definition of the presentation style attributes with which the menu should be rendered.

Default value: "background-color: #ffffff; border-width: 1px; border-color: #000000; border-style: solid; padding: 1px;"

SelectedItemClass

Name of the presentation style class with which the menu items should be rendered when they are selected.

Default value: not set

SelectedItemStyle

Definition of the presentation style attributes with which the menu items should be rendered when they are selected.

Default value: "padding: 1px; color: #ffffff; background-color: #000080;"

ShowButton

Identifier of the button input that will trigger the action to make the menu display all the available options at once. This class does not add the button input to the form. It must be added separately by the application.

Default value: none

SubmitFeedback

HTML code to display within the page feedback element when a completion AJAX request is submitted to the server. This option is only relevant in the dynamic mode.

Default value: ""

Timeout

Limit of time in seconds that a browser should wait to retrieve the completion AJAX request response from the server. This option is only relevant in the dynamic mode.

Default value: 60

TimeoutFeedback

HTML code to display within the page feedback element when the communication with the server times out. This option is only relevant in the dynamic mode.

Default value: ""

`form_captcha_class`

Purpose

CAPTCHA is a designation that means: a Completely Automated Public Turing test to tell Computers and Humans Apart.

It is a kind of tests that are used to make it dificult for automated programs to have access to certain resources by imposing challenges that are easy to respond for humans but much harder to solve for the automated programs.

This custom input type implements a CAPTCHA test by requiring that the user enters a text that is presented in an image that appears next to a text input.

Robot programs will have difficulty to determine what is written in the image as it may appear too obfuscated to be read even by OCR programs (Optical Character Recognition).

This kind of custom input is often used to prevent abuses of sites that are accessed by robot programs to perform automated tasks like for instance retrieving all pages of a site in a very short period or even retrieving pages restricted to a limited number of users.

Features

It generates a text input with a validation image of customizable size with a text displayed in a random position of the image.

The image can be obfuscated with an optional noise image that is drawn over the text also in a random position.

It also presents a button to let the users request that the image be redrawn with the text and the noise image in a different position where it may be less difficult to read.

The text is generated randomly with an optional validation expiry period. When the expiry period is reached the current text is not accepted as valid and a new text is generated.

The class does not use sessions or cookies to keep track of the text that is displayed by the image. Instead, it uses a private server side key that is used to encrypt the text and the creation time that is passed in an event handling request to the class that decrypts the text to generate the validation image.

Requirements

The GD image library extension

The class requires the PHP is configured to use the GD image library extension. Certain versions of the GD library do not support GIF images. In this case, the PNG or JPEG formats must be used.

The mcrypt library extension

The class requires the PHP is configured to use the mcrypt library extension to be able to encrypt the validation text.

Properties

BackgroundColor (changeable)

Color to be used to clear the background of the verification image. It must be in the hexadecimal RGB format: #RRGGBB. If it is set to an empty string it will appear with transparent background or white in case the image is generated in a format that does not support transparency.

Default value: ""

ExpiryTime

Number of seconds of the time for which the validation text generated by the class remains valid. It must be a value greater than 0. If it is not set the text never expires.

Default value: not set

ExpiryTimeValidationErrorMessage

Error message to return when the input value is not valid because the validation time expired. This property is required if the ExpiryTime property is set.

Default value: not set

Font (changeable)

Specify number of the font that will be used to render the verification text. It can be either a font number from 0 to 5 to use a font built-in the GD library, or a custom font number returned by functions for opening fonts of other types.

Default value: 2

Format (changeable)

Format of the template that defines how the input elements will be presented. There are four supported place holders for defining how the image, validation text, redraw button and the encrypted validation key fields will be presented: image, text, redraw and validation.

Default value: "{image} {text} {redraw}{validation}"

ImageAlign (changeable)

Specify the type of vertical alignment of the verification image, like with the ALIGN attribute of the HTML IMG tag.

Default value: "top"

ImageFormat (changeable)

Specify the type of format that the verification image will be generated. The supported formats are: gif, jpeg, png.

Default value: "gif"

ImageHeight (changeable)

Specify the height with which the verification image will be generated.

Default value: 20

ImageWidth (changeable)

Specify the width with which the verification image will be generated.

Default value: 80

InputClass

Name of the presentation style class with which the text input field should be rendered.

Default value: not set

InputExtraAttributes

List of extra attributes that should be added to the text input HTML tag when the form output is generated.

Default value: not set

InputStyle

Definition of the presentation style attributes with which the text input field should be rendered.

Default value: not set

InputTabIndex

Order of navigation of the text input field when using the tab key, as defined by the HTML TABINDEX attribute.

Default value: not set

Key (required)

Private key that is used to encrypt the text that is passed back in a separate request to the class to draw and output the image.

Default value: not set

NoiseFromGIFImage (changeable)

Specify the name of the image file in the GIF format that will be used as visual noise to obfuscate the text in the verification image. It must be a transparent image, or else the validation text will not be visible.

Default value: ""

NoiseFromPNGImage (changeable)

Specify the name of the image file in the PNG format that will be used as visual noise to obfuscate the text in the verification image. It must be a transparent image, or else the validation text will not be visible.

Default value: ""

RedrawClass

Name of the presentation style class with which the redraw submit input should be rendered.

Default value: not set

RedrawStyle

Definition of the presentation style attributes with which the redraw submit input should be rendered.

Default value: not set

RedrawSubform (changeable)

Text to be used in the redraw submit button.

Default value: "Redraw"

RedrawText (changeable)

Text to be used in the redraw submit button.

Default value: "Redraw"

ResetIncorrectText (changeable)

Boolean flag that determines whether the verification text should be changed to a new value when the user enters an incorrect text.

Default value: 0

TextColor (changeable)

Color to be used to draw the validation text. It must be in the hexadecimal RGB format: #RRGGBB.

Default value: "#000000"

TextLength (changeable)

Number of characters that will have the validation text.

Default value: 4

ValidationErrorMessage (required)

Error message to return when the input value does not match the validation text presented in the image.

Default value: not set

VerificationClass (changeable)

Name of the presentation style class with which the verification image should be rendered.

Default value: not set

VerificationStyle (changeable)

Definition of the presentation style attributes with which the verification image should be rendered.

Default value: not set

`form_date_class`

Purpose

Let the user specify a date of the calendar with year, month and day.

Features

It generates select inputs for the day and month and a text input for the year.

It can validate any date between the years 1 and 9999 AC. The validation can be performed either on the client side and server side. It supports restricting the accepted period between given start and end dates.

It can ask the user to enter an age relative to today's date rather than a specific date. The plug-in class subtracts the number of years, months and days entered by the user from today's date to compute the actual date.

The submitted date value is returned in the ISO 9601 format (YYYY-MM-DD) but the date can be presented in any other format definable in the application that creates the form. The text that is displayed for the months may also be redefined.

Optionally the date input may show a checkbox to let the user decide whether he wants to choose a date manually or assume a given default.

Properties

Accessible

The same as the Accessible property for basic inputs.

Default value: not set

AskAge

Boolean flag that indicates the plug-in class to ask the user for an age relative to today's date.

Default value: 0

ChoiceDefaultValue

Default value to be used when the ChooseControl option is set whether checkbox that appears should be initially set.

Default value: 0

Choose

Boolean flag that indicates when the ChooseControl option is set whether checkbox that appears should be initially set.

Default value: 0

ChooseControl

Boolean flag that indicates whether the date input should show a checkbox to let the user decide whether he wants to choose a date manually or assume a given default.

Default value: 0

DayClass

Name of the presentation style class with which the day input field should be rendered.

Default value: not set

DayStyle

Definition of the presentation style attributes with which the day input field should be rendered.

Default value: not set

FixedDay

Set the date day to a fixed value that cannot be changed by the user.

Default value: not set

Format (changeable)

Format of the template that defines how the date will be presented. There are three supported place holders for defining how the year, month and day fields will be presented: year, month and day.

Default value: "{year}-{month}-{day}" or "{year}-{month}" when HideDay parameter is set to 1

HideDay

Hide the day field so it is not displayed to the user. This parameter may only be set to 1 if the FixedDay parameter is also set.

Default value: 0

MonthClass

Name of the presentation style class with which the month input field should be rendered.

Default value: not set

MonthStyle

Definition of the presentation style attributes with which the month input field should be rendered.

Default value: not set

Months

Associative array that defines the text for each of the 12 months of the year. The array entry indexes go from "01" to "12".

Default value: array with all entry values set to the entry indexes

Optional

Boolean flag that determines whether the date input value is not required. An optional date field is accepted as valid when either the year, month and day fields are empty. In this case, the GetInputValue function returns an empty string.

Default value: 0

SelectYears

Integer value that is used to determine whether year input will be displayed as input of type text or select.

If the ValidationStartDate and ValidationEndDate arguments are defined and the number of years between the two dates is less than the value of the SelectYears argument, the year is presented as a select type input with the given range of years as option values.

Default value: 10

TABINDEX

Order of navigation of the input fields when using the tab key, as defined by the HTML TABINDEX attribute. When not set, all fields will have the same TABINDEX property value.

Default value: none

VALUE (changeable)

Current value of the date. An empty string means, date not set. It may also be set to "now" as an alias to the current day date.

Default value: ""

ValidationDateErrorMessage

Validation error message for when the user specifies a date that does not exist on the calendar.

Default value: "It was not specified a valid date."

ValidationDayErrorMessage

Validation error message for when the user specifies an invalid day.

Default value: "It was not specified a valid day."

ValidationErrorMessage

Default validation error message.

Default value: not set

ValidationEndDate

Day of the end of the range of allowed dates. It may be set to "now" as an alias to the current day date.

Default value: "9999-12-31"

ValidationEndDateErrorMessage

Validation error message to present when the current date is set to a day after the end date.

Default value: default validation error message

ValidationMonthErrorMessage

Validation error message for when the user specifies an invalid month.

Default value: "It was not specified a valid month."

ValidationStartDate

Day of the start of the range of allowed dates. It may be set to "now" as an alias to the current day date.

Default value: "0001-01-01"

ValidationStartDateErrorMessage

Validation error message to present when the current date is set to a day before the start date.

Default value: default validation error message

ValidationYearErrorMessage

Validation error message for when the user specifies an invalid month.

Default value: "It was not specified a valid year."

YearClass

Name of the presentation style class with which the year input field should be rendered.

Default value: not set

YearStyle

Definition of the presentation style attributes with which the year input field should be rendered.

Default value: not set

`form_html_editor_class`

Purpose

Let the user edit an HTML document visually.

Features

The user can enter text and format it using toolbar buttons.

Is based on a JavaScript library that works with the most important browsers.

Fallback to a simple textarea in case JavaScript support is disabled in the browser.

Can insert custom template marks that presented with configurable preview HTML.

Can expand implicitly custom template marks in the HTML despite they may not be visible.

Can use a custom CSS stylesheet for the HTML document.

Properties

CLASS

Name of the presentation style class with which the editor container should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.

Default value: not set

COLS

Number of rows of the editor as defined for the COLS attribute of the <TEXTAREA> HTML tag.

Default value: not set

ExternalCSS

URI of the CSS file that defines styles for use in the editor frame.

Default value: not set

JavascripPath

Directory of the URI of the Javascript class file html_editor.js. If the directory of the URI of the current script if the same of the html_editor.js file, just leave this property set to an empty string.

Default value: ""

Mode

Name of the editing mode. Valid modes are visual for the visual editor and html for the HTML editor.

Default value: "visual"

ROWS

Number of columns of the editor as defined for the COLS attribute of the <TEXTAREA> HTML tag.

Default value: not set

ShowToolbars

Boolean flag that determines whether the editor toolbars are displayed.

Default value: 1

STYLE

Definition of the presentation style attributes with which the editor container should be rendered.

Default value: not set

TemplateVariables

Associative array that defines the properties of the supported template variables. The array entry names are the names of the variables. The array values are also associative arrays that define template property values. Currently the following template properies are supported:

Alternatives

Associative array that defines all the supported alternative values of template. The array entry names are the alternative variable names. The array entry values are also associative arrays that define properties of the alternative values. Currently only the Preview and Title are supported. They have the same meaning as for the main template variable properties.

Default value: not set

Inline

Boolean flag that determines whether the template variable should be displayed as inline or block element of the HTML document. If this option is omitted, the variable will be expanded to the value passed to the Value property.

Default value: none

Preview

HTML to be used when displaying the template variable preview in the visual editor.

Default value: not set

Title

Text to be used for the template variable in the insert template menu.

Default value: not set

Value

HTML value to expand the template variable when the Inline variable is not set.

Default value: not set

`form_layout_paged_class`

Purpose

This custom input type can be used to display a group of inputs that appear in pages that the user can switch clicking on tab buttons.

Features

This kind of custom input can be used to split the layout of large forms in several smaller forms with inputs split over multiple pages.

Only one page is displayed at a time. The pages are rendered near a set of tabs. Each tab corresponds to one page. When the user clicks on a tab, the corresponding page is displayed and the previously displayed page is hidden.

This plug-in generates the necessary Javascript to switch the form pages to display without having to reload the Web page when the user clicks on the tabs.

If Javascript is disabled when the user clicks on a tab, the form is submitted to the server to be rendered again, showing just the page that corresponds to the clicked tab.

This plug-in also generates the necessary stylesheet definitions to render the tab buttons. The tabs appear like separators of printed documentation bindings with tabs to quickly go to specific sections of the documentation.

The tabs are rendered in such way to give a 3D look effect to make it clear to the user which is the currentlty selected tab. In some browsers these tabs appear with rounded borders. Alternatively, the page tabs and buttons may be rendered using custom CSS classes.

The tab buttons are rendered in a row one after another. When there are too many tab buttons, there is the possibility to split the buttons in several rows to make them occupy less width.

By default, each page displays only one input per page. However, the input displayed on each page may be a layout input that manages the presentation of multiple inputs.

The presentation of the each page may also be customized using a sub-class of the form_layout_paged_class with a function named AddPagePart. This function takes just one parameter, which is the identifier of the current page to be rendered.

A page may appear with a fade-in effect when the user clicks on the respective tab button.

When a validation error occurs, the page with the first invalid field is switched automatically.

Can automatically adjust the size of the container of all pages to avoid the resizing that happens when it switches to a new page of a different size.

Properties

AutoAdjustSize

Boolean flag that indicates whether the size of the container of the pages should be adjusted automatically to fit all pages.

Default value: 0

CurrentPage (changeable)

Identifier of the page that appears selected initially.

Default value: first page

FadePagesTime

Time in seconds that it will take the fade effect to make switched pages appear smoothly. It may be a floating point number to express a value below 1 second. Set to 0 to disable the page fade effect.

Default value: 0

JavascriptPath

Directory of the URI of the Javascript class files necessary to implement animation effects.

Default value: ""

PageClass

TabClass

GapClass

PageButtonClass

TabButtonClass

Name of alternative CSS classes that define how certain elements will be rendered, like: tab of the current page, tab of other pages, gaps between tabs, button of the current page, and button of other pages.

Default value: ""

Pages

Associative array that defines parameters of each form page. The keys of the entries of this array are the identifiers of the pages. The array entry values should be also associative arrays that define the respective page parameters.

Here follows the list of currently supported parameters:

Name (required)

Name to display in the respective page tab.

Default value: the same as the page identifier

Caption

Text to display in each page as a caption to explain the purpose of the page fields.

Default value: none

Break

Name of the option to specify whether the respective page tab button should break the row of tab buttons on which it is displayed.

This option may be either "before" or "after" depending on whether the row of buttons should be split before or after the current page tab button.

Default value: none

Event connection actions

This custom input implements one types of action that can be triggered on the browser side: SwitchPage.

The SwitchPage action is used to switch the currently selected page. It supports the context arguments Page and InputsPage.

The Page argument can be used to specify the identifier of a page to be switched.

The InputsPage argument can be used to specify an expression that references a Javascript object whose members are input identifiers, and the member values are pages to be switched. This argument is used internally to automatically switch the current page when the form has invalid fields.

`form_layout_vertical_class`

Purpose

This custom input type can be used to automatically compose the layout of a group of inputs that should appear vertically align.

Features

This kind of custom input can be used to quickly layout many or even all inputs of a form without the need for manually written HTML templates.

The list of inputs are rendered as a sequence of rows. The layout of each input row is defined by an HTML template that contains marks to specify where and how each input rendered, as well the input label and a mark to denote that the input is invalid, required or optional.

This input can check the list of inputs considered invalid on the last call to the Validate function and render them with a special invalid input mark.

The default templates for the input rows can be customized for all inputs or only for specific inputs.

Individual inputs can be made read-only or invisible depending on a condition value, so they are ommited from the form output or not be editabled under certain circumstances.

Can display inputs in multiple side-by-side columns.

Properties

Columns

Bidimensional array that lists groups of identifiers of all the inputs to be included in the layout in side-by-side columns.

Default value: none

Data

Associative array that specifies which of the inputs listed by the Inputs property should be rendered with custom HTML data. The keys of the entries of this array are the names of the data inputs and the entry values should the HTML data that should be rendered for the row of the respective data inputs.

Default value: none

DefaultMark

HTML text string that defines how to render the input special mark for inputs that are not flagged as invalid.

Default value: empty string

Footer

HTML text string that defines what should be rendered after the sequence of input rows.

Default value: </table>

Header

HTML text string that defines what should be rendered before the sequence of input rows.

Default value: <table>

InputFormat

HTML template that defines how each input row should be rendered. It must have marks named {input}, {label} and {mark} to denote where the input, label and a special input mark respectively should appear in the input row.

Default value: <tr><td valign="top">{label}:</td><td valign="top">{input} <span id="mark_{id}">{mark}</span></td></tr>

Inputs

Array that lists the identifiers of all the inputs to be included in the layout.

Default value: none

InvalidMark

HTML text string that defines how to render the input special mark for inputs that are flagged as invalid.

Default value: empty string

NoLabelInputFormat

HTML template that defines how each input row should be rendered for inputs that do not have an associated label.

Default value: <tr><td colspan="2" align="center">{input}</td></tr>

Properties

Associative array that defines special properties to override the default way each input row is rendered. The keys of the entries of this array are the names of the inputs and the entry values should more associative arrays that define the respective input rendering properties.

Here follows the list of currently supported properties:

CenteredPair

Name of the position that determines whether the input should be presented grouped horizontally with the next inputs within the same row. If this property is left, middle or right, the respective input appears respectively on the left, middle or right of the centered group of inputs. Multiple inputs may be in the middle.

Currently, only inputs without labels can be presented as centered pairs.

Default value: none

DefaultMark

HTML text string that overrides the DefaultMark property value.

InputFormat

HTML template that overrides the InputFormat property value.

InvalidMark

HTML text string that overrides the InvalidMark property value.

ReadOnly

Boolean flag that determines whether the input should be rendered in read-only mode. If this property is 1, the respective input cannot be edited.

Default value: 0

Visible

Boolean flag that determines whether the input row should appear in the form output. If this property is 0, the respective input row is ommited from the form output.

Default value: 1

SwitchedPosition

Boolean flag that determines whether the input row should present the input and the label in switched positions. If this property is 1, the respective input appears in the place of the label and vice-versa.

Default value: 0

CenteredPairLeftInputFormat

HTML template that defines how each input row should be rendered for inputs that have the CenteredPair property set to left.

Default value: <tr><td colspan="2" align="center">{input} 

CenteredPairRightInputFormat

HTML template that defines how each input row should be rendered for inputs that have the CenteredPair property set to right.

Default value: {input}</td></tr>

SwitchedPositionInputFormat

HTML template that defines how each input row should be rendered for inputs that have the SwitchedPosition property set.

Default value: <tr><td align="right">{input}</td><td>{label} <span id="mark_{id}">{mark}</span></td></tr>

`form_linked_select_class`

Purpose

This custom input type implements a select input that can let the user choose one or more options from multiple groups of options.

The current group of options may be switched dynamically on the client side when it changes the value of another input to which this custom input is linked.

Features

This kind of custom input can be linked to any type of input, including custom inputs of this or other classes. An unlimited number of this kind of custom inputs can be linked in cascade.

The width and height of the input can be automatically adjusted according to the length of the text of the largest option of all groups and the group with more options.

It supports select inputs of single or multiple selected options.

Properties

This custom input type supports most of the properties of base select input type.

Groups

Associative array that contains all the groups of options that may be displayed. The keys of the entries of this array are the names of the groups and the entry values should be more associative arrays that define each group of options as defined by the OPTIONS attribute of the base select type input.

Default value: none

LinkedInput

Identifier of the input linked to this custom input that defines the group of options that is currently in use. The current value of the linked input defines the current group of options. When the value of that input changes, the group of options of this custom input is switched.

Default value: none

Dynamic

Boolean flag that tells whether the alternative groups of options should be dynamically retrieved by the browser when the linked input changes. When this option is set to 1, each group of options is retrieved from the server using Javascript and an hidden inline frame. Otherwise, the groups of options are passed all at once within the Javascript code that is generated with the form HTML.

The non-dynamic mode lets the linked input options be switched immediately, but for large groups of options the form page may become very large and slow to load. The dynamic mode is recommended when using large groups of options, or when the options need to be retrieved from a slow storage medium, like for instance a database. Look at the custom input sub-classes that are specialized in retrieving options from databases and other data sources.

Default value: 0

AutoWidthLimit

Limit number of columns of width that this input will have initially. If this property is set and the Dynamic property is not set, the class will determine which is the longest option of all the specified groups of options. If the property is set to 0 the class sets the initial display width of the select input to the length of the longest option in em units. If this property is more than 0, the initial display width is set to no more columns than the value of this property.

Default value: not set

AutoHeightLimit

Limit number of rows of height that this input will have. If this property is set and the Dynamic property is not set, the class will determine which is the longest group of options of all the specified groups. If the property is set to 0 the class sets the number of rows of the select input the count of options of the longest group. If this property is more than 0, the number of rows is set to no more than the value of this property.

Default value: not set

`form_list_select_class`

Purpose

This custom input type implements an emulation of a select input that allows to configure the presentation of the options as rows of a table with customizable HTML content.

Features

It works in a compatible way with the regular select input.

It can display the option elements in a table with rows with customizable HTML data for each option. The headers of the options table are configurable.

The options table can be displayed in a container with limited height that may scroll.

It uses radio inputs for single select lists and checkbox for multiple select inputs. An additional checkbox input is displayed to toggle the selection of all options of multiple select lists.

Properties

This custom input type supports most of the properties of base select input type.

Accessible

Boolean option to tell whether the input is accessible when the form is in read only mode, or not accessible otherwise.

Default value: none

CLASS

CSS style used to render the list select container.

Default value: none

Columns

Array of options that defines how each column of the list select table will be rendered. Each entry contains an associative array that defines properties of each table column. Here follows the list of supported properties:

Header

HTML that will be displayed in the column header row.

Default value: none

Row

Name of the entry of the array passed by the Rows parameter from which it will be displayed the data for the current column.

Default value: none

Type

String that defines the type of the column. If the type is Input, the column will display a radio input to select the respective option. If the type is Data, the column will display data from the array passed by the Rows input parameter. If the type is Option, the column will display data from the respective option value.

Default value: Data

Default value: array( array( 'Type'=>'Input', ), array( 'Type'=>'Option', ), )

MULTIPLE

Boolean option to tell whether the list will be a single or multiple select list.

Default value: 0

ONCHANGE

Javascript code to be executed when the selected input changes.

Default value: none

OptionReadOnlyMark

HTML that defines what should be displayed in the place of each option input if the input is displayed as not accessible.

Default value: none

OPTIONS

Associative array that defines the values and text of a select field as defined for the OPTION HTML tag.

Default value: none

ReadOnlyMark

HTML that defines what should be displayed if the input is displayed as not accessible.

Default value: none

Rows

Associative array with data to be displayed in the list select table. The array keys are the names of the select options. The array keys are also associative arrays with the rows of data.

Default value: none

SELECTED

Array of values of selected options when in multiple mode.

Default value: none

SIZE

Number of rows that occupies container of the list select table. The size of the container is defined in em units, so it may not match exactly the number of list select table rows that will be made visible.

Default value: none

STYLE

CSS style definition that will be used to render the list select container.

Default value: border-style: solid; border-color: #808080 #ffffff #ffffff #808080; border-width: 1px

VALUE

Value of the selected option.

Default value: none

`form_map_location_class`

Purpose

This custom input type lets the user specify a location in the world by pointing it on a map. The input retrieves the latitude and longitude coordinates of the selected location.

Features

The Google Maps API is used to render and browse the maps.

The user can specify a location by clicking in any point on the map, or by entering the latitude and longitude coordinates in separate text inputs.

The currently selected location is denoted by a marker icon. Initially, the selected locations appears on the center of the map.

The text inputs of the coordinates of the selected may be rendered according to a configurable presentation template. These inputs may also be hidden.

The map may present additional markers in application defined locations. Each marker may have a custom information window that appears when the mouse is over the marker. The marker may also have a custom tooltip title. When the user clicks on the marker icon, a new page may be opened on the same or a separate browser window.

The zoom level can be set explicitly, or automatically by defining the coordinates of a bounding box that must fit in the current map size. The zoom level may also be adjusted to fit the area defined by the set of location markers.

The GetJavascriptSetInputProperty function can be used to generate Javascript commands to change the Latitude and Longitude properties from Javascript.

The maps can show advertising from Google AdSense to credit a given publisher.

Can locate an address on the map using the Google Maps API geocoding support. The address to be searched can be taken from another input.

Can cluster one or more groups of custom markers in case they overlap in the same region.

Requirements

Google Maps API key

The Google Maps API requires an unique key to work on the pages of each site. The key may be obtained for free in the Google Maps API signup page.

Page head, load and unload

Most of HTML and Javascript generated for this kind of custom input must be inserted in the page head section. Applications that use forms with this custom inputs must call the main forms class PageHead function to retrieve the necessary HTML tags to be inserted within the page head section.

This kind of input must be initialized from the page body load event. Use the main forms class PageLoad function to retrieve the necessary Javascript code to assign to the ONLOAD attribute of the page BODY HTML tag.

To avoid memory leak bugs of certain browsers, special Javascript code must be executed from the page body unload event. Use the main forms class PageUnload function to retrieve the necessary Javascript code to assign to the ONUNLOAD attribute of the page BODY HTML tag.

Properties

Accessible

Boolean flag that determines whether the input should accessible. When the input is not accessible, it displays the map but the coordinates of the location point cannot be changed.

Default value: 1

AdsManager

Associative array that specifies whether the maps may show advertising from Google AdSense to be credited to a given publisher. The array may contain values that define options for controlling aspects of the advertising.

Channel

Identifier of the publisher account channel to be associated with advertising that is displayed.

Default value: none

MaxAdsOnMap

Limit number of advertising units that can be displayed in the map.

Default value: 2

Publisher

Identifier of the AdSense publisher account. Usually starts with ca-pub-.

Default value: none

BoundsOffset

Value to adjust the coordinates bounding box to set the zoom level automatically when the ZoomMarkers property is specified. A positive value makes the bounding box expand.

Default value: none

CLASS

CSS stylesheet used to render the <div> tag on which the map will appear.

Default value: none

Clusters

Array that defines one or more marker managers that may cluster multiple markers in case they overlap in the current zoom level. Each cluster is described by an entry of the array. Each cluster entry should be an associative array that defines several cluster properties. Here follows the list of currently supported cluster properties:

Manager

Name of the type of cluster that will aggregate the markers. Currently only the MarkerClusterer marker manager is supported.

Default value: none

Path

Path URL of the script that defines the marker manager Javascript class. For MarkerClusterer marker manager the default path is markerclusterer.js.

Default value: none

Controls

Associative array that specifies which additional built-in controls will be displayed on the map. The array entry indexes specify the control names. The entry values specify more associative arrays to define properties to customize details of the controls. The supported controls are: "SmallMap", "LargeMap", "SmallZoom", "Scale", "MapOverview" and "MapType". Currently no control properties are supported.

Default value: none

Coordinates

Boolean flag that determines whether the coordinate values should be displayed along with the map.

Default value: 1

HideMarker

Boolean flag that determines whether the location marker should not be displayed.

Default value: 0

Icons

Associative array that defines any custom icons that may be needed. The array keys are names assigned to each custom icon. The array values are associative arrays that define icon properties as described in the Google Maps documentation. Currently the following properties are supported: image, shadow, printImage, mozPrintImage, transparent, dragCrossImage, iconSize, shadowSize, dragCrossSize, iconAnchor, infoWindowAnchor, dragCrossAnchor, maxHeight and imageMap.

Default value: none

Key

Unique key to enable the access to the Google Maps API. A different key must be used for each site on which this API is used. The API key may be obtained for free in the Google Maps API signup page.

Default value: none

Format

Format of the template that defines how the map and coordinate text inputs will be presented. There are seven supported place holders for defining how each input and label will be outputted: map, latitude, latitudelabel, longitude, longitudelabel, zoom and maptype.

Default value: "{map}\n<br />\n<div>{latitudelabel} {latitude} {longitudelabel} {longitude}</div>\n{zoom}\n{maptype}"

Latitude (changeable)

Initial latitude coordinate value of the selected map location.

Default value: 0.0

LatitudeClass

CSS stylesheet used to render the latitude text input.

Default value: none

LatitudeLabel

Label for the latitude text input.

Default value: "Latitude:"

LatitudeStyle

CSS style definition used to render the latitude text input.

Default value: none

Longitude (changeable)

Initial longitude coordinate value of the selected map location.

Default value: 0.0

LongitudeClass

CSS stylesheet used to render the longitude text input.

Default value: none

LongitudeLabel

Label for the longitude text input.

Default value: "Longitude:"

LongitudeStyle

CSS style definition used to render the longitude text input.

Default value: none

MapType

Type of rendering used to display the map. There are three types of map rendering: Normal for rendering maps as colored polygons, Satellite for display satellite photographs, and Hybrid for rendering roads as polygons over satellite photographs.

Default value: "Normal"

MarkerIcon

Name of a custom icon to be used as the marker.

Default value: none

Markers

Array that defines additional custom markers to display on the map. Each marker is described by an entry of the array. Each marker entry should be an associative array that defines several marker properties. Here follows the list of currently supported marker properties:

Cluster

Name of the cluster that will aggregate the markers that overlap in the current zoom level for being in the same region.

Default value: none

Information

HTML string that defines the contents of the marker information window. This window opens when the mouse is over the marker.

Default value: none

Icon

Name of a custom icon to be used as the marker.

Default value: none

Latitude

Latitude coordinate value of the marker location.

Default value: none

Link

URL of the page to be opened when the user clicks on the marker icon.

Default value: none

Longitude

Longitude coordinate value of the marker location.

Default value: none

Title

Title text to associate to the marker. Usually it appears as a tooltip when the mouse is over the marker, like with the HTML TITLE tag.

Default value: none

Target

Name of the window or frame on which the page specified the Link marker property will be opened. If this marker property is not specified, the page will be opened on the same browser window.

Default value: none

NoCoordinatesFormat

Format of the template that defines how the map and coordinate text inputs will be presented when the coordinates are not displyed. There are five supported place holders for defining how each input and label will be outputted: map, latitude, longitude, zoom and maptype.

Default value: "{map}\n{latitude}\n{longitude}\n{zoom}\n{maptype}"

STYLE

CSS style definition used to render the <div> tag on which the map will appear.

Default value: none

ValidationErrorMessage

Error message to display when the user enters invalid coordinate values.

Default value: "It was not specified a valid location."

ZoomBounds

Array that defines the coordinates of a bounding box that must fit in the current map size. The zoom level will be adjusted to assure that the given coordinates will be visible. The array must have the four coordinates of the bounding box: South latitude, East longitude, North latitude and West longitude.

Default value: none

ZoomMarkers

Boolean option that determines whether the zoom level and the map center should be adjusted to fit all the markers on the visible portion of the map.

Default value: none

ZoomLevel

Level of zoom to display the map. 0 means show the whole world. Higher values make the map display an area closer to the selected location. The maximum accepted zoom level depends on the zone of the world.

Default value: 0

Event connection actions

This custom input implements one type of action that can be triggered on the browser side: LocateAddress.

The LocateAddress action is used to send a request to the Google Maps API to find the location of an address. The address value to be located is taken from another form input. If found, the map center and the mark location are set to the coordinates of the located address.

The LocateAddress action supports the context arguments Address, Country and CountryValue.

The Address argument can be used to specify the input from which the address to be located will be taken.

The Country argument can be used to specify an input from which will be taken the name of the country to restrict the search for the address.

The CountryValue is an option that determines how the of the name of the country to be searched will be retrieved from the input specified by the Country option. It can be either Value to use the current input value, or SelectedOption to use the text value of the current option of the country input.

`form_mdb2_auto_complete_class`

Purpose

This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.

It uses the PEAR::MDB2 API to execute the SQL queries that retrieve auto-complete texts. PEAR::MDB2 is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.

Properties

This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.

CompleteValues

No longer applies.

Connection

Database connection object as returned by the function MDB2::connect. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.

Default value: not set

CompleteValuesQuery

SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark {BEGINSWITH} to specify where it will be inserted the SQL LIKE pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.

Default value: not set

CompleteValuesLimit

Maximum number of result entries that will be displayed in the auto-complete menu.

Default value: 10

`form_mdb2_linked_select_class`

Purpose

This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.

It uses the PEAR::MDB2 API to execute the SQL queries that retrieve groups of options. PEAR::MDB2 is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.

Properties

This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.

Groups

No longer applies.

Dynamic

Same meaning but the default value has changed.

Default value: 1

Connection

Database connection object as returned by the function MDB2::connect. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.

Default value: not set

OptionsQuery

SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark ? to specify where the group identifier value should be used.

Default value: not set

DefaultOption

Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.

Default value: not set

DefaultOptionValue

Text value associated to the option specified by the DefaultOption parameter.

Default value: not set

GroupsQuery

SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.

Default value: not set

`form_metabase_auto_complete_class`

Purpose

This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.

It uses the Metabase API to execute the SQL queries that retrieve auto-complete texts. Metabase is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.

Properties

This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.

CompleteValues

No longer applies.

Connection

Database connection setup handle as returned by the function MetabaseSetupDatabase.

Default value: not set

CompleteValuesQuery

Default value: not set

CompleteValuesLimit

Maximum number of result entries that will be displayed in the auto-complete menu.

Default value: 10

`form_metabase_linked_select_class`

Purpose

This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.

It uses the Metabase API to execute the SQL queries that retrieve groups of options. Metabase is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.

Properties

This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.

Groups

No longer applies.

Dynamic

Same meaning but the default value has changed.

Default value: 1

Connection

Database connection setup handle as returned by the function MetabaseSetupDatabase.

Default value: not set

OptionsQuery

Default value: not set

DefaultOption

Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.

Default value: not set

DefaultOptionValue

Text value associated to the option specified by the DefaultOption parameter.

Default value: not set

GroupsQuery

SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.

Default value: not set

`form_mysql_auto_complete_class`

Purpose

This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a MySQL database rather than from static arrays.

Properties

This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.

CompleteValues

No longer applies.

Connection

Database connection handle as returned by the functions mysql_connect or mysql_pconnect.

Default value: not set

CompleteValuesQuery

Default value: not set

CompleteValuesLimit

Maximum number of result entries that will be displayed in the auto-complete menu.

Default value: 10

`form_mysql_linked_select_class`

Purpose

This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.

It uses the PHP MySQL functions directly to execute the SQL queries that retrieve groups of options.

Properties

This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.

Groups

No longer applies.

Dynamic

Same meaning but the default value has changed.

Default value: 1

Connection

Database connection setup handle as returned by the functions mysql_connect or mysql_pconnect.

Default value: not set

OptionsQuery

SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark {GROUP} to specify where the group identifier value should be used.

Default value: not set

DefaultOption

Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.

Default value: not set

DefaultOptionValue

Text value associated to the option specified by the DefaultOption parameter.

Default value: not set

GroupsQuery

SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.

Default value: not set

`form_scaffolding_class`

Purpose

This custom input type can be used to compose and process forms for manipulating entries of records, stored for instance in databases, by the means of common CRUD actions: Create, Read, Update and Delete.

It can display a listing of entries to be edited with links to edit or delete such entries. An additional link is displayed to let the user create a new entry.

Features

The create, read, update and delete actions can be enabled or disabled as needed by the application.

Initially, a listing of entries is presented as a table with columns that display the values of different entry properties.

The listing table may show different background colors for odd and even rows. A special color may be used to highlight the row under the mouse pointer.

Optional pagination links may be displayed to let the user browse long listings of entries split over multiple pages.

The listing rows for each entries may present links to trigger actions to edit or delete the respective entry. A separate link is displayed to trigger the action to create a new entry.

The create, update and delete actions present a form with a configurable list of inputs to let the user set the entry properties.

The form for creating or editing entries may show an optional submit button to show a preview of the entry being edited. Another optional button can be used to let the user save the entry and continue editing.

The texts of all feedback messages are configurable.

Several actions may trigger accesses to the server using AJAX to minimize server interaction access by avoiding page reloading. If Javascript support is disabled in the browser, the interactions will gracefully fallback to regular page reloading accesses.

Requirements

form_ajax_submit_class

This plug-in class is necessary to interact with the server without page reloading.

form_layout_vertical_class

This plug-in class is necessary to automatically layout the inputs of the forms for editing or deleting entries.

Properties

CancelLabel

Text for the cancel submit button.

Default value: Cancel

Create

Boolean option to determine whether the plug-in will present a form to create a new entry and a link to start the create form next to the existing entries listing.

Default value: 1

CreateCanceledMessage (changeable)

HTML of the message that should be displayed when the new entry creation form was canceled.

Default value: Creating a new entry was canceled.

CreatedMessage (changeable)

HTML of the message that should be displayed when a new entry is created successfully.

Default value: A new entry was created successfully.

CreateMessage (changeable)

HTML of the message that should be displayed initially along with the new entry creation form.

Default value: Create a new entry

CreatePreviewMessage (changeable)

HTML of the message that should be displayed when showing a preview of a new entry in the creation form.

Default value: New entry preview

Columns (changeable)

Array with entries that define the way each column in the entries listing should be displayed.

Each entry in this array should be set to an associative array that defines the respective column properties.

Default value: array()

Column properties

Class

CSS class used to display values of the column.

Default value:

Delete

Boolean option to tell whether the column should display a link to start the delete form for the respective row entry.

Default value: 0

Format

HTML template that may define how the column values are displayed.

Default value: use the value directly

FormatParameters

Associative array that defines how each template placeholder should be replaced.

The keys of the array are the template placeholder marks. The values of the array entries define properties that describe how to generate the values that will replace the placeholders.

Default value: array()

Template placeholder properties

Column

Number of the column from which the default template placeholder value should be retrieved.

Default value: current column number

HTML

Boolean option to tell that the value should be encoded as HTML before displaying.

Default value: 0

Map

Associative array that determines how values should be mapped to alternative HTML representations.

Default value: array()

MapNull

Value to use when the column value is undefined.

Default value:

Replace

Associative array that defines a list of regular expressions that will be used to find and replace column values.

Default value: array()

Header

HTML to display in the header row of the column.

Default value:

HTML

Boolean option to tell that the column value should be encoded as HTML before displaying.

Default value: 0

ID

Boolean option to tell whether the column values have the respective entry identifiers.

Default value: 0

Map

Associative array that determines how values should be mapped to alternative HTML representations.

Default value: array()

MapNull

Value to use when the column value is undefined.

Default value:

Replace

Associative array that defines a list of regular expressions that will be used to find and replace column values.

Default value: array()

Style

CSS style used to display values of the column.

Default value:

Update

Boolean option to tell whether the column should display a link to start the update form for the respective row entry.

Default value: 0

View

Boolean option to tell whether the column should display a link to display an entry.

Default value: 0

CustomParameters

Associative array with custom parameters and values that applications need to pass to each page to keep context.

Default value: array()

Delete

Boolean option to determine whether the plug-in will present a form to delete existing entries and links in the entries listing to start the delete form to confirm the deletion of the respective entries.

Default value: 1

DeleteCanceledMessage (changeable)

HTML of the message that should be displayed when an existing entry delete form was canceled.

Default value: Deleting the entry was canceled.

DeletedMessage (changeable)

HTML of the message that should be displayed when an existing entry is deleted successfully.

Default value: The entry was deleted successfully.

DeleteFields

Array with the definitions of each input that will be used in the forms to delete entries.

Default value: array()

DeleteLabel

Text for the delete links and submit button.

Default value: Delete

DeleteMessage (changeable)

HTML of the message that should be displayed along with the entry delete form.

Default value: Are you sure you want to delete this entry?

Editing (get only)

Boolean flag that tells whether the user is creating, updating or deleting an entry.

Entry (changeable)

Identifier of the entry to be updated or deleted.

Default value: not defined

EntryFields

Array with the definitions of each input that will be used in the forms to create or update entries.

Default value: array()

ErrorMessageFormat

HTML template used to display validation errors. The placeholder {errormessage} should be used to define where the actual validation error message should appear.

Default value: <div style="text-align: center; font-weight: bold">{errormessage}</div>

EvenRowListingClass

Name of the CSS class to display the even rows of the entries listing table.

Default value:

EvenRowListingColor

Background of the even rows of the entries listing table.

Default value:

ExternalParameters

Associative array with custom parameters and values that applications need to pass to each page to keep context via in the link URLs only, and so not via hidden form inputs.

Default value: array()

FormFooter (changeable)

HTML template used to append to the section with the layout of the forms to create, update and delete entries.

Default value:

FormHeader (changeable)

HTML template used to prepend to the section with the layout of the forms to create, update and delete entries.

Default value:

IDColumn (changeable)

Number of the column in the array passed to the Rows property that contains the value of the identifier of each entry to be listed.

Default value:

InvalidMark

HTML to mark invalid form fields.

Default value: [X]

ListingClass

Name of the CSS class to use for the table that presents the entries listing.

Default value:

ListingMessage (changeable)

HTML of the message that should be displayed while displaying the entries listing.

Default value:

ListingPadding

Padding of cells of the entries listing table.

Default value: 2

ListingSpacing

Spacing for the entries listing table.

Default value: 0

ListingStyle

CSS styles to use for the table that presents the entries listing.

Default value:

NoEntriesMessage (changeable)

HTML of the message that should be displayed when there are no listing entries to display.

Default value:

OddRowListingClass

Name of the CSS class to display the odd rows of the entries listing table.

Default value:

OddRowListingColor

Background of the odd rows of the entries listing table.

Default value:

Page (changeable)

Number of the current page of the entries listing to display starting from 1.

Default value: 1

PageEntries (changeable)

Limit number of entries to display on each page of the entries listing.

Default value: 10

Preview

Boolean option to determine whether the plug-in will present a submit button in the entry create or update form to display a preview of the entry next to the form and continue editing it.

Default value: 0

PreviewLabel

Text for the preview submit button.

Default value: Preview

EntryOutput (changeable)

HTML to display an entry being viewed or the preview of the entry being created or updated.

Default value:

Read

Boolean option to determine whether the plug-in will present the listing of existing entries to be eventually edited or deleted.

Default value: 1

Rows (changeable)

Bidimensional array with data to display in the entries listing.

Default value: array()

Save

Boolean option to determine whether the plug-in will present a submit button in the entry create or update forms to save the entry and continue editing it the entry without exiting the form.

Default value: 0

SaveLabel

Text for the save submit button.

Default value: Save

State

Initial state of the user interface. Currently it supports the following states:

create_canceled

The form to create a new entry was canceled.

create_previewing

A preview of the entry being created is displayed.

created

The form to create a new entry was submitted.

creating

The form to create a new entry is being displayed.

delete_canceled

The form to delete an existing entry was canceled.

deleted

The form to delete an existing entry was submitted.

deleting

The form to delete an existing entry is being displayed.

listing

The listing of entries is being displayed.

update_canceled

The form to update an existing entry was canceled.

update_previewing

A preview of the entry being updated is displayed.

updated

The form to update an existing entry was submitted.

updating

The form to update an existing entry is being displayed.

viewing

A view of a stored entry is displayed.

Default value: listing

SubmitLabel

Text for the main submit button.

Default value: Submit

TotalEntries (changeable)

Total number of the entries that can be displayed.

Default value: 0

Update

Boolean option to determine whether the plug-in will present a form to update existing entries and links in the entries listing to start the update form to edit the respective entries.

Default value: 1

UpdateCanceledMessage (changeable)

HTML of the message that should be displayed when an existing entry update form was canceled.

Default value: Updating an entry was canceled.

UpdateInput

Name of inputs that should have their values updated during AJAX responses. It can be set several times to specify that different inputs should be updated

Default value: none

UpdatedMessage (changeable)

HTML of the message that should be displayed when an existing entry is updated successfully.

Default value: The entry was updated successfully.

UpdateLabel

Text for the update links and submit button.

Default value: Update

UpdateMessage (changeable)

HTML of the message that should be displayed along with the entry update form.

Default value: Update this entry

UpdatePreviewMessage (changeable)

HTML of the message that should be displayed when showing a preview of an existing entry in the update form.

Default value: Updated entry preview

View

Boolean option to determine whether the plug-in will present pages to display individual entries and links in the entries listing to the entries view page.

Default value: 0

ViewLabel

Text for the view links.

Default value: View

ViewingMessage (changeable)

HTML of the message that should be displayed along with the view of an entry.

Default value: Viewing entry

Messages

The scaffolding custom input can capture interactions with the server regardless of whether the form was submitted to the server in the regular way or through an AJAX request.

When the form is submitted, it posts messages to the application during the call to the LoadInputValues function. The messages describe different types of events that should trigger applications actions for storing and retrieving information to show or manipulate the information of the entries that may be displayed or edited by the application.

The posted messages need to be retrieved using the GetNextMessage function, and replied with ReplyMessage function, so the plug-in can generate the appropriate HTML and Javascript to respond to the form submission requests.

The application may need to set some values in the messages before replying them in order to tell the plug-in what to do next. Consequently, the plug-in may post further messages to the application depending on the previous responses. Therefore, applications must process the messages in a loop until there are no more messages need to be handled.

Currently, it post the following types of messages that correspond to all the possible states of the input:

create_canceled

This type of message is posted when the user clicked on the cancel button while the new entry form was being displayed.

Usually, applications do not need to do anything before replying to this type of message.

create_previewing

This type of message is posted when the user clicked on the preview button while the new entry form is being displayed.

Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should generate HTML to display a preview of the of the entry that is being created and set the EntryOutput property.

created

This type of message is posted when the user submitted the form to create a new entry.

Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should create the new entry.

The message Entry entry should be set to identifier of the newly created entry before replying to the message.

creating

This type of message is posted when user is editing a new entry, eventually because he clicked on the new entry creation link.

Usually, applications do not need to do anything before replying to this type of message.

delete_canceled

This type of message is posted when the user clicked on the cancel button while the delete entry form was being displayed.

The message Entry entry is set to the identifier of the entry to be deleted.

Usually, applications do not need to do anything before replying to this type of message.

deleted

This type of message is posted when the user submitted the form to delete an existing entry.

The message Entry entry is set to the identifier of the entry to be deleted.

Applications should call the LoadInputValues and the Validate like with a regular form submission if the delete form had any additional inputs. If the form is valid the application should update the entry records.

deleting

This type of message is posted when user is about to delete an existing entry, eventually because he clicked on the delete link of the respective entry in the entries listing.

The message Entry entry is set to the identifier of the entry to be deleted.

Usually, applications do not need to do anything before replying to this type of message.

listing

This type of message is posted when the entries listing needs to be displayed. The application must set the properties TotalEntries, PageEntries, Rows to let the plug-in determine what it should list.

Applications may also set the IDColumn and Columns properties to define the how the listing should be presented, if those properties were not previously defined when the custom input was added.

The message has the Page entry set to the page of the entries listing should be displayed starting from 1.

If it is requested a page that is outside the range of available listing pages, applications may fix the current page to a value within the allowed range by setting the Page property.

update_canceled

This type of message is posted when the user clicked on the cancel button while the update entry form was being displayed.

The message Entry entry is set to the identifier of the entry being edited.

Usually, applications do not need to do anything before replying to this type of message.

update_previewing

This type of message is posted when the user clicked on the preview button while the update entry form is being displayed.

The message Entry entry is set to the identifier of the entry being edited.

Usually applications should do the same when processing create_previewing messages.

updated

This type of message is posted when the user submitted the form to update an existing entry.

The message Entry entry is set to the identifier of the entry being edited.

Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should update the entry records.

updating

This type of message is posted when user is editing an existing entry, eventually because he clicked on the edit link of the respective entry in the entries listing.

The message Entry entry is set to the identifier of the entry being edited.

Applications need to retrieve the values of the entry properties to assign to the respective form inputs that will allow the user to change those entry properties.

viewing

This type of message is posted when the user clicked on a link to view an entry.

The message Entry entry is set to the identifier of the entry to be displayed.

Usually applications should do the same when processing update_previewing messages, but display the stored entry values instead.

Message parameters

All the types of posted messages contain certain common entries. These common entries should not be changed by the application.

The Event entry is set to the type of message. The From and ReplyTo entries define the identifier of the custom input that posted the message. The AJAX entry is set when the form was submitted via AJAX.

Besides the types of entries that applications should set when replying to each type of message, applications may also set the Cancel entry to 1 when an error occurred, for instance while trying to update or delete an entry that does not exist, or when creating, updating or deleting an entry failed for some reason.

When there is a validation error, applications do not need to set any special message entries. The plug-in automatically detects and marks inputs that were flagged as invalid during validation.

`form_secure_submit_class`

Purpose

This input is used to prevent Cross-Site Request Forgery (CSRF) security attacks.

It emulates a common form submit or image input, but has an hidden input attached to it with a validation key that changes every time the form is presented.

When applications query the forms class to check whether the submit input was submitted, it only responds positively if the secret key is correct and it has not expired. Otherwise, this plug-in class pretends the submit input was not clicked.

This approach aims to frustrate CSRF attack attempts to forge a form submission using validation values scrapped from the form HTML page during a previous access.

Features

It adds a submit or image input and an hidden input to validate the form submission. The validation value stored in the hidden input is generated using a secret key specified by the application. This key is used to encrypt the actual validation value. It is recommended to use different keys to present the same form to different site users

The validation value expires after a given period of time. Applications may retrieve the Expired input property to determine whether the validation failed because someone forged a request with an invalid key or because the validation value expired. Applications may use this information to tell the user to submit the form again when the validation value expired.

The validation value is not accepted when the current request was done using an HTTP method (GET or POST) different than the current form object method. Applications should use preferrably the POST method.

Requirements

The mcrypt library extension

The class requires the PHP is configured to use the mcrypt library extension to be able to encrypt the validation value.

Properties

This custom input plug-in class takes the same properties as the inputs of type submit and image. Additionally, the class also supports the properties below.

If you specify the SRC property, an image input will be added. Otherwise, it will be added an input of type submit.

ExpiryTime

Number of seconds of the time for which the validation value generated by the class remains valid. It must be a value greater than 0.

Default value: 300

Expired (read-only)

Boolean flag that tells whether the validation value has expired after calling the main forms class WasSubmitted function.

Default value: 0

Key (required)

Private key that is used to encrypt the validation value.

Default value: not set

`form_upload_progress_class`

Purpose

This custom input type monitors the progress of submission of a form to the server with file inputs. It can provide several statistics to the user to give an idea of how much of the uploading task was done and how much it remains.

Features

A progress bar may be displayed in a specified position of the form page. The format of the bar can be customized.

Form upload statistics may be displayed along with the progress bar, such as the percentage done, size of data being uploaded, upload speed and remaining time.

The form upload statistics are monitored no more than one time per second to avoid delaying the upload excessively with the progress update information that is sent for display in the browser.

Requirements

PHP version with upload monitor support

The class requires at least PHP 5.2 or an older version patched to provide upload monitor support. Patches are available to provide upload monitor support to older PHP versions.

PHP upload progress extension

The class also requires that the current PHP installation has the upload progress extension available. Currently that extension can be obtained from the PECL repository.

Form AJAX submit plug-in

The class requires the form AJAX submit custom input plug-in to monitor the upload progress during the form submission. This plug-in is available with the regular forms class distribution.

Properties

FeedbackElement

Identifier of the page element within which the progress bar and other upload statistic details will appear.

Default value: none

FeedbackFormat

String with an HTML template that defines how the progress bar and other details may appear. This plug-in replaces special template marks with upload progress statistic values. Then it updates the page element defined by the FeedbackElement with the resulting HTML data. Here follows the supported template marks:

{ACCURATE_PROGRESS}

Percentage of the amount of data uploaded so far. This value is represented as a decimal value.

{AVERAGE_SPEED}

Average speed of the upload considering the amount of data uploaded so far and the time that elapsed since the beginning of the upload. This value may appear with the suffixes K, M or G to represent speeds in KB/s, MB/s or GB/s if the speed is large enough.

{CURRENT_SPEED}

Speed of upload of the last chunk of data that was received. This value may appear with the suffixes K, M or G to represent speeds in KB/s, MB/s or GB/s if the speed is large enough.

{PROGRESS}

Percentage of the amount of data uploaded so far. This value is represented as a rounded integer value.

{REMAINING}

Expected time remaining till the end of the upload. This value may appear with : within the values of remaining seconds, minutes and hours.

{TOTAL}

Total amount of data expected to be sent when the upload finishes. This value may appear with the suffixes K, M or G to represent the amount in KB, MB or GB if the amount is large enough.

{UPLOADED}

Amount of data uploaded so far. This value may appear with the suffixes K, M or G to represent the amount in KB, MB or GB if the amount is large enough.

Default value: {PROGRESS}%

Example value: <table style="width: 200px" border="1"><tr> <td style="width: {ACCURATE_PROGRESS}%; border-style: none; background-color: #0000ff; background-image: url(progress.gif); text-align: center;">{PROGRESS}%</td> <td style="border-style: none;"></td> </tr></table>

For more information contact: info-at-meta-language.net