Author: Manuel Lemos (mlemos-at-acm.org)
Version control: @(#) $Id: forms.documentation,v 1.110 2008/04/30 08:21:38 mlemos Exp $
Contents
"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
Upper 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 upper limit checking is done.
Synopsis
$error=$my_form_object->AddHiddenInputs($inputs)
Purpose
Add a set of hidden input fields to the form definition.
Usage
The $inputs argument is an associative array that enumerates a set of input fields that are meant to be added to the form definition as hidden fields. The index of each entry of the $inputs array indicates the name of the input field. The respective array entry value indicates the initial value of the input field.
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.
Synopsis
$error=$my_form_object->AddHiddenInputs($inputs)
Purpose
Add a set of hidden input fields to the output that is generated for the form with the Output method.
Usage
The $inputs argument is an associative array that enumerates a set of input fields that are meant to be added to the form output. The index of each entry of the $inputs array indicates the name of the input field. The respective array entry value indicates a value that the field will be set to, thus overriding its initial value.
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.
Synopsis
$error=$my_form_object->AddInputHiddenPart($input)
Purpose
Add a field input to the output that is generated for the form with the Output method as if it was a hidden field.
Usage
The $input argument is the identifier of the field 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.
Synopsis
$error=$my_form_object->AddInputPart($input)
Purpose
Add an input field to the output that is generated for the form with the Output method.
Usage
The $input argument is the identifier of the field 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.
Synopsis
$error=$my_form_object->AddInputReadOnlyPart($input)
Purpose
Add a field input to the output that is generated for the form with the Output method in read-only mode. The input is rendered in a way that the user cannot edit it, but its current value is also passed in an hidden input.
Usage
The $input argument is the identifier of the field 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.
Synopsis
$error=$my_form_object->AddLabelPart($arguments)
Purpose
Add a label for an input field to the output that is generated for the form with the Output method.
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.
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.
- 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
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.
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.
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.
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.
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.
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.
Synopsis
$error=$my_form_object->DisplayOutput()
Purpose
Output the HTML generate 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. This return value may be safely ignored if the method call arguments are correctly defined.
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.
Synopsis
$error=$my_form_object->EndLayoutCapture()
Purpose
Stop capturing the current script output to compose the form layout.
Usage
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Synopsis
$javascript_object=$my_form_object->GetJavascriptInputObject($form_object, $input)
Purpose
Generate a Javascript expression that represents a given input field as an object to be used to access its variables and functions 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_object return value is a string that represents the given input field Javascript object.
Synopsis
$javascript_value=$my_form_object->GetJavascriptInputValue($form_object, $input)
Purpose
Generate a Javascript expression that represents the value of a given 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 value in Javascript.
Synopsis
$javascript=$my_form_object->GetJavascriptSetCheckedState($form_object, $input, $checked)
Purpose
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
- 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
(required)
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.
Synopsis
$my_form_object->OutputDebug($message)
Purpose
Output debugging information using the function specified by the debug variable, if set.
Usage
The $message argument is a message string to pass to the debugging function.
Synopsis
$html=$my_form_object->PageHead()
Purpose
Retrieve the HTML code that is necessary to insert in the page head section to make all the form inputs work correctly.
Usage
This function is usually called when the head section of the form page is being generated. It is necessary to call when using certain types of inputs that need special Javascript code, CSS styles, link or meta tags to be defined in the page head section.
The $html return value contains the necessary HTML tags that should be inserted in the page head section.
Synopsis
$javascript=$my_form_object->PageLoad()
Purpose
Retrieve the Javascript code that is necessary to execute when the page is loaded to make all the form inputs work correctly.
Usage
This function is usually called when the ONLOAD attribute of the page BODY is being defined. It is necessary to call when using certain types of inputs that need special Javascript code to load.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY ONLOAD tag.
Synopsis
$javascript=$my_form_object->PageUnload()
Purpose
Retrieve the Javascript code that is necessary to execute when the page is unloaded to make all the form inputs work correctly.
Usage
This function is usually called when the ONUNLOAD attribute of the page BODY is being defined. It is necessary to call when using certain types of inputs that need special Javascript code to load.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY UNONLOAD tag.
Synopsis
$error=$my_form_object->PostMessage($message)
Purpose
Send a message to the form message queue.
Usage
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.
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.
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.
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.
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.
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.
Synopsis
$my_form_object->ResetFormParts()
Purpose
Reset the definition of the form output as it is initially when the form object is created.
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.
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.
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.
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
- MAXLENGTH
- ONBLUR
- ONCHANGE
- ONCLICK
- ONDBLCLICK
- ONFOCUS
- ONKEYDOWN
- ONKEYPRESS
- ONKEYUP
- ONMOUSEDOWN
- ONMOUSEMOVE
- ONMOUSEOUT
- ONMOUSEOVER
- ONMOUSEUP
- ONSELECT
- ROWS
- SIZE
- SRC
- TABINDEX
- Accessible
- ApplicationData
- Capitalization
- ClientScript
- ReadOnlyMark
- ReadOnlyMarkUnchecked
- SubForm
- VALUE
- ValidationServerFunctionErrorMessage
- STYLE
- CLASS
The $value argument defines the value to be assigned to the given field property.
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.
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.
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.
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.
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.
Synopsis
$error=$my_form_object->StartLayoutCapture()
Purpose
Start capturing the current script output to compose the form layout.
Usage
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.
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.
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: ""
- NAME
Name of the form as defined for the NAME attribute of the <FORM> HTML tag. This property must be set to non-empty string if the Output method needs to generate Javascript code for functions that manipulate the fields added to the form output. This is the case when a field requires client side validation or a function is added to execute an action associated to a given input field.
Default value: ""
- ONERROR
Client side script commands to execute when the form is submitted but has validation errors.
The script may use several variables that are initialized with values related with the validation errors. The form variable is a reference to the form object. The error_message variable is a string with all the errors to be displayed. The Invalid variable is an object whose member names are the fields that failed validation rules. The member values are the respective input error messages.
Default value: ""
- ONSUBMIT
Client side script commands to execute when the form is submitted as defined for the ONSUBMIT attribute of the <FORM> HTML tag.
Any commands specified by this property are executed before executing the client side validation code generated by the class Output method.
Default value: ""
- ONSUBMITTING
Client side script commands to execute when the form is submitted as defined for the ONSUBMIT attribute of the <FORM> HTML tag.
Any commands specified by this property are executed after executing the client side validation code generated by the class Output method. If there are any fields with invalid values, the commands specified by this property are not executed.
Default value: ""
- ONRESET
Client side script commands to execute when the form is reseted as defined for the ONRESET attribute of the <FORM> HTML tag.
Any commands specified by this property are executed before executing the client side validation code generated by the class Output method.
Default value: ""
- TARGET
Name of the Web browser frame on which the results of the form submission are meant to be displayed as defined for the ACTION attribute of the <FORM> HTML tag.
If this property is set to an empty string, the results of the form submission are displayed in the same browser frame as the one on which the form is displayed.
Default value: ""
- error
Some functions return an error message when they fail. This message is also stored in the error property so it can be checked later. This avoids the need to check those functions return value immediately after they are called to determine if they succeeded.
The class functions never reset the value of this property. Therefore its value is overwritten by the last function call that fails.
Default value: ""
- Changes
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 | 
