Version control: @(#) $Id: doc_forms.html,v 1.1 2003/09/04 18:19:42 mose Exp $
Forms class
Class for generation and validation of HTML Forms.
Manuel Lemos (mlemos@acm.org)
forms.php
$error=$my_form_object->AddInput($arguments)
Add an input field to the form definition.
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.
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.
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 and hidden.
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.
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.
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.
MIME file types to be accepted by the file fields as defined for the ACCEPT attribute of the <INPUT> HTML tag.
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.
Alternative text argument for image fields as defined for the ALT attribute of the <INPUT> HTML tag.
Width of the border to be drawn around the input fields, usually of the image type.
Flag argument for radio and checkbox fields as defined for the CHECKED attribute of the <INPUT> HTML tag.
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.
Number of columns of a textarea field as defined for the COLS attribute of the <INPUT> HTML tag.
Default data value that is outputted as the definition of the input label. See the function AddLabelPart for more information.
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.
Flag argument for select fields as defined for the MULTIPLE attribute of the <INPUT> HTML tag.
Client side script commands to execute when the field value changes as defined for the ONCHANGE attribute of the <INPUT> HTML tag.
Client side script commands to execute when the user clicks on the field as defined for the ONCLICK attribute of the <INPUT> HTML tag.
Associative array that defines the values and text of a select field as defined for the OPTION HTML tag.
Number of rows of a textarea field as defined for the COLS attribute of the <INPUT> HTML tag.
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.
Number of characters that a text field displays at once as defined for the SIZE attribute of the <INPUT> HTML tag.
URL argument for image fields as defined for the SRC attribute of the <INPUT> HTML tag.
Definition of the presentation style class attributes with which the input field should be rendered.
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.
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. 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.
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.
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.
Name of the Javascript function to be called to encode a password field when a form is submitted.
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.
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.
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.
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.
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.
Default error message to be used when no validation type specific message is defined.
Flag argument that indicates that the field value should be validated as an e-mail address.
Error message to be used when the field value is meant to contain an e-mail address but it is invalid.
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.
Name of the select type field that defines the credit card type to be assumed when the ValidationAsCreditCard argument is set to field.
Error message to be used when the field value is meant to contain a credit card number but it is invalid.
Text argument that indicates that the field value should be validated to match the given regular expression.
Error message to be used when the field value is meant to match a given regular expression but it is does not.
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.
Error message to be used when the field value is meant to not be empty but it is not.
Integer argument that indicates the minimum length of the field value in number of characters.
Error message to be used when the field value length is less than the specified by the ValidateMinimumLength option.
Name of another field that the field value should be equal to. This type of validation is useful for password confirmation fields.
Error message to be used when the field value is meant to be equal to another given field value but it is not.
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.
Error message to be used when the field value is meant to be different from another given field value but it is not.
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.
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.
Flag argument that indicates that the field value should be validated to verify that it contains a valid integer number.
Error message to be used when the field value is meant to be a valid integer number but it is not.
Flag argument that indicates that the field value should be validated to verify that it contains a valid floating point number.
Error message to be used when the field value is meant to be a valid floating point number but it is not.
When this option is specified the validation checks that would be done by the Validate function for this input are not performed.
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.
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.
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.
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.
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.
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.
Error message to be used when the client side validation function returns false.
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.
Error message to be used when the server side validation function returns false.
$error=$my_form_object->AddHiddenInputs($inputs)
Add a set of hidden input fields to the form definition.
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.
$error=$my_form_object->AddDataPart($data)
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.
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.
$error=$my_form_object->AddInputPart($input)
Add an input field to the output that is generated for the form with the Output method.
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.
$error=$my_form_object->AddHiddenInputs($inputs)
Add a set of hidden input fields to the output that is generated for the form with the Output method.
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.
$error=$my_form_object->AddInputHiddenPart($input)
Add a field input to the output that is generated for the form with the Output method as if it was a hidden field.
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.
$error=$my_form_object->AddLabelPart($arguments)
Add a label for an input field to the output that is generated for the form with the Output method.
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.
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.
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.
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.
$error=$my_form_object->AddFunction($arguments)
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.
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.
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.
Name of the function to be added.
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 and enable to let the field receive user input.
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.
$error=$my_form_object->RemoveFunction($name)
Remove a previously added function from the form output to be generated by the Output method.
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.
$error=$my_form_object->Output($arguments)
Generate the output of the form.
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.
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.
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.
$error_message=$my_form_object->Validate($verify,$sub_form)
Determine if the values set in the form input fields are valid.
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.
$submitted_input=$my_form_object->WasSubmitted($input)
Determine if a form was submitted by a given input field.
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.
$error=$my_form_object->LoadInputValues($submitted)
Set the form fields with values passed to the script by the Web server.
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.
$error=$my_form_object->SetInputProperty($input,$property,$value)
Redefine the current value of an input field property.
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:
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.
$error=$my_form_object->SetInputValue($input,$value)
Redefine the current value of an input field.
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.
$value=$my_form_object->GetInputValue($input)
Retrieve the current value that is set to the given field.
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.
$name=$my_form_object->GetFileValues($input,$values)
Retrieve the values that identify a file uploaded when the form is submitted.
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:
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.
$error=$my_form_object->SetCheckedState($input,$checked)
Set the current checked state of a radio or checkbox input.
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.
$checked=$my_form_object->GetCheckedState($input)
Retrieve the current checked state of a radio or checkbox input.
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.
$input=$my_form_object->GetCheckedRadio($name)
Retrieve the form radio input of a given name that is currently checked.
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.
$value=$my_form_object->GetCheckedRadio($name,$default)
Retrieve the value of the form radio input of a given name that is currently checked.
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.
$my_form_object->ResetFormParts()
Reset the definition of the form output as it is initially when the form object is created.
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 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: ""
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.
Default value: ""
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 the value of the PHP global variable $PHP_SELF.
Default value: ""
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: ""
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: ""
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: ""
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 MIME type multipart/form-data should be used.
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 entries 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
String that is used to separate the values of MULTIPLE select fields when the form is outputted in ReadOnly mode.
Default value: \n
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
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
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: ""
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: ""
Options are special properties that only need to be changed in particular circumstances. Their default values are appropriate for normal operation.
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"
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"
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"
Name of the client side global variable that it is used to store the sub-form name correspondent 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"
Regular expression that is used to validate an e-mail address text field.
Default value: "^([a-z0-9_]|\\-|\\.)+@(([a-z0-9_]|\\-)+\\.)+[a-z]{2,4}$"
Name of the global function that is called to determine the number that should be assigned to the TABINDEX attribute the correspondent 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: ""
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: ""
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"
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"
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"
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"
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"
$output=FormCaptureOutput($form,$arguments)
Capture the output of a form object in a result text string.
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 $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.
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 the class does not include a template engine because it is already large as it is. Instead, it is recommended the use one of the many template engines that exist for PHP.
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 once, 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 neglectable.
Since the flexibility that is earned by separating presentation from logic motivates many developers to use Smarty. So, along with this forms class it is provided a plug-in pre-filter function that can be used along with the Smarty engine to compose the forms presentation using templates.
The plugin function is provided in a PHP include file named prefilter.form.php. There is also an example form handling script named test_smarty_form.php that uses Smarty with this plug-in function. This script uses 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 with some special placeholder 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"}.
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.