Author: Manuel Lemos (mlemos-at-acm.org)
Version control: @(#) $Id: forms.documentation,v 1.164 2014/08/11 03:47:06 mlemos Exp $
Forms class
Class for generation and validation of HTML Forms.
Manuel Lemos (mlemos-at-acm.org)
forms.php
$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->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.
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.
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, enable to let the field receive user input, and markValidated to set the style or CSS class of input depending whether it is valid or not.
$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.
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.
Alignment argument for image fields as defined for the ALIGN attribute of the <INPUT> HTML tag.
Arbitrary application defined data.
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.
HTML content to display in input buttons of type submit, reset and button. When this option is defined, the input is rendered with the HTML BUTTON tags instead of INPUT tags.
Boolean flag that indicates whether the Javascript code to avoid form resubmission should not be generated for submit type inputs.
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.
Boolean flag that indicates whether calls to the WasSubmitted function, without specifying an input to check, should ignore this input when checking whether it was submitted.
Name of the CSS class used to render the input when it is invalid.
The specified value replaces the input CSS class attribute when it is listed in the Invalid forms class variable.
The specified CSS class name is also used to replace invalid fields' CSS class, when the form is validated on the client side using Javascript.
CSS style attributes used to render the input when it is invalid.
The specified styles are merged with the input default CSS style attributes when it is listed in the Invalid forms class variable.
The specified CSS attributes are also used to replace there input CSS attributes, when the form is validated on the client side using Javascript.
Default data value that is outputted as the definition of the input label. See the function AddLabelPart for more information.
Name of the presentation style class with which the label associated to this input field should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.
Associative array with a list of extra attributes that should be added to the input label HTML tag when the form output is generated.
Identifier of the label document element associated to this input field as defined for the ID attribute of the <LABEL> HTML tag.
Definition of the presentation style attributes with which the label associated to this input field should be rendered.
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.
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 and checkbox fields. The meaning of this argument is the same for select as defined for the MULTIPLE attribute of the <SELECT> HTML tag. For checkbox fields, the use of this argument indicates that that the field belongs to a group of checkbox fields with the same NAME attribute value that should be validated together.
Name 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.
Boolean flag that indicates whether the input should be considered independent when it is added by custom inputs.
Client side script commands to execute when the field value changes as defined for the event handling definition attribute of the same name of the <INPUT> HTML tag.
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. If the select field is of type MULTIPLE, the SELECTED argument should be an array with the values of the options that should be pre-selected.
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 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.
Type of the field as defined for the TYPE attribute of the <INPUT> HTML tag. Supported input types are: textarea, select, text, file, password, checkbox, radio, submit, reset, button and hidden.
Additionally, there is a special type named custom that should be specified to add custom inputs defined by separate plug-in classes.
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.
Boolean flag that determines whether the field should outputted as an accessible input when it is added to the form output definition with the AddInputPart function.
If this flag is set to 0, the field is outputted as text that represents its current state or value, preserving the presentation style defined by the STYLE and CLASS attributes.
If this flag is set to 1, the field is outputted as an usual accessible input, regardless of the value of the form ReadOnly flag. If the field Accessible property is not specified, the form ReadOnly flag value is considered to determine how the field is outputted.
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 a class that implements the behavior of a custom input implemented as a separate plug-in.
Identifier of another input that determines whether the validation of the current input will be performed depending on the state of the other input.
If the other input check state is true, the current input will be validated. Otherwise, the current input validation will be skipped.
The other input must support checking its state. So it must be of the type checkbox, radio, or custom.
Flag argument that indicates whether invalid values should be discarded when the function LoadInputValues is called.
This is meant to help preventing security exploits performed by attackers that may spoof values passed in fields that usually are not editable by real users, like for instance context values passed in hidden fields.
If this argument is 1, the inputs are validated from within the LoadInputValues function. If the submitted values are invalid, it is ignored and the input default values are restored.
If the argument is 0, validation is only performed when the Validate function is called. In the case of the select type inputs, invalid option values that may have been submitted are not discarded by the LoadInputValues function.
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.
Name of the Javascript function to be called to encode a password field when a form is submitted.
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.
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.
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.
Text to be displayed in a text input until it has any input text.
Mark that should be outputted in the place of the field when the form is displayed as read-only or when the field is set as not accessible. If this argument is not specified, it is displayed the current field value.
The read-only mark is outputted without being encoded, so it can include actual HTML markup to display images or other types of marks instead of the submitted field values.
This is useful for instance to mask password values or display nice alternate images for read-only radio buttons or checkboxes.
Notice that this mark data is not encoded by this class when it is outputted as part of the form output. Therefore, be careful when using data for the mark that is submitted by the user or other untrusted external data source, as it may contain tags that may open the potential security abuse with cross-site scripting exploits.
Mark that should be outputted in the place of a radio or checkbox field when it is not checked and the form is displayed as read-only or when the field is set as not accessible.
Notice that this mark data is not encoded by this class when it is outputted as part of the form output. Therefore, be careful when using data for the mark that is submitted by the user or other untrusted external data source, as it may contain tags that may open the potential security abuse with cross-site scripting exploits.
List of transformations that may be applied to a text input value when it is changed by the user. The transformations are defined in the form of regular expressions patterns that define the form of the text that should be searched and the corresponding replacement expressions.
The transformations may occur on the server side when the class function LoadInputValues is called. The transformations may also occur on the client side if the user browser has enabled Javascript with regular expression based text replacement support. The generated form Javascript code automatically detects whether client side transformations can be applied.
The transformations list should be defined as an associative array with the search regular expressions as array entry indexes and the replacement text as array entry values.
It is beyond the scope of this document to give a full explanation of how regular expressions work and their syntax. You may want to study the PHP function ereg_replace to learn the syntax of search and replacement regular expressions.
In general terms you should know that the parts of the text input value that match the search regular expression are substituted by the replacement expression.
The replacement expression may contain place holders that will be substituted by matching parts of the original value. Place holders are specified by a backslash character \ followed by the number of the part of the original value. A matching part is denoted in the search regular expression by enclosing its definition within brackets ( ) .
Given this, \1 in the replacement expression represents the first search match text, \2 the second, \3 the third and so on up to \9.
Here follows the definition of a few examples of useful replacement expressions:
"ReplacePatterns"=>array(
/*
* trim whitespace at the beginning of the text value
*/
"^\\s+"=>"",
/*
* trim whitespace at the end of the text value
*/
"\\s+\$"=>"",
/*
* Prepend the text http:// in values that start with www.
*/
"^([wW]{3}.)"=>"http://\\1"
)
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.
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.
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.
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.
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.
Error message to be used when the field value is meant to contain a credit card number but it is invalid.
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.
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.
Error message to be used when the field value is meant to be different from a given text value but it is not.
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.
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.
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.
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 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.
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.
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.
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.
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.
Default error message to be used when no validation type specific message is defined.
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.
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.
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.
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.
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 the select type field that defines the credit card type to be assumed when the ValidationAsCreditCard argument is set to field.
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.
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.
Function to be called to validate the field value on the server side. It may be a string with the name of a global function, or a form of defining a callable function of an object, static class function or an anonymous function. 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.
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.
$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->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->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->AddInputReadOnlyPart($input)
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.
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.
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.
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.
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.
Associative array with a list of extra attributes that should be added to the label HTML tag when the form output is generated.
Identifier of the label document element as defined for the ID attribute of the <LABEL> HTML tag.
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.
Definition of the presentation style attributes with which the label should be rendered.
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.
$error=$my_form_object->Connect($from, $to, $event, $action, $context)
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.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $to argument is the identifier of the connection target input that will execute an action after the trigger event occurs in the origin input.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser). All event types that may be triggered by the base input types are supported. Custom input types may support other types of events.
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input. Currently, several actions are supported by all base input types, except for the hidden type.
The Click action emulates the same effect of an user clicking in the target input. The Focus action gives the focus to the target input. The Select action selects all the text of a text target input. The Enable action enables the target input. The Disable action disables the target input. The MarkValidated action sets the style or CSS class of input depending whether it is valid or not.
Custom input types may support other types of actions.
The $context argument is an associative array that may pass additional context information to configure details of the action that will be executed. Most actions do not require any additional context information. In that case the $context argument may be an empty array.
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->ConnectFormToInput($input, $event, $action, $context)
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.
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.
$error=$my_form_object->DisplayOutput()
Output the HTML generate for the form.
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.
$encoded=$my_form_object->EncodeJavascriptString($string)
Encode a string value for use as a string expression in Javascript code.
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.
$error=$my_form_object->EndLayoutCapture()
Stop capturing the current script output to compose the form layout.
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.
$output=$my_form_object->FetchOutput()
Fetch the generated form output into a string.
The $output return value contains a string that contains the generated form output. If there was an error, an empty string is returned.
$sub_form=$my_form_object->FlagInvalidInput($input, $error)
Flag a given input as invalid.
The $input argument specifies the identifier of the input to be flagged as invalid.
The $error argument specifies the validation error message to associate to the invalid input.
The $sub_form return value is a string of the sub-form that the flagged input belongs.
$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->GetCheckable($input, $checkable)
Return the information of whether a given input can be treated like a checkbox or radio so its state can be checked or unchecked.
The $input argument defines the identifier of the input to be queried.
The return $error value is a string value that indicates whether there was an error, eventually because it is a custom input that does not implement the GetCheckable function.
$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->GetCheckedRadioValue($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.
$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.
$error=$my_form_object->GetContainedInputs($input, $kind, $contained)
Retrieve the list of inputs contained within a given input of the form.
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.
$error=$my_form_object->GetInputProperty($input, $property, $value)
Retrieve the current value of an input field property.
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:
Arbitrary application defined data.
HTML text value of the input label, if set.
Value the option of a select input that is currently selected.
Type of the given input.
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.
$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.
$error=$my_form_object->GetInputEventURL($input, $event, $parameters, $url)
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.
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.
$inputs=$my_form_object->GetInputs($parent)
Retrieve the list of inputs of the form.
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.
$javascript_value=$my_form_object->GetJavascriptCheckedRadioValue($form_object, $name, $default)
Generate a Javascript expression that represents the value of the currently checked radio input field with a given name to be used to on client side scripts in Javascript.
The $form_object argument is a string that represents the Javascript object of the form to which the radio input belongs.
The $name argument defines the name of the radio inputs that should be looked up to see which one is checked.
The $default argument defines the value that should be returned if there is no radio field with the given name that is checked. If this argument is not specified, the default value is an empty string.
The $javascript_value return value is a string that represents the value of the checked radio input field in Javascript.
$javascript_value=$my_form_object->GetJavascriptCheckedState($form_object, $input)
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.
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.
$error=$my_form_object->GetJavascriptConnectionAction($form_object, $from, $to, $event, $action, $context, $javascript)
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.
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.
$javascript_object=$my_form_object->GetJavascriptInputObject($form_object, $input)
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.
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.
$javascript_value=$my_form_object->GetJavascriptInputValue($form_object, $input)
Generate a Javascript expression that represents the value of a given input field to be used to on client side scripts in Javascript.
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.
$javascript=$my_form_object->GetJavascriptSelectedOption($form_object, $input)
Generate a Javascript expression that evaluates to the current selected option of a select or custom input field.
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 return value is a string with Javascript expression of the input selected option.
$javascript=$my_form_object->GetJavascriptSetCheckedState($form_object, $input, $checked)
Generate a Javascript expression to set the checked state of a given checkbox, radio, or custom input field.
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.
$javascript=$my_form_object->GetJavascriptSetFormProperty($form_object, $property, $value)
Generate a Javascript expression to assign the value of a form property.
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.
$javascript=$my_form_object->GetJavascriptSetInputProperty($form_object, $input, $property, $value)
Generate a Javascript expression to assign the value of a property of a given input field.
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.
$javascript=$my_form_object->GetJavascriptSetInputValue($form_object, $input, $value)
Generate a Javascript expression to assign the value of a given input field.
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.
$has_messages=$my_form_object->GetNextMessage($message)
Retrieve the next event message pending on the message queue.
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.
$value=$my_form_object->GetSubmittedValue($input)
Retrieve the value of a given input that is being submitted.
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.
$error=$my_form_object->HandleEvent($processed)
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.
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.
$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 unless the form is using custom input that may trigger error conditions.
$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.
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.
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.
$my_form_object->OutputDebug($message)
Output debugging information using the function specified by the debug variable, if set.
The $message argument is a message string to pass to the debugging function.
$html=$my_form_object->PageHead()
Retrieve the HTML code that is necessary to insert in the page head section to make all the form inputs work correctly.
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.
$javascript=$my_form_object->PageLoad()
Retrieve the Javascript code that is necessary to execute when the page is loaded to make all the form inputs work correctly.
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.
$javascript=$my_form_object->PageUnload()
Retrieve the Javascript code that is necessary to execute when the page is unloaded to make all the form inputs work correctly.
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.
$error=$my_form_object->PostMessage($message)
Send a message to the form message queue.
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.
$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->ReplyMessage($message, $processed)
Send a reply to the message retrieved from the form message queue.
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.
$my_form_object->ResetFormParts()
Reset the definition of the form output as it is initially when the form object is created.
$radio=$my_form_object->SetCheckedRadio($name, $value)
Set the current checked state of all radio inputs of a given name.
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.
$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.
$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.
$error=$my_form_object->SetSelectOptions($input, $options, $selected)
Set the list of options and selected values of a select type input.
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.
$error=$my_form_object->StartLayoutCapture()
Start capturing the current script output to compose the form layout.
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_message=$my_form_object->Validate($verify,$sub_form)
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:
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.
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.
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: ""
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: ""
Identifier of the form document element as defined for the ID attribute of the <FORM> HTML tag.
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.
If the form being submitted has file inputs, the POST method is used automatically.
Default value: ""
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: ""
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: ""
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: ""
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: ""
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: ""
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: ""
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
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
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()
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
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: ""
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: ""
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: ""
Options are special properties that only need to be changed in particular circumstances. Their default values are appropriate for normal operation.
Text to prepend to the error messages that are displayed or returned when invalid inputs are found.
Default value: ""
Text to append to the error messages that are displayed or returned when invalid inputs are found.
Default value: ""
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
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
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 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 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"
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"
Boolean option to tell the class to not generate JavaScript code to validate the package on the browser side.
Default value: 0
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: ""
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: ""
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})?\$"
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"
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}\$"
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"
Sequence of characters that will be used to break the lines of the generated Javascript code.
Default value: \n
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]+)?\$"
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"
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 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"
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"
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 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"
$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 $output return value contains the form HTML output if the function call succeed. Otherwise it contains an empty string.
To compose the layout of a form, the class needs to be called alternating HTML data definitions using AddInputPart calls and input field or label placements. However, this does not help the work of Web developers and designers because HTML code produced by the Web designer needs to be mixed with the programming of the developers, making the work of both harder to conceal and maintain.
To help solving this problem, a template engine could be used to separate the presentation work files from the programming logic work files. Currently there are two supported solutions to use templates to compose the output of forms: using plain HTML template files with embedded PHP commands to place the form inputs and labels, or using the Smarty template engine with a special plug-in to capture the template processing.
PHP itself is already a template language. Since this form class needs to know in advance all the HTML data that will make part of the output and where the form inputs are located, the form layout HTML data needs to be added with the AddDataPart function before generating the whole form output.
An alternative way of defining the layout HTML data for the form output composition is to use PHP script output capturing support available since version 4.
This class is capable of capturing the current PHP script output by calling the function StartLayoutCapture. After calling this function and until the EndLayoutCapture function is called, all the script output is captured to compose the form output.
Plain HTML template files can be used to define the form layout by using the PHP include command. Just place PHP code sections in the points of the HTML template where the inputs and their labels will appear, using the class functions like AddInputPart and AddLabelPart. Here follows an example:
File: my_form_script.php
<?php
$form=new form_class;
$form->AddInput(array(
"NAME"=>"user_name",
"TYPE"=>"text",
"ValidateAsNotEmpty"=>1,
"ValidationErrorMessage"=>"You have not specified the user name"
));
$form->AddInput(array(
"NAME"=>"password",
"TYPE"=>"text",
"ValidateAsNotEmpty"=>1,
"ValidationErrorMessage"=>"You have not specified the password"
));
$form->AddInput(array(
"ID"=>"submit",
"TYPE"=>"submit"
));
$form->StartLayoutCapture();
include("my_form_template.html.php");
$form->EndLayoutCapture();
$form->DisplayOutput();
?>
File: my_form_template.html.php
<table>
<tr>
<th><?php
$form->AddLabelPart(array(
"FOR"=>"user_name",
"LABEL"=>"<u>U</u>ser name",
"ACCESSKEY"=>"U"
));
?>:</th>
<td><?php $form->AddInputPart("user_name"); ?></td>
</tr>
<tr>
<th><?php
$form->AddLabelPart(array(
"FOR"=>"password",
"LABEL"=>"<u>P</u>assword",
"ACCESSKEY"=>"P"
));
?>:</th>
<td><?php $form->AddInputPart("password"); ?></td>
</tr>
<tr>
<td colspan="2"><?php $form->AddInputPart("submit"); ?></td>
</tr>
</table>
One of the most popular template engines for PHP is Smarty. It generates PHP scripts that merge the HTML data from templates with the commands of code that execute actions and produce dynamically generated data. Once these scripts are generated, they do not need to be updated as long as the template files are not changed.
Given that even with the generation of processed templates in the form of PHP scripts that are cache, this solution is usually faster than most alternative template engines. However, keep in mind in the end you still need to load a large class that is the Smarty execution engine besides the compiled template script. So, the consumption of CPU and memory resources often is not negligible.
Since the flexibility that is earned by separating presentation from logic motivates many developers to use Smarty, along with this forms class it is provided a plug-in pre-filter function that can be used with the Smarty engine to compose the forms presentation using templates.
The plug-in function is provided in a PHP include file named prefilter.form.php. Currently there are two versions of the plug-in, one for Smarty 2 and another for Smarty 3.
There is also an example form handling script named test_smarty_form.php that uses Smarty 2 with this plug-in function. The version for Smarty 3 is named test_smarty3_form.php. These scripts use a template file named form.tpl that contains the layout of the form defined in HTML.
Besides the HTML markup and the Smarty commands, the form template files may have special place holder marks that define where the form fields will be placed. Currently only three types of marks are supported: {input name="input"}, {hiddeninput name="input"} and {label for="input"}. If you changed Smarty mark left and right delimiters to other characters besides { and }, the form input and label marks must use those other delimiter characters.
The {input} mark specifies an input to be added to the form as it would be added with the AddInputPart. The {hiddeninput} mark specifies an input to be added to the form as a hidden input as it would be added with the AddInputHiddenPart. The {label} mark specifies where a label of a specified input to be added to the form as it would be added with the AddLabelPart.
The current version of this plug-in makes Smarty generate processed template scripts that refer to the object of the forms class referring to a global variable named $form. Make sure your forms class object is assigned to this global variable.
The forms class provides support for using custom form input types that can implement enhanced functionality over the basic HTML form input types.
The custom input types can provide support for sophisticated form handling features, like for instance, managing complex inputs made of several tightly coupled inputs, or providing enhanced usability by the means of special Javascript event handlers that can make the forms more interactive, thus avoiding long delays that make the user wait for needless Web server access round trips to perform special types of manipulation of the input values.
New custom form input types can be implemented by the means of separate plug-in classes, that can provide new form input functionality without requiring the developers to change the code of the main forms class.
Any developer can create new custom form input plug-in classes. Such classes may be distributed with their own license. Since the license of the main forms class is BSD like, it allows unrestricted distribution including of dependent components. So, the license of a plug-in class may be proprietary and it may even be distributed in a closed source format as a commercial product.
A form input of a custom type is used very much like the regular types of input. It should be defined also using the forms class function AddInput. The main difference is that you need to specify the name of the class of the custom input using the CustomClass parameter of the AddInput function.
All custom input classes have a common API that is used by the main forms class to provide the custom behavior. New custom input classes should extend the form_custom_class. This class is defined in the forms.php file right before the main forms class.
The form_custom_class base class provides default behavior for all custom input classes by the means of several functions and variables. Some of those functions and variables have necessarily to be reimplemented in the custom input classes. The other functions and variables may be redefined only when necessary.
If you are interested in developing a new custom input class, here follows a list of common steps that you should take:
A new custom custom input class should be created by extending the form_custom_class base class. This base class provides default behavior that reduces significantly the effort that is necessary to implement a new custom input.
The most important function of a custom input class is the AddInput function. It should check the parameter arguments passed to the function and initialize the class variables according to the needs.
If the new custom input is intended to manage a set of one or more new inputs, the AddInput function is the place where such inputs should be defined by using the main forms class AddInput function. Use the GenerateInputID function to create unique identifiers for those new inputs.
If the class is supposed to benefit from the automatic support for rendering from format templates, it should initialize the format and valid_marks class variables using the ParseNewInputFormat function.
This will let the class benefit from inheriting several functions from the base class without having to reimplement them like AddInputPart, AddHiddenInputPart, AddLabelPart and AddFunction.
Some inputs may need to load Javascript code, CSS styles or page meta tags that need to be inserted in the page head section, thus outside the form tags. If the new custom input needs this, it must implement the PageHead function.
If the custom input needs to define head tags only once, even when the form has multiple custom inputs of the same class, the ClassPageHead function should be implemented to define such tags.
Additionally, if it needs to execute Javascript code during the page load or unload events, it must implement the PageLoad or PageUnload functions respectively.
If the new custom input will have an associated input value that can be set or changed by the user, implement the GetInputValue function to provide a means for the applications that use the new form custom input to retrieve its current value.
Also, if the new custom input will emulate the behavior of a checkbox or radio, implement the GetCheckedState function to provide a means for the applications that use the new form custom input to retrieve its checked state.
If there are any properties that can be changed by the applications after the custom input is added to the form, implement the SetInputProperty function to handle property change requests, including for the main input VALUE property if supported.
Also, if the new custom input will emulate the behavior of a checkbox or radio, implement the SetCheckedState function to provide a means for the applications that use the new form custom input to change its checked state.
If the custom input value has to be validated according to specific rules, implement the ValidateInput function to enforce such rules. Make sure it is possible to configure details of such validation rules with either the AddInput or SetInputProperty functions, including the text to present to the user every time a rule is not satisfied. If the custom input does not need to perform server side validation, set the server_validate variable needs to be set to 1. In this case, the ValidateInput function does not need to be redefined.
If possible implement the GetJavascriptValidations function to specify the Javascript code and other details that will be used to enforce some or all of the types of validation rules on the client side. This helps improving the usability of the forms that use the new custom input. If the custom input needs to perform client side validation, make sure you set the client_validate variable to 1.
If the custom input is expected to be managed by another custom input, implement GetJavascriptInputValue function to make possible for the manager input to retrieve the custom input value on the client side with Javascript and perform any special type of validation or manipulation.
If the custom input class needs to perform some special action like updating its internal state values when the form values are loaded, implement the LoadInputValues function to define how to execute such special action.
In certain circumstances it may be useful to connect two or more inputs in such way that when a client side (user browser) event occurs in the context of a given input, it triggers the execution of actions in the context of other inputs.
For instance, when updating the quantity of a product in an order form, it would be useful to immediately update another field that shows the total value of the order.
This can be achieved using the Connect function. It associates a client side event in the origin input to an action that is executed in the context of a target input.
The base input types support a limited number of events and actions. New custom input classes can be developed to support more events and actions. Such custom input classes need to implement the Connect to handle new events and GetJavascriptConnectionAction to generate the necessary Javascript code that implements new actions.
The base custom input class provides means to automatically register custom input events.
An application just calls the Connect function to trigger the execution of an action on the context of a given input when the event occurs.
The base class implementation of that function registers the details of the event connection. The connections class variable is updated to keep event connection information. The Connect function only accepts registrations of connections for events with an entry already initialized in the connections variable.
When a custom input class needs to generate the Javascript code to execute the registered actions that handle the custom event, it just needs to call the base class GetEventActions function.
That function returns the Javascript code for the actions associated to the registered event connections. The actions Javascript code also includes the value for the respective event default action set in the events class variable.
In certain circumstances a custom input may need to execute actions on the server side to handle special user interaction events.
This is the case, for instance, of highly interactive inputs that may communicate with the server using special purpose Javascript to pass request parameters to the server side in order to execute actions or retrieve information necessary to update their client side state or details of its presentation in the user browser.
In other circumstances a custom input may need to serve dynamically generated information to the browser that cannot be served when the form HTML is generated, like for instance, to present images with graphics generated dynamically.
In either case, these interactions with custom input on the client side and the respective custom input class, can be implemented with the HandleEvent function.
The HandleEvent class function examines the request parameters to determine which custom input is responsible for processing the request. Then it calls the HandleEvent function of the respective custom input class passing the name of the event and any additional parameters that may have been passed to the request.
A custom input class that expects to process event handling requests should execute the necessary actions and eventually server HTTP response headers and body that the browser will use to complete the interaction.
A custom input may forward the request to handle an event received by the HandleEvent function. This may be useful to delegate the response of a client side event to a child input.
The class of the custom input receiving a event handling request just needs to call the PostMessage function of the main forms class, setting the message Target parameter to the identifier of the input to which the event should be forwarded. An input receiving a forwarded message must implement the PostMessage function.
A custom input may emulate form submit inputs to provide additional behaviour. In that case, an input emulating form submit inputs may implement the WasSubmitted function.
The following sections provide detailed information on all the custom input public class functions and variables that are inherited from the custom input base class and can be reimplemented in new custom input classes.
Array that stores the names of all the children inputs that have has parent the current custom input.
This variable is updated by the AddChild function and should not be redefined by the custom input class.
Default value: array()
Boolean flag that tells whether the custom input generates Javascript code to perform eventual client side validation that may be necessary.
This variable should be redefined or initialized when the AddInput function is called, if the custom input performs client side validation to be executed after any validations of base inputs that it may have as children.
Default value: 0
Associative array that stores the actions registered to handle events supported by the custom input class.
The indexes of the associative array should be the names of the events. The values of the array should be arrays on which the information of the registered event actions will be stored by the DefaultConnect implementation of the base custom input class.
This variable should be redefined by the custom input classes that support their own event handling. It should contain array entries with the names of all supported events. The entry values should be empty arrays.
Default value: array()
Example value: array(
"ONCOMPLETE"=>array(),
"ONTIMEOUT"=>array()
)
Associative array that stores the Javascript code to be executed when the supported custom events are called.
The indexes of the associative array should be the names of the events. The values are strings with the Javascript code set for each of the events.
This variable should be initialized with default Javascript code for each of the supported custom events. The array entries for events that do not have a default handling code do not need to be initialized.
Default value: array()
Example value: array(
"ONTIMEOUT"=>"alert('The communication with the server has timed out.');"
)
Format of an HTML template that defines how the custom input will be rendered. This format template is used by the AddInputPart function of the custom input base class to implement the default rendering method.
The syntax of the template consists of arbitrary HTML with special marks that define the position of place holder marks. These marks can appear in any position the format template value.
The special marks start and end with characters defined by the mark_start and mark_end respectively. The text value between the start and end marks defines the mark name.
The meaning of the mark name is defined by the valid_marks variable. Usually it specifies that the mark corresponds to one of several input fields that are managed by the custom input.
This variable should be redefined by the custom input class if it is intended to use the default rendering method provided by the custom input base class.
Default value: ""
Example value: "{day}/{month}/{year}"
Identifier of the default input that is meant to get the input focus. That input may get the focus when:
If this variable is set to an empty string, no input will get the focus.
This variable should be redefined by the custom input class if it is intended to use the automatic focus input association by the custom input base class.
Default value: ""
Example value: "date_day"
Identifier name of the current custom input. This is set by the main forms class when the custom input object is created.
It is assigned to the ID or NAME value specified by the current script as parameter of the AddInput function of the main forms class to add the custom input to the form definition.
It is meant to be used by any functions of the custom input class that need to know what is the name by which the main forms class registers the current custom input.
Default value: set by the main forms class
Text that identifies the beginning of a place holder mark in format templates.
Usually this variable does not need to be redefined by the custom input class.
Default value: "{"
Text that identifies the end of a place holder mark in format templates.
Usually this variable does not need to be redefined by the custom input class.
Default value: "}"
Boolean flag that tells whether the custom input performs server side validation that occurs after any validations of base inputs that it may have as children.
This variable should be redefined or initialized when the AddInput function is called, if the custom input does not perform any server side validation.
Default value: 1
Associative array that specifies the meaning of names used in place holder marks used in the format template specified by the format variable.
This array has as entry indexes the types of elements to which each place holder is mapped when it is rendered by the custom input base class implementation of the AddInputPart function. Currently it supports the elements of type input, label and data.
The array values should be also associative arrays that map place holder mark names to the names of the elements that they will represent when the custom input is rendered.
This variable should be redefined by the custom input class if it is intended to use the default rendering method provided by the custom input base class.
Default value: array()
Example value:
array(
"input"=>array(
"year"=>"date_year",
"month"=>"date_month",
"day"=>"date_day"
),
"label"=>array(
"year"=>"date_year"
),
"data"=>array(
"clock"=>'<img src="clock.gif" width="16" height="16" alt="Clock">'
)
)
$error=$input_object->AddChild($form, $name)
Add the information of the name of a successfully added child input of a custom input.
This function is called when the AddInput function of the main forms class is called by the custom input class to add a child input.
This function should not need to be reimplemented in the actual custom input classes. The default implementation of the custom input base class stores the name of the child input in the children array class variable, so it may be used whenever the class needs to iterate over the children inputs.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $name argument is the identifier name of the just added child input.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->AddFunction($form, $arguments)
Add the definition of a Javascript function that is meant to be generated as part of the output of the form. The function to be generated is meant to execute actions related with the elements of the form.
This function is called when the AddFunction function of the main forms class is called to add a function on a custom input element.
Usually this function does not need to be reimplemented in the actual custom input classes. The default implementation of the custom input base class calls the main forms class AddFunction on the input specified by the focus_input variable of the custom input object.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $arguments argument is the array passed to the main forms class AddFunction function.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->AddInput($form, $arguments)
Initialize the custom input object with parameters that are meant to configure details of its behavior.
Usually it is used the create any basic inputs to be managed by the object of the custom input class, processing the format template and any other parameters specified by the input definition arguments.
This function is called when the AddInput function of the main forms class is called to add a custom input to the form.
This function needs to be reimplemented in the actual custom input classes.
The $form argument is a reference to the forms class object on which this custom input is being used. Make sure you declare the $form argument to be passed by reference.
The $arguments argument is the array passed to the main forms class AddInput function.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->AddInputHiddenPart($form)
Add the input to the output that is generated for the form as if it was a hidden field.
Usually this function does not need to be reimplemented in the actual custom input classes if a format template and the list of valid marks is specified in the format and valid_marks custom input object variables.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->AddInputPart($form)
Add the input to the output that is generated for the form.
Usually this function does not need to be reimplemented in the actual custom input classes if a format template and the list of valid marks is specified in the format and valid_marks custom input object variables.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->AddLabelPart(&$form, $arguments)
Add the label of the custom input to the output that is generated for the form with the main forms class Output method.
Usually this function does not need to be reimplemented in the actual custom input classes.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $arguments argument is an associative array that takes pairs of tag names and values that define the properties of the label to be added to the form output, like it is defined for the AddLabelPart function of the main forms class.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$html=$input_object->ClassPageHead($form)
Retrieve the HTML code that is necessary to insert in the page head section to make all custom inputs of the same class work correctly.
This function is called once from the main forms class PageHead function for each class of the custom inputs.
This function needs to be reimplemented in the custom input classes that need special Javascript code, CSS styles, link or meta tags to be defined in the page head section.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $html return value contains the necessary HTML tags that should be inserted in the page head section.
$error=$input_object->Connect($form, $to, $event, $action, $context)
Handle the request to connect another form input to the custom form input in such way that when a given event occurs in the other input on the client side (user browser), it is triggered an action that is executed in the context of the custom input.
This function is called when the Connect function of the main forms class is called and the custom input is the connection target input.
This function needs to be reimplemented in the actual custom input classes that support executing actions in result of handling input events that occur in other inputs connected to the custom input.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->DefaultConnect($form, $to, $event, $action, $context)
Provide a default implementation for the Connect function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the Connect function to register actions to be associated to events supported by the custom input.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->DefaultJavascriptGetConnectionAction($form, $form_object, $from, $event, $action, $context, $action)
Provide a default implementation for the GetJavascriptConnectionAction function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the GetJavascriptConnectionAction function to generate Javascript code for actions that are not directly generated by the custom input class. Currently, it just fails returning an error but that behavior may change in the future.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $action argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->DefaultHandleEvent($form, $event, $parameters, $processed)
Provide a default implementation for the HandleEvent function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the HandleEvent function to handle events that are not directly handled by the custom input class. Currently, it just fails returning an error but that behavior may change in the future.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $event argument is the name of the event that has occurred.
The $parameters argument is an associative array with all the parameters that were passed in the event handling request.
The $processed argument is used to pass a boolean variable by reference that is set by this function to indicate whether the event was processed by the function.
The $error return value contains an error message if there was an error while trying to process the specified event. Otherwise it contains an empty string.
$error=$input_object->DefaultPostMessage($form, $message, $processed)
Provide a default implementation for the PostMessage function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the PostMessage function to handle messages that are not directly handled by the custom input class. Currently, it just sends a reply to the posted message.
This function is usually called to handle forwarded messages to delegate the handling of client side events. It only needs to be implemented by custom classes that expect handling forwarded messages.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $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. See the documentation of the PostMessage function of the main forms class for the list of common message entries.
The $processed argument is used to return a boolean value by reference that is set by this function to indicate whether it finished handling the posted message or it generated more messages that need to be handled by other inputs.
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=$input_object->DefaultSetInputProperty($form, $property, $value)
Provide a default implementation for the SetInputProperty function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the SetInputProperty function to support properties that are not directly implemented by the custom input class. Currently, it only implements the following properties:
The $form argument is a reference to the forms class object on which this custom input is being used.
The $property argument is the name of the property to be changed.
The $value argument is the new value of the property.
The $error return value contains an error message if the specified property is not supported, or cannot be changed after the input has been created, or for some other reason the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
$id=$input_object->GenerateInputID($form, $input, $kind)
Helper function to generate input identifier names. It is meant to create names for basic inputs that make part of composite complex custom inputs.
For instance, a custom date input may be made of three basic inputs for the year, month and day. This function can be used to generate their names based on the identifier name of the custom input.
Usually this function does not need to be reimplemented in the actual custom input classes.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $input argument is the base name of the input identifier to be generated. Usually it is the identifier name of the current custom input.
The $kind argument is a unique name of the kind input to which the resulting identifier will be assigned.
The $id return value is the generated input identifier.
$error=$input_object->GetContainedInputs($form, $kind, $contained)
Retrieve the list of inputs contained within the custom input.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $kind argument is a string that specifies the kind of contained input to be retrieved. Currently this argument is ignored. Set to an empty string for future compatibility.
The $contained argument is a reference to a variable that will be assigned by this function to an array of identifier strings of the contained inputs.
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.
$actions=$input_object->GetEventActions($form, $form_object, $event)
Generate the necessary Javascript code that will be used to implement the actions registered with the Connect function.
This function is meant to be called by custom input classes that need to generate Javascript that will be associated to a given event.
This function is implemented by the base custom input class and should not be reimplemented by any other custom input class.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $event argument is the name of event for which it is being generated the handling Javascript code.
The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.
The $actions return value is the generated event handling Javascript code.
$value=$input_object->GetInputValue($form)
Retrieve the current value of the custom input, eventually combining the current values of any of the inputs that compose the custom input.
This function is called when the main forms class GetInputValue is called specifying the current custom input identifier as argument.
This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $value return value is the current input value. It usually is a string but special types of inputs may return input values of other types. The custom input base class always returns an empty string.
$javascript_value=$input_object->GetJavascriptCheckedState($form, $form_object)
Generate a Javascript expression that represents the checked state of a the custom input field to be used to on client side scripts in Javascript.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $javascript_value return value is a string that represents the given input field checked state in Javascript.
$error=$input_object->GetJavascriptConnectionAction($form, $form_object, $from, $event, $action, $context, $javascript)
Generate the necessary Javascript code that will be used to implement the action that is executed when the trigger event occurs in a connected input.
This function is called when the main forms class generates the form output for the connection origin input, so it can assign the generated action Javascript code to the trigger event attribute definition.
This function needs to be reimplemented in the actual custom input classes that support executing actions in result of handling input events that occur in other inputs connected to the custom input.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $javascript argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$javascript_value=$input_object->GetJavascriptInputValue($form, $form_object)
Generate a Javascript expression that represents the value of the custom input field expression that be used to on client side scripts in Javascript to retrieve the input value.
This function is called when the main forms class GetJavascriptInputValue is called specifying the current custom input identifier as argument.
This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.
The $javascript_value return value is a string that represents the custom input field value in Javascript.
$javascript=$my_form_object->GetJavascriptSetCheckedState($form, $form_object, $checked)
Generate a Javascript expression to set the checked state of the custom input field.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.
The $checked argument is a string that specifies the Javascript expression to set the given input checked state.
The $javascript return value is a string with Javascript statements to set the custom input checked state.
$javascript=$input_object->GetJavascriptSetInputProperty($form, $form_object, $property, $value)
Generate Javascript commands to assign the value of a property of the custom input field.
This function is called when the main forms class GetJavascriptSetInputProperty function is called specifying the current custom input identifier as argument.
This function needs to be reimplemented in the actual custom input classes if it supports changing any input properties from Javascript.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.
The $property argument is a string that specifies the name of the input property to be assigned. It should be VALUE for assigning the main input value.
The $value argument is a string that specifies the Javascript expression to assign to the given input property.
The $javascript return value is a string with Javascript statements to assign the given input property.
$error=$input_object->GetJavascriptValidations($form, $form_object, $validations)
Retrieve a list of validation tests that are meant to be performed on the client side using Javascript.
This function is called by the main forms class to generate the part of the form output that has the Javascript code that is going to be used to perform the client side validation tests.
The custom input tests are performed after all other input values are validated on the client side. So it is safe to assume that when the custom input tests are executed, all other input fields that are validated on the client side contain valid values.
This function needs to be reimplemented in the actual custom input classes if there are special types of validation tests that can be performed on the client side, besides other tests that are eventually performed on individual inputs that make part of a composite custom input.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.
The $validations argument is a reference to an array that will be initialized with entries that define details of each client side validation test.
Each entry of the $validations array is set to an associative array that specifies parameters of an individual test. Here follows the list of currently supported parameters:
Array that defines a list of arbitrary Javascript commands to be executed right before evaluating the actual validation test condition. These commands can be used to compute the expressions that will be used in the test condition.
Each entry in the array defines a line that will be added to the Javascript function generated by the class to validate the form on the client side. Entries with emptry strings are suppressed.
String that specifies a Javascript boolean expression that is evaluated to determine whether the input is valid. If the expression value is true, the field is invalid and no other validation tests are performed.
If the condition string is empty, no validation condition is evaluated.
String that specifies the error message that is displayed to let the user know why the input value is not valid. This error message must not be missing or empty, unless the condition string is empty.
String the specifies the identifier of the input that may get the input focus. Giving the focus to an input helps the user start correcting the input value right away.
This parameter is optional. If it is missing, the custom input class variable focus_input determines which input will get the focus. If this parameter is set to an empty string, no input will get the focus regardless of the value of the focus_input variable.
If you reimplement this function in custom input class, make sure you declare the $validations argument to be passed by reference.
Here follows an example of defined a special validation test that checks whether the day of a given month and year is valid:
$day=$form->GetJavascriptInputValue($form_object,$this->day);
$month=$form->GetJavascriptInputValue($form_object,$this->month);
$year=$form->GetJavascriptInputValue($form_object,$this->year);
$validations=array(
array(
"Commands"=>array(
"month=".$month,
"if(month=='04'",
"|| month=='06'",
"|| month=='09'",
"|| month=='11')",
" month_days=30",
"else",
"{",
" if(month=='02')",
" {",
" year=parseInt(".$year.")",
" if((year % 4)==0",
" && ((year % 100)!=0",
" || (year % 400)==0))",
" month_days=29",
" else",
" month_days=28",
" }",
" else",
" month_days=31",
"}",
"date_day=".$day
),
"Condition"=>"month_days<parseInt(date_day)",
"ErrorMessage"=>$this->invalid_day_error_message,
"Focus"=>$this->day
)
);
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->HandleEvent($form, $event, $parameters, $processed)
Execute any actions or return information in response to a request to handle an event sent by the by the browser that is presenting the form to the user.
This function is called by the forms class function also named HandleEvent when it determines that a given event handling request should be routed to this custom input object class.
An event request is usually targeted to a custom input when generates HTML or Javascript code that triggers a server side request to execute a certain action that is necessary to implement specific action that is part of the custom input behavior.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $event argument is the name of the event that has occurred.
The $parameters argument is an associative array with all the parameters that were passed in the event handling request.
The $processed argument is used to pass a boolean variable by reference that is set by this function to indicate whether the event was processed by the function.
The $error return value contains an error message if there was an error while trying to process the specified event. Otherwise it contains an empty string.
$error = $input_object->LoadInputValues($form, $submitted)
Perform any special actions that may need to take place when the main forms class retrieves the values of the inputs passed to the current script, eventually after the user has submitted the form.
This function is called for all custom inputs from the main forms class LoadInputValues function after the values of all basic inputs were loaded. So, it is safe for the custom class input function to retrieve the just loaded basic input values using the function GetInputValue.
Usually this function does not need to be reimplemented in the actual custom input classes.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $submitted argument has the same value that is passed to the main forms class LoadInputValues.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$html=$input_object->PageHead($form)
Retrieve the HTML code that is necessary to insert in the page head section to make the custom input work correctly.
This function is called for all custom inputs from the main forms class PageHead function.
This function needs to be reimplemented in the custom input classes that need special Javascript code, CSS styles, link or meta tags to be defined in the page head section.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $html return value contains the necessary HTML tags that should be inserted in the page head section.
$javascript=$input_object->PageLoad($form)
Retrieve the Javascript code that is necessary to execute when the page is loaded to make the custom input work correctly.
This function is called for all custom inputs from the main forms class PageLoad function.
This function needs to be reimplemented in the custom input classes that need to execute special Javascript code when the page body is loaded.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY ONLOAD tag.
$javascript=$input_object->PageUnload($form)
Retrieve the Javascript code that is necessary to execute when the page is unloaded to make the custom input work correctly.
This function is called for all custom inputs from the main forms class PageUnload function.
This function needs to be reimplemented in the custom input classes that need to execute special Javascript code when the page body is unloaded.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY ONUNLOAD tag.
$error=$input_object->ParseNewInputFormat()
Validate and process the current input display format template.
It parses the format template defined by the format variable and validates it to verify whether it complies with definition of place holders specified by the valid_marks variable.
This function is used by the custom input base class when it renders the input with the AddInputPart function. It may also be used to validate a new format template defined from the parameters of the AddInput or SetInputProperty functions.
Usually this function should not be reimplemented in the actual custom input classes.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error=$input_object->PostMessage($form, $message, $processed)
Handle a message targetted to the input.
This function is usually called to handle forwarded messages to delegate the handling of client side events. It only needs to be implemented by custom classes that expect handling forwarded messages.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $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. See the documentation of the PostMessage function of the main forms class for the list of common message entries.
The $processed argument is used to return a boolean value by reference that is set by this function to indicate whether it finished handling the posted message or it generated more messages that need to be handled by other inputs.
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=$input_object->ReplyMessage($form, $message, $processed)
Handle a message sent in reply to a previously posted event message.
Usually this function should be reimplemented in the actual custom input classes that post event handling messages.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $message argument is the same associative array of the message sent with the PostMessage function. It may contain new or altered entries to specify details that may trigger different actions when the message reply is processed.
The $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.
$error=$input_object->SetInputProperty($form, $property, $value)
Change the value of a specific property of the custom input.
This function needs to be reimplemented in the actual custom input classes to support setting properties that can be changed after the creation of the custom input with the AddInput function.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $property argument is the name of the property to be changed.
The $value argument is the new value of the property.
The $error return value contains an error message if the specified property is not supported, or cannot be changed after the input has been created, or for some other reason the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
$error=$input_object->SetSelectOptions($form, $options, $selected)
Set the list of options and selected values of a custom input that implements a behavior similar to a select input type.
This function is called when the SetSelectInput function of the main forms class is called for a custom input class.
This function needs to be reimplemented in the actual custom input classes that implement inputs similar to the select input type.
The $form argument is a reference to the forms class object on which this custom input is being used.
The $options argument is an associative array that defines the list of options, like for the OPTIONS argument passed to AddInput function.
The $selected argument is array that defines the values of the list of options that should be selected, like for the SELECTED argument passed to AddInput function.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
$error_message=$input_object->ValidateInput($form)
Validate the current value of the custom input.
This function is called by the main forms class Validate function after it has successfully validated all the basic type inputs. So, it is safe to retrieve from the ValidateInput function valid values of any basic inputs managed by a custom input class.
This function needs to be reimplemented in the actual custom input classes if they need to perform special types of validation besides the validations that are already performed on the basic inputs managed by custom input classes.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $error_message return value is a message suitable to present to the user that explains why the current input value is invalid. If the input value is valid, this return value should be an empty string.
$submitted_input=$my_form_object->WasSubmitted($form, $input)
Determine if a form was submitted by the custom input.
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $input argument specifies the identifier of the custom input or an empty string of the class is checking which of the form fields was submitted.
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.
The forms class distribution comes with separate custom input plug-in classes that are ready to implement Web forms based user interfaces with sophisticated controls that provide complex functionality and enhanced usuability.
Here follows the list of available custom input classes. More will be made available later.
Submit a form in the background without reloading the current page.
Multiple actions may be defined dynamically to be executed within the same form submission. The definition of an action does not require that the developer has prior Javascript knowledge.
Currently supported actions include altering the HTML contents of parts of the current page, redirecting the browser to a new page, setting the value of document element, waiting for a given period, etc..
HTML code to display within the page feedback element when the form submission response is completely sent to the browser by this plug-in class.
Default value: ""
Identifier of the page element within which a debug console should appear displaying information about the communication that happens during AJAX requests.
Default value: ""
Contents of the feedback page element.
This property can only be set while the AJAX response to a form submission is being sent. If it is set as an AddInput parameter, its value is ignored.
Default value: ""
Identifier of a page element within which feedback messages may appear when certain browser side events occur. Usually, the feedback page element is a <div> or <span>, but it may be of other type. This plug-in is not responsible for generating feedback elements. It only updates the contents of the specified page feedback element when a certain event occurs.
Currently, the events that can make the feedback page element be updated are the form submission and server communication timeout. The messages that appear in the feedback element are defined by the SubmitFeedback and TimeoutFeedback properties respectively. It may also be set using the Feedback property while the AJAX response to a form submission is being sent.
Default value: ""
HTML code to display within the page feedback element when the form is submitted by this plug-in class.
Default value: ""
Identifier of the input to which the form submission event messages will be forwarded. If this property is not set, the event messages will be queued for retrieval by the application.
Default value: none
Limit of time in seconds that a browser should wait to retrieve the form submission response from the server.
Default value: 60
HTML code to display within the page feedback element when the communication with the server times out.
Default value: ""
String with Javascript code to execute the form submission is completely sent to the browser.
Default value: none
String with Javascript code to execute the form submission takes more time to return its response than the configured timeout value.
Default value: "alert('The communication with the server has timed out.');"
String with Javascript code to execute after an AJAX form submission is sent.
Default value: none
Custom HTTP response header that may be sent before outputting the AJAX response. An empty string, means no custom header is outputted.
Default value: ""
Example: "X-no-gzip-compress: yes"
This custom input implements two types of action that can be triggered on the browser side: Submit and Load.
The Submit action is used to trigger the AJAX POST form submission. The Submit action supports the context arguments SetInputValue, SubForm and Validate.
The SetInputValue argument can be used to specify a list of inputs that should be set right before submitting the form. The argument value must be an associative array. The indexes of the array are the input names. The array values are the respective values of there inputs to set.
The SubForm argument can be used to restrict the validation that is performed before the form is submitted to a sub-form with the specified name.
The Validate argument is a boolean flag that indicates whether the form should be validated before submitting it via AJAX. By default the form is always validated.
The Load action is used to submit an AJAX GET request with custom parameters, thus without having to submit the form. The Submit action supports two context arguments named Parameters and RandomParameter.
The Parameters argument should be an associative array that defines the names and values of the parameters to send with the AJAX GET request.
The RandomParameter argument should be the name special parameter that will be initialized with a random value with the purpose to avoid eventual browser caching of the GET response.
When an AJAX submit custom input captures an AJAX form submission, it can post messages to the form message queue to let an application process the AJAX request and define how it should be responded to execute the desired actions on the browser page from which the form was submitted.
Currently, the AJAX submit input only posts submit type messages.
Immediate is a boolean parameter preset to 0. Applications should set it to 1 before replying to a message to instruct the AJAX submit input immediately send the response defined by the Actions response parameter, even if the response is not finished.
More is a boolean parameter preset to 0. Applications should set it to 1 before replying to a message, to instruct the AJAX submit input send the response defined by the Actions response parameter, but the response is not finished.
When the AJAX submit input receives a message response with this parameter set to 1, it posts the submit message again.
Window is a string parameter set to an expression that evaluates to the main browser Javascript Window object. It can be used to generate Javascript expressions that need to access to that object.
Document is a string parameter set to an expression that evaluates to the main browser Javascript Document object. It can be used to generate Javascript expressions that need to access to that object.
Form is a string parameter set to an expression that evaluates to the current Javascript Form object. It can be used to generate Javascript expressions that need to access to that object.
SubForm is a string parameter that may be set to the name of the sub-form associated to the form submission. This parameter is only set if the submit action context also specifies a sub-form parameter.
Actions is an array response parameter that should contain one or more entries to define which actions must be executed when the AJAX request response is sent to the browser.
Each action entry is defined by an associative array that defines the detail parameters of the action.
Common action parameters
Action is the name of the type action. Currently supported actions are:
Append HTML to a given document element.
Execute an arbitrary Javascript code.
Execute Javascript associated to an action executed in the context of another input.
Prepend HTML to a given document element.
Instruct the browser to redirect to a new page URL.
Replace a given document element with new HTML content.
Change a property of a given input.
Change the value of a given input.
Change the value of a given document element property.
Wait for a given period of time.
Action specific parameters
AppendContent
PrependContent
ReplaceContent
Identifier of the document element that will be altered.
HTML data that defines the content alteration.
Command
Javascript code to execute.
HTML data that defines the content alteration.
Connect
Identifier of the input which will execute the connection action.
Name of the action to execute.
Array with context data to pass when executing the action.
Redirect
URL of the new page to redirect.
SetInputProperty
Identifier of the input.
Name of the input property to set.
Expression that defines the value to set the input property.
SetInputValue
Identifier of the input.
Expression that defines the value to set the input.
SetValue
Identifier of the document element.
Identifier of the document element property to set. If the property is a variable of the document element object, you can use . to specify which object is it.
Value to set the document element property.
Type of the value to set. Currently supported data types are: string, number, float, integer, boolean, undefined, null, opaque. opaque should be used for a value defined by an expression of an arbitrary type.
Default: "string"
Wait
Period of time to wait in seconds. It must not be zero. It may be an integer or a floating point number to specify decimal periods of time.
/*
* Create a form object.
*/
$form = new form_class;
$form->NAME = 'some_form_name';
/*
* The form submission method must be POST.
*/
$form->METHOD = 'POST';
/*
* Make the form be submitted to the current script.
*/
$form->ACTION = '';
/*
* Add some fields.
*/
$form->AddInput(array(
'TYPE' => 'text',
'NAME' => 'login',
'ID' => 'login',
'LABEL' => '<u>L</u>ogin',
'ACCESSKEY' => 'L'
));
$form->AddInput(array(
'TYPE' => 'text',
'NAME' => 'password',
'ID' => 'password',
'LABEL' => '<u>P</u>assword',
'ACCESSKEY' => 'P'
));
$form->AddInput(array(
'TYPE' => 'submit',
'NAME' => 'doit',
'ID' => 'doit',
'VALUE' => 'Submit'
));
/*
* Add the AJAX form submit custom input.
*/
$form->AddInput(array(
'TYPE' => 'custom',
'NAME' => 'sender',
'ID' => 'sender',
'CustomClass' => 'form_ajax_submit_class',
'Timeout' => 60,
'ONTIMEOUT' => 'alert('The communication with the server has timed out.');'
));
/*
* Make the submit button to the AJAX form submit custom input to make
* the form be submitted via AJAX when the submit button is clicked.
* Other client side events could trigger AJAX form submission.
*/
$form->Connect('doit', 'sender', 'ONCLICK', 'Submit', array());
/*
* Call HandleEvent to let the custom input to let
* the class handle the AJAX form submission
*
* Do not output anything before these lines.
*/
$form->HandleEvent($processed);
if($processed)
exit;
/*
* Was the form submitted via AJAX?
* Check whether the AJAX form submit input posted a message.
*/
if($form->GetNextMessage($message))
{
/*
* The form was submitted via AJAX.
* Lets process the messages to build an AJAX response and
* update only the relevant parts of the page on the browser
*/
do
{
/*
* Check what kind of events did occur on the browser?
*/
switch($message['Event'])
{
case 'submit':
/*
* The form was submitted. Lets validate and process it.
*/
$form->LoadInputValues();
$error_message = $form->Validate($verify);
/*
* If the form fields are valid, make any other
* server side only validations
*/
if(strlen($error_message)==0)
{
$error_message = ValidateLoginAndPassword(
$form->GetInputValue('login'),
$form->GetInputValue('password')
);
}
/*
* Are there any form validation errors?
*/
if(strlen($error_message))
{
/*
* Tell the form submitter input to send to the browser
* an order to display validation error feedback message.
*
* Replace the contents of the tags <div id="feedback"></div>
* with a validation error message.
*
* Make sure the message is correctly encoded in HTML using
* HTMLSpecialChars function.
*/
$message['Actions'] = array(
array(
'Action' => 'ReplaceContent',
'Container' => 'feedback',
'Content' => 'Validation error: '.HtmlSpecialChars($error_message);
)
);
}
else
{
/*
* The form was validated without errors.
* Lets execute the form processing actions
*/
/* Some processing actions should be executed here */
/*
* Show some feedback on the browser page.
*/
$message['Actions'][] = array(
'Action' => 'ReplaceContent',
'Container' => 'feedback',
'Content' => 'The form was submitted and processed successfully!'
);
/*
* Wait a few seconds before redirecting
* the browser to a new page.
*/
$message['Actions'][] = array(
'Action' => 'Wait',
'Time' => 3
);
/*
* Redirect the browser to a new page.
*/
$new_page = GetEnv('REQUEST_URI');
$message['Actions'][] = array(
'Action' => 'Redirect',
'URL' => 'http://'.GetEnv('HTTP_HOST').$new_page
);
}
break;
}
/*
* Reply to the form submit event to make it respond
* to the AJAX request in such way to make the browser
* execute to response actions.
*/
if(strlen($form->ReplyMessage($message, $processed)))
exit;
}
/*
* Loop until there are no more event messages
* or the processing was finished
*/
while(!$processed
&& $form->GetNextMessage($message));
/*
* If the request was fully processed, lets exit the script.
*/
if($processed)
exit;
}
/*
* Here validate, process and output the form
* like with any normal non-AJAX form submission
*/
Manage visual effects to be applied to elements of a form page.
This class requires a Javascript animation class to actually perform the animation effects. The Javascript class is available with this PHP class as a separate file named animation.js.
This PHP class generates the necessary HTML script tags to include the Javascript class file in the HTML page head section. Applications should use the main forms class PageHead function to retrieve the page head section tags that include the animation Javascript class file.
Directory of the URI of the Javascript class file animation.js. If the directory of the URI of the current script if the same of the animation.js file, just leave this property set to an empty string.
Default value: ""
This plug-in class implements only one action that can be triggered on the browser side. That action is named AddAnimation. It is used to a given animation to the list of running animation.
The definition of the animation should be passed to the action context parameter. This parameter is an associative array with entries to define several animation properties. Currently, it supports the following properties:
Integer value that defines the level of the debug mode. 0 means that debugging is disabled. 1 or more makes the class display alert messages when animations define effects that may not be applied due to animation definition errors or impossible situations.
Array with the definition of each effect in the animation sequence. Each entry of the array is an associative that describes the effect properties. Currently, the following properties are supported:
Animation
Name of the animated associated to the effect. It is required by the CancelAnimation effect.
Content
HTML tags of the content to use by the effect. It is required by the AppendContent, PrependContent and ReplaceContent effects.
Duration
Duration of the effect in seconds. It is required by the FadeIn, FadeOut and Wait effects.
DynamicElement
Javascript expression that defines dynamically the identifier of the page element to apply the effect. It is required in alternative to the Element property.
Element
Identifier of the page element to apply the effect. It is required by the AppendContent, FadeIn, FadeIn, Hide, PrependContent and ReplaceContent and Show effects.
Type (Required)
Name of the type of effect. Currently it supports the following effect types:
AppendContent
Insert more HTML tags at the end of the content of a given page element.
CancelAnimation
Stop and remove an animation given its name.
FadeIn
Make a given hidden page element appear smoothly until it becomes completely visible.
FadeOut
Make a given page element disappear smoothly until it becomes completely invisible.
Hide
Turn a given page element invisible.
PrependContent
Insert more HTML tags at the beginning of the content of a given page element.
ReplaceContent
Replace the HTML tags contained within a given page element.
Show
Turn a given page element visible.
Wait
Wait a given period of time.
Visibility
Defines the CSS property that will be used to control the visibility of an element for the effects: FadeIn, FadeIn, Hide, and Show. It may be set to either visibility or display. The default is visibility.
Name to associate to the animation being defined.
Javascript expression that defines the Window object on which the animation will run. It is necessary if it is intended to run an animation on a browser window or frame distinct from the one that is starting the animation.
Automatically complete the values typed by the user in a text input by presenting a menu with a list of possible words that start with the text typed so far.
In dynamic mode, this class needs the custom input plug-in class form_ajax_submit_class to retrieve the completion values on demand from the server.
Delay in seconds that the input should wait after the last keystroke before it attempts to complete the text typed by the user.
Default value: 0.5
Identifier of the text input that will have the typed text automatically completed. This class does not add the text input to the form. It must be added separately by the application.
Default value: none
Minimum number of characters that the user must have typed before the class attempts to complete the text.
Default value: 3
HTML code to display within the page feedback element when the completion AJAX request is finished. This option is only relevant in the dynamic mode.
Default value: ""
Associative array that enumerates all possible completion values. The indexes of the array are the completion text strings. The array values define the HTML code used to present the completion options in the menu.
Default value: not set
Boolean flag that determines whether the completion values are retrieved on demand from the server using AJAX, or are loaded all at once within the page Javascript code generated by this class.
Default value: 0
Identifier of a page element within which feedback messages may appear when the completion is performed dynamically using AJAX. This option is only relevant in the dynamic mode.
Default value: ""
Name of the presentation style class with which the menu items should be rendered.
Default value: not set
Definition of the presentation style attributes with which the menu items should be rendered.
Default value: "padding: 1px; color: #000000;"
Name of the presentation style class with which the menu should be rendered.
Default value: not set
Definition of the presentation style attributes with which the menu should be rendered.
Default value: "background-color: #ffffff; border-width: 1px; border-color: #000000; border-style: solid; padding: 1px;"
Name of the presentation style class with which the menu items should be rendered when they are selected.
Default value: not set
Definition of the presentation style attributes with which the menu items should be rendered when they are selected.
Default value: "padding: 1px; color: #ffffff; background-color: #000080;"
Identifier of the button input that will trigger the action to make the menu display all the available options at once. This class does not add the button input to the form. It must be added separately by the application.
Default value: none
HTML code to display within the page feedback element when a completion AJAX request is submitted to the server. This option is only relevant in the dynamic mode.
Default value: ""
Limit of time in seconds that a browser should wait to retrieve the completion AJAX request response from the server. This option is only relevant in the dynamic mode.
Default value: 60
HTML code to display within the page feedback element when the communication with the server times out. This option is only relevant in the dynamic mode.
Default value: ""
CAPTCHA is a designation that means: a Completely Automated Public Turing test to tell Computers and Humans Apart.
It is a kind of tests that are used to make it dificult for automated programs to have access to certain resources by imposing challenges that are easy to respond for humans but much harder to solve for the automated programs.
This custom input type implements a CAPTCHA test by requiring that the user enters a text that is presented in an image that appears next to a text input.
Robot programs will have difficulty to determine what is written in the image as it may appear too obfuscated to be read even by OCR programs (Optical Character Recognition).
This kind of custom input is often used to prevent abuses of sites that are accessed by robot programs to perform automated tasks like for instance retrieving all pages of a site in a very short period or even retrieving pages restricted to a limited number of users.
The class requires the PHP is configured to use the GD image library extension. Certain versions of the GD library do not support GIF images. In this case, the PNG or JPEG formats must be used.
The class requires the PHP is configured to use the mcrypt library extension to be able to encrypt the validation text.
Color to be used to clear the background of the verification image. It must be in the hexadecimal RGB format: #RRGGBB. If it is set to an empty string it will appear with transparent background or white in case the image is generated in a format that does not support transparency.
Default value: ""
Number of seconds of the time for which the validation text generated by the class remains valid. It must be a value greater than 0. If it is not set the text never expires.
Default value: not set
Error message to return when the input value is not valid because the validation time expired. This property is required if the ExpiryTime property is set.
Default value: not set
Specify number of the font that will be used to render the verification text. It can be either a font number from 0 to 5 to use a font built-in the GD library, or a custom font number returned by functions for opening fonts of other types.
Default value: 2
Format of the template that defines how the input elements will be presented. There are four supported place holders for defining how the image, validation text, redraw button and the encrypted validation key fields will be presented: image, text, redraw and validation.
Default value: "{image} {text} {redraw}{validation}"
Specify the type of vertical alignment of the verification image, like with the ALIGN attribute of the HTML IMG tag.
Default value: "top"
Specify the type of format that the verification image will be generated. The supported formats are: gif, jpeg, png.
Default value: "gif"
Specify the height with which the verification image will be generated.
Default value: 20
Specify the width with which the verification image will be generated.
Default value: 80
Name of the presentation style class with which the text input field should be rendered.
Default value: not set
List of extra attributes that should be added to the text input HTML tag when the form output is generated.
Default value: not set
Definition of the presentation style attributes with which the text input field should be rendered.
Default value: not set
Order of navigation of the text input field when using the tab key, as defined by the HTML TABINDEX attribute.
Default value: not set
Private key that is used to encrypt the text that is passed back in a separate request to the class to draw and output the image.
Default value: not set
Specify the name of the image file in the GIF format that will be used as visual noise to obfuscate the text in the verification image. It must be a transparent image, or else the validation text will not be visible.
Default value: ""
Specify the name of the image file in the PNG format that will be used as visual noise to obfuscate the text in the verification image. It must be a transparent image, or else the validation text will not be visible.
Default value: ""
Name of the presentation style class with which the redraw submit input should be rendered.
Default value: not set
Definition of the presentation style attributes with which the redraw submit input should be rendered.
Default value: not set
Text to be used in the redraw submit button.
Default value: "Redraw"
Text to be used in the redraw submit button.
Default value: "Redraw"
Boolean flag that determines whether the verification text should be changed to a new value when the user enters an incorrect text.
Default value: 0
Color to be used to draw the validation text. It must be in the hexadecimal RGB format: #RRGGBB.
Default value: "#000000"
Number of characters that will have the validation text.
Default value: 4
Error message to return when the input value does not match the validation text presented in the image.
Default value: not set
Text string for validation. By default it is set to a random text by this plug-in but it may be set initially to a specific value.
Default value: not set
Name of the presentation style class with which the verification image should be rendered.
Default value: not set
Definition of the presentation style attributes with which the verification image should be rendered.
Default value: not set
This custom input type can be used to simplify the creation of user interfaces and processing of events when using the form_scaffolding_class custom input to manipulate records of entries stored in databases or other forms of storage.
It should be used together with another custom input of type form_scaffolding_class. That other custom input must have set the TargetInput property set to the identifier of the form_crud_class input.
Name of the data source class that will be used to access the record entries data. That class should extend the base class form_crud_data_source_class.
Default value: not set
Identifier of the form_scaffolding_class custom input with which this input will be integrated.
Default value: not set
The form_crud_data_source_class is a class defined together with the form_crud_class class with the purpose of defining base functions to implement custom data source classes.
Data source classes serve as adapters to store and retrieve data from any type of data container. That data is displayed or edited using the form_crud_class and the form_scaffolding_class input classes together.
Applications need to create sub-classes that extend the form_crud_data_source_class and redefine just the functions that are necessary to customize the access to the data that will be stored or retrieved to be displayed or edited.
The base class can also generate the presentation of entries to be displayed by defining some base class variables to configure the presentation templates.
HTML string of the template that defines how an entry should be displayed.
Set this variable to an HTML template before the ViewEntry function of the base data source class is called.
The template should include place holder marks that will be replaced by the values of the entry fields. For instance the {age} place holder will be replaced by the value of the entry field named age.
Templates may also have conditional sections which will only be displayed if the respective value is defined. For instance a template with a conditional section like this {age-section}Age: {age}{/age-section} will only be displayed if the value age-section is defined.
Default value: 'the entry template was not defined'
Associative array that defines properties of place holder value used in the template defined by the entry_template variable.
The keys of the array are the place holder names. The array values are also associative arrays with the list of the properties. Currently the following properties are supported:
Boolean property value that defines whether the current place holder defines a conditional section.
If a conditional section place holder value named section is defined, the base data source class function ViewEntry will replace a section in the template defined as {section}some section data{/section} by just some section data. If the place holder value is not defined the whole section is removed from the template.
Boolean property value that defines whether the current place holder value should be encoded as HTML before it is replaced in the template.
Default value: array()
Text string that defines the beginning of place holder marks in the template.
Default value: '{'
Text string that defines the end of place holder marks in the template.
Default value: '}'
Text string that defines the beginning of place holder marks that define the end of sections in the template.
Default value: '{/'
Here follows the list of functions of the form_crud_data_source_class class that custom data source classes may redefine.
Initialize
Synopsis
$error = $data_source->Initialize($form, $arguments)
Purpose
Initialize the internal state of the data source object. It is called after the data source object is created during the call to the AddInput function.
Implement this function if you need to take values from the AddInput arguments.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $arguments argument is an associative array with the arguments passed to the AddInput function.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
Finalize
Synopsis
$error = $data_source->Finalize($form)
Purpose
Free any resources allocated during the life time of the data source object.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
GetListing
Synopsis
$error = $data_source->GetListing($form, $listing)
Purpose
Retrieve information that will be used to display the current page of listing entries.
Implement this function if the scaffolding input will display a listing of entries.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $listing argument is a reference to an associative array with values of properties of the form_scaffolding_class input. The Page entry contains the number of the listing page that is currently being displayed. The values set in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: Rows, IDColumn, Columns, TotalEntries, PageEntries, Page, ListingMessage.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
InitializeEntry
Synopsis
$error = $data_source->InitializeEntry($form, $entry, $invalid, $values)
Purpose
Validate whether it is acceptable to create an entry in the current circumstances and eventually preset the values of some fields.
Usually it is not necessary to redefine this function. It may be needed for instance when there are parameters defined in the URL or the current user session that alter the circumstances to the point the application may disallow the creation of new entries.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $entry argument is a reference to an associative array that may be set with values of properties of the form_scaffolding_class input. The values set in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: CreateCanceledMessage, CreateMessage.
The $invalid argument is a reference to an a boolean variable that should be set by the function to 1 if creating a new entry should be disallowed.
The $values argument is a reference to an associative array that may be set with values to initialize form inputs. The values in this array will be assigned to the respective form inputs after the function returns. checkbox, radio or other types of custom checkable inputs will have the CHECKED property set according to the assigned value which must be a boolean value.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
GetEntry
Synopsis
$error = $data_source->GetEntry($form, $entry, $invalid, $values)
Purpose
Retrieve the values of a given entry, if it is valid.
Implement this function if the scaffolding input will be viewing, updating or deleting individual entries.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $entry argument is a reference to an associative array that may be set by this function with values of properties of the form_scaffolding_class input. The array is passed to the function with an entry named ID set to the identifier of the entry to be retrieved. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties:
When viewing an entry: ViewingMessage, EntryOutput.
When updating an entry: UpdateCanceledMessage, UpdateMessage, UpdatedMessage.
When deleting an entry: DeleteMessage, DeleteCanceledMessage, DeletedMessage.
The $invalid argument is a reference to an a boolean variable that should be set by the function to 1 if the requested entry cannot be accessed for some reason.
The $values argument is a reference to an associative array that may be set by the function with values to assign to form inputs when an entry is being updated. The values in this array will be assigned to the respective form inputs after the function returns. checkbox, radio or other types of custom checkable inputs will have the CHECKED property set according to the assigned value which must be a boolean value.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
SaveEntry
Synopsis
$error = $data_source->SaveEntry($form, $creating, $entry, $values)
Purpose
Save the values of new or existing entries.
Implement this function if the scaffolding input will be used to create new entries or update existing entries.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $creating argument is boolean value that determines whether the entry is being created. Otherwise the function is being called to update an existing entry.
The $entry argument is a reference to an associative array that may be set by this function with values of properties of the form_scaffolding_class input. The array is passed to the function with an entry named ID set to the identifier of the entry to be saved when it is updating an existing entry. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties:
When creating an entry: CreatedMessage.
When updating an entry: UpdatedMessage.
The $values argument is a reference to an associative array with values with form inputs to create or update the entry. The values of checkbox, radio or other types of custom checkable inputs are boolean values that have the current state of the CHECKED state property.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
ViewEntry
Synopsis
$error = $data_source->ViewEntry($form, $entry, $values)
Purpose
Generate the output to display an entry.
Implement this function if you want to customize the presentation of an entry and the scaffolding input will be displaying a stored entry or previewing an entry with new values without saving.
Alternatively your data source class may simply inherit the base class behavior and automatically generate the presentation of entries by defining the variables entry_template and entry_template_properties.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $entry argument is a reference to an associative array that may be set by this function with values of properties of the form_scaffolding_class input. The array is passed to the function with an entry named ID set to the identifier of the entry to be displayed. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: ViewingMessage, EntryOutput.
The $values argument is a reference to an associative array with values of the entry fields. The values of checkbox, radio or other types of custom checkable inputs are boolean values that have the current state of the CHECKED state property.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
DeleteEntry
Synopsis
$error = $data_source->DeleteEntry($form, $entry)
Purpose
Delete a given entry.
Implement this function if the scaffolding input will be deleting specified entries.
Usage
The $form argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.
The $entry argument is a reference to an associative array that may be set by this function with values of properties of the form_scaffolding_class input. The array is passed to the function with an entry named ID set to the identifier of the entry to be deleted. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: DeletedMessage.
The $error return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.
Let the user specify a date of the calendar with year, month and day.
The same as the Accessible property for basic inputs.
Default value: not set
Boolean flag that indicates the plug-in class to ask the user for an age relative to today's date.
Default value: 0
Default value to be used when the ChooseControl option is set whether checkbox that appears should be initially set.
Default value: 0
Boolean flag that indicates when the ChooseControl option is set whether checkbox that appears should be initially set.
Default value: 0
Boolean flag that indicates whether the date input should show a checkbox to let the user decide whether he wants to choose a date manually or assume a given default.
Default value: 0
Name of the presentation style class with which the day input field should be rendered.
Default value: not set
Definition of the presentation style attributes with which the day input field should be rendered.
Default value: not set
Set the date day to a fixed value that cannot be changed by the user.
Default value: not set
Format of the template that defines how the date will be presented. There are three supported place holders for defining how the year, month and day fields will be presented: year, month and day.
Default value: "{year}-{month}-{day}" or "{year}-{month}" when HideDay parameter is set to 1
Hide the day field so it is not displayed to the user. This parameter may only be set to 1 if the FixedDay parameter is also set.
Default value: 0
Name of the presentation style class with which the month input field should be rendered.
Default value: not set
Definition of the presentation style attributes with which the month input field should be rendered.
Default value: not set
Associative array that defines the text for each of the 12 months of the year. The array entry indexes go from "01" to "12".
Default value: array with all entry values set to the entry indexes
Boolean flag that determines whether the date input value is not required. An optional date field is accepted as valid when either the year, month and day fields are empty. In this case, the GetInputValue function returns an empty string.
Default value: 0
Integer value that is used to determine whether year input will be displayed as input of type text or select.
If the ValidationStartDate and ValidationEndDate arguments are defined and the number of years between the two dates is less than the value of the SelectYears argument, the year is presented as a select type input with the given range of years as option values.
Default value: 10
Order of navigation of the input fields when using the tab key, as defined by the HTML TABINDEX attribute. When not set, all fields will have the same TABINDEX property value.
Default value: none
Current value of the date. An empty string means, date not set. It may also be set to "now" as an alias to the current day date.
Default value: ""
Validation error message for when the user specifies a date that does not exist on the calendar.
Default value: "It was not specified a valid date."
Validation error message for when the user specifies an invalid day.
Default value: "It was not specified a valid day."
Default validation error message.
Default value: not set
Day of the end of the range of allowed dates. It may be set to "now" as an alias to the current day date.
Default value: "9999-12-31"
Validation error message to present when the current date is set to a day after the end date.
Default value: default validation error message
Validation error message for when the user specifies an invalid month.
Default value: "It was not specified a valid month."
Day of the start of the range of allowed dates. It may be set to "now" as an alias to the current day date.
Default value: "0001-01-01"
Validation error message to present when the current date is set to a day before the start date.
Default value: default validation error message
Validation error message for when the user specifies an invalid month.
Default value: "It was not specified a valid year."
Name of the presentation style class with which the year input field should be rendered.
Default value: not set
Definition of the presentation style attributes with which the year input field should be rendered.
Default value: not set
Let the user edit an HTML document visually.
Name of the presentation style class with which the editor container should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.
Default value: not set
Number of rows of the editor as defined for the COLS attribute of the <TEXTAREA> HTML tag.
Default value: not set
URI of the CSS file that defines styles for use in the editor frame.
Default value: not set
Directory of the URI of the Javascript class file html_editor.js. If the directory of the URI of the current script if the same of the html_editor.js file, just leave this property set to an empty string.
Default value: ""
Name of the editing mode. Valid modes are visual for the visual editor and html for the HTML editor.
Default value: "visual"
Number of columns of the editor as defined for the COLS attribute of the <TEXTAREA> HTML tag.
Default value: not set
Boolean flag that determines whether the editor toolbars are displayed.
Default value: 1
Definition of the presentation style attributes with which the editor container should be rendered.
Default value: not set
Associative array that defines the properties of the supported template variables. The array entry names are the names of the variables. The array values are also associative arrays that define template property values. Currently the following template properies are supported:
Associative array that defines all the supported alternative values of template. The array entry names are the alternative variable names. The array entry values are also associative arrays that define properties of the alternative values. Currently only the Preview and Title are supported. They have the same meaning as for the main template variable properties.
Default value: not set
Boolean flag that determines whether the template variable should be displayed as inline or block element of the HTML document. If this option is omitted, the variable will be expanded to the value passed to the Value property.
Default value: none
HTML to be used when displaying the template variable preview in the visual editor.
Default value: not set
Text to be used for the template variable in the insert template menu.
Default value: not set
HTML value to expand the template variable when the Inline variable is not set.
Default value: not set
Default value: not set
This custom input type can be used to display a group of inputs that appear in pages that the user can switch clicking on tab buttons.
If Javascript is disabled when the user clicks on a tab, the form is submitted to the server to be rendered again, showing just the page that corresponds to the clicked tab.
The tabs are rendered in such way to give a 3D look effect to make it clear to the user which is the currentlty selected tab. In some browsers these tabs appear with rounded borders. Alternatively, the page tabs and buttons may be rendered using custom CSS classes.
The tab buttons are rendered in a row one after another. When there are too many tab buttons, there is the possibility to split the buttons in several rows to make them occupy less width.
The presentation of the each page may also be customized using a sub-class of the form_layout_paged_class with a function named AddPagePart. This function takes just one parameter, which is the identifier of the current page to be rendered.
Boolean flag that indicates whether the size of the container of the pages should be adjusted automatically to fit all pages.
Default value: 0
Identifier of the page that appears selected initially.
Default value: first page
Time in seconds that it will take the fade effect to make switched pages appear smoothly. It may be a floating point number to express a value below 1 second. Set to 0 to disable the page fade effect.
Default value: 0
Directory of the URI of the Javascript class files necessary to implement animation effects.
Default value: ""
Name of alternative CSS classes that define how certain elements will be rendered, like: tab of the current page, tab of other pages, gaps between tabs, button of the current page, and button of other pages.
Default value: ""
Associative array that defines parameters of each form page. The keys of the entries of this array are the identifiers of the pages. The array entry values should be also associative arrays that define the respective page parameters.
Here follows the list of currently supported parameters:
Name to display in the respective page tab.
Default value: the same as the page identifier
Text to display in each page as a caption to explain the purpose of the page fields.
Default value: none
Name of the option to specify whether the respective page tab button should break the row of tab buttons on which it is displayed.
This option may be either "before" or "after" depending on whether the row of buttons should be split before or after the current page tab button.
Default value: none
Boolean flag that indicates whether the tabs should be displayed or hidden.
Default value: 1
This custom input implements one types of action that can be triggered on the browser side: SwitchPage.
The SwitchPage action is used to switch the currently selected page. It supports the context arguments Page, PageValue and InputsPage.
The Page argument can be used to specify the identifier of a page to be switched.
Alternatively, the PageValue can be used to specify a JavaScript string variable or expression that will be used to dynamically set the identifier of the page to be switched.
The InputsPage argument can be used to specify an expression that references a Javascript object whose members are input identifiers, and the member values are pages to be switched. This argument is used internally to automatically switch the current page when the form has invalid fields.
This custom input type can be used to automatically compose the layout of a group of inputs that should appear vertically align.
Bidimensional array that lists groups of identifiers of all the inputs to be included in the layout in side-by-side columns.
Default value: none
Associative array that specifies which of the inputs listed by the Inputs property should be rendered with custom HTML data. The keys of the entries of this array are the names of the data inputs and the entry values should the HTML data that should be rendered for the row of the respective data inputs.
Default value: none
HTML text string that defines how to render the input special mark for inputs that are not flagged as invalid.
Default value: empty string
HTML text string that defines what should be rendered after the sequence of input rows.
Default value: </table>
HTML text string that defines what should be rendered before the sequence of input rows.
Default value: <table>
HTML template that defines how each input row should be rendered. It must have marks named {input}, {label} and {mark} to denote where the input, label and a special input mark respectively should appear in the input row.
Default value: <tr><td valign="top">{label}:</td><td valign="top">{input} <span id="mark_{id}">{mark}</span></td></tr>
Array that lists the identifiers of all the inputs to be included in the layout.
Default value: none
HTML text string that defines how to render the input special mark for inputs that are flagged as invalid.
Default value: empty string
HTML template that defines how each input row should be rendered for inputs that do not have an associated label.
Default value: <tr><td colspan="2" align="center">{input}</td></tr>
Associative array that defines special properties to override the default way each input row is rendered. The keys of the entries of this array are the names of the inputs and the entry values should more associative arrays that define the respective input rendering properties.
Here follows the list of currently supported properties:
Name of the position that determines whether the input should be presented grouped horizontally with the next inputs within the same row. If this property is left, middle or right, the respective input appears respectively on the left, middle or right of the centered group of inputs. Multiple inputs may be in the middle.
Currently, only inputs without labels can be presented as centered pairs.
Default value: none
HTML text string that overrides the DefaultMark property value.
Boolean flag that determines whether the input row should not appear visible in the form but should be added to the output as hidden input . If this property is 0, the respective input row is ommited from the form output.
Default value: 0
HTML template that overrides the InputFormat property value.
HTML text string that overrides the InvalidMark property value.
Boolean flag that determines whether the input should be rendered in read-only mode. If this property is 1, the respective input cannot be edited.
Default value: 0
Boolean flag that determines whether the input row should present the input and the label in switched positions. If this property is 1, the respective input appears in the place of the label and vice-versa.
Default value: 0
Boolean flag that determines whether the input row should appear in the form output. If this property is 0, the respective input row is ommited from the form output.
Default value: 1
HTML template that defines how each input row should be rendered for inputs that have the CenteredPair property set to left.
Default value: <tr><td colspan="2" align="center">{input}
HTML template that defines how each input row should be rendered for inputs that have the CenteredPair property set to right.
Default value: {input}</td></tr>
HTML template that defines how each input row should be rendered for inputs that have the SwitchedPosition property set.
Default value: <tr><td align="right">{input}</td><td>{label} <span id="mark_{id}">{mark}</span></td></tr>
This custom input type implements a select input that can let the user choose one or more options from multiple groups of options.
The current group of options may be switched dynamically on the client side when it changes the value of another input to which this custom input is linked.
This custom input type supports most of the properties of base select input type.
Associative array that contains all the groups of options that may be displayed. The keys of the entries of this array are the names of the groups and the entry values should be more associative arrays that define each group of options as defined by the OPTIONS attribute of the base select type input.
Default value: none
Identifier of the input linked to this custom input that defines the group of options that is currently in use. The current value of the linked input defines the current group of options. When the value of that input changes, the group of options of this custom input is switched.
Default value: none
Boolean flag that tells whether the alternative groups of options should be dynamically retrieved by the browser when the linked input changes. When this option is set to 1, each group of options is retrieved from the server using Javascript and an hidden inline frame. Otherwise, the groups of options are passed all at once within the Javascript code that is generated with the form HTML.
The non-dynamic mode lets the linked input options be switched immediately, but for large groups of options the form page may become very large and slow to load. The dynamic mode is recommended when using large groups of options, or when the options need to be retrieved from a slow storage medium, like for instance a database. Look at the custom input sub-classes that are specialized in retrieving options from databases and other data sources.
Default value: 0
Limit number of columns of width that this input will have initially. If this property is set and the Dynamic property is not set, the class will determine which is the longest option of all the specified groups of options. If the property is set to 0 the class sets the initial display width of the select input to the length of the longest option in em units. If this property is more than 0, the initial display width is set to no more columns than the value of this property.
Default value: not set
Limit number of rows of height that this input will have. If this property is set and the Dynamic property is not set, the class will determine which is the longest group of options of all the specified groups. If the property is set to 0 the class sets the number of rows of the select input the count of options of the longest group. If this property is more than 0, the number of rows is set to no more than the value of this property.
Default value: not set
This custom input type implements an emulation of a select input that allows to configure the presentation of the options as rows of a table with customizable HTML content.
This custom input type supports most of the properties of base select input type.
Boolean option to tell whether the input is accessible when the form is in read only mode, or not accessible otherwise.
Default value: none
CSS style used to render the list select container.
Default value: none
Array of options that defines how each column of the list select table will be rendered. Each entry contains an associative array that defines properties of each table column. Here follows the list of supported properties:
HTML that will be displayed in the column header row.
Default value: none
Name of the entry of the array passed by the Rows parameter from which it will be displayed the data for the current column.
Default value: none
String that defines the type of the column. If the type is Input, the column will display a radio input to select the respective option. If the type is Data, the column will display data from the array passed by the Rows input parameter. If the type is Option, the column will display data from the respective option value.
Default value: Data
Default value: array(
array(
'Type'=>'Input',
),
array(
'Type'=>'Option',
),
)
Boolean option to tell whether the list will be a single or multiple select list.
Default value: 0
Javascript code to be executed when the selected input changes.
Default value: none
HTML that defines what should be displayed in the place of each option input if the input is displayed as not accessible.
Default value: none
Associative array that defines the values and text of a select field as defined for the OPTION HTML tag.
Default value: none
HTML that defines what should be displayed if the input is displayed as not accessible.
Default value: none
Associative array with data to be displayed in the list select table. The array keys are the names of the select options. The array keys are also associative arrays with the rows of data.
Default value: none
Array of values of selected options when in multiple mode.
Default value: none
Number of rows that occupies container of the list select table. The size of the container is defined in em units, so it may not match exactly the number of list select table rows that will be made visible.
Default value: none
CSS style definition that will be used to render the list select container.
Default value: border-style: solid; border-color: #808080 #ffffff #ffffff #808080; border-width: 1px
Value of the selected option.
Default value: none
This custom input type lets the user specify a location in the world by pointing it on a map. The input retrieves the latitude and longitude coordinates of the selected location.
The Google Maps API requires an unique key to work on the pages of each site. The key may be obtained for free in the Google Maps API signup page.
Most of HTML and Javascript generated for this kind of custom input must be inserted in the page head section. Applications that use forms with this custom inputs must call the main forms class PageHead function to retrieve the necessary HTML tags to be inserted within the page head section.
This kind of input must be initialized from the page body load event. Use the main forms class PageLoad function to retrieve the necessary Javascript code to assign to the ONLOAD attribute of the page BODY HTML tag.
To avoid memory leak bugs of certain browsers, special Javascript code must be executed from the page body unload event. Use the main forms class PageUnload function to retrieve the necessary Javascript code to assign to the ONUNLOAD attribute of the page BODY HTML tag.
Boolean flag that determines whether the input should accessible. When the input is not accessible, it displays the map but the coordinates of the location point cannot be changed.
Default value: 1
Associative array that specifies whether the maps may show advertising from Google AdSense to be credited to a given publisher. The array may contain values that define options for controlling aspects of the advertising.
Identifier of the publisher account channel to be associated with advertising that is displayed.
Default value: none
Limit number of advertising units that can be displayed in the map.
Default value: 2
Identifier of the AdSense publisher account. Usually starts with ca-pub-.
Default value: none
Default value: none
Value to adjust the coordinates bounding box to set the zoom level automatically when the ZoomMarkers property is specified. A positive value makes the bounding box expand.
Default value: none
CSS stylesheet used to render the <div> tag on which the map will appear.
Default value: none
Array that defines one or more marker managers that may cluster multiple markers in case they overlap in the current zoom level. Each cluster is described by an entry of the array. Each cluster entry should be an associative array that defines several cluster properties. Here follows the list of currently supported cluster properties:
Name of the type of cluster that will aggregate the markers. Currently only the MarkerClusterer marker manager is supported.
Default value: none
Path URL of the script that defines the marker manager Javascript class. For MarkerClusterer marker manager the default path is markerclusterer.js.
Default value: none
Associative array that specifies which additional built-in controls will be displayed on the map. The array entry indexes specify the control names. The entry values specify more associative arrays to define properties to customize details of the controls. The supported controls are: "SmallMap", "LargeMap", "SmallZoom", "Scale", "MapOverview" and "MapType". Currently no control properties are supported.
Default value: none
Boolean flag that determines whether the coordinate values should be displayed along with the map.
Default value: 1
Boolean flag that determines whether the location marker should not be displayed.
Default value: 0
Associative array that defines any custom icons that may be needed. The array keys are names assigned to each custom icon. The array values are associative arrays that define icon properties as described in the Google Maps documentation. Currently the following properties are supported: image, shadow, printImage, mozPrintImage, transparent, dragCrossImage, iconSize, shadowSize, dragCrossSize, iconAnchor, infoWindowAnchor, dragCrossAnchor, maxHeight and imageMap.
Default value: none
Unique key to enable the access to the Google Maps API. A different key must be used for each site on which this API is used. The API key may be obtained for free in the Google Maps API signup page.
Default value: none
Format of the template that defines how the map and coordinate text inputs will be presented. There are seven supported place holders for defining how each input and label will be outputted: map, latitude, latitudelabel, longitude, longitudelabel, zoom and maptype.
Default value: "{map}\n<br />\n<div>{latitudelabel} {latitude} {longitudelabel} {longitude}</div>\n{zoom}\n{maptype}"
Initial latitude coordinate value of the selected map location.
Default value: 0.0
CSS stylesheet used to render the latitude text input.
Default value: none
Label for the latitude text input.
Default value: "Latitude:"
CSS style definition used to render the latitude text input.
Default value: none
Initial longitude coordinate value of the selected map location.
Default value: 0.0
CSS stylesheet used to render the longitude text input.
Default value: none
Label for the longitude text input.
Default value: "Longitude:"
CSS style definition used to render the longitude text input.
Default value: none
Type of rendering used to display the map. There are three types of map rendering: Normal for rendering maps as colored polygons, Satellite for display satellite photographs, and Hybrid for rendering roads as polygons over satellite photographs.
Default value: "Normal"
Name of a custom icon to be used as the marker.
Default value: none
Array that defines additional custom markers to display on the map. Each marker is described by an entry of the array. Each marker entry should be an associative array that defines several marker properties. Here follows the list of currently supported marker properties:
Name of the cluster that will aggregate the markers that overlap in the current zoom level for being in the same region.
Default value: none
HTML string that defines the contents of the marker information window. This window opens when the mouse is over the marker.
Default value: none
Name of a custom icon to be used as the marker.
Default value: none
Latitude coordinate value of the marker location.
Default value: none
URL of the page to be opened when the user clicks on the marker icon.
Default value: none
Longitude coordinate value of the marker location.
Default value: none
Title text to associate to the marker. Usually it appears as a tooltip when the mouse is over the marker, like with the HTML TITLE tag.
Default value: none
Name of the window or frame on which the page specified the Link marker property will be opened. If this marker property is not specified, the page will be opened on the same browser window.
Default value: none
Default value: none
Format of the template that defines how the map and coordinate text inputs will be presented when the coordinates are not displyed. There are five supported place holders for defining how each input and label will be outputted: map, latitude, longitude, zoom and maptype.
Default value: "{map}\n{latitude}\n{longitude}\n{zoom}\n{maptype}"
CSS style definition used to render the <div> tag on which the map will appear.
Default value: none
Error message to display when the user enters invalid coordinate values.
Default value: "It was not specified a valid location."
Array that defines the coordinates of a bounding box that must fit in the current map size. The zoom level will be adjusted to assure that the given coordinates will be visible. The array must have the four coordinates of the bounding box: South latitude, East longitude, North latitude and West longitude.
Default value: none
Boolean option that determines whether the zoom level and the map center should be adjusted to fit all the markers on the visible portion of the map.
Default value: none
Level of zoom to display the map. 0 means show the whole world. Higher values make the map display an area closer to the selected location. The maximum accepted zoom level depends on the zone of the world.
Default value: 0
This custom input implements one type of action that can be triggered on the browser side: LocateAddress.
The LocateAddress action is used to send a request to the Google Maps API to find the location of an address. The address value to be located is taken from another form input. If found, the map center and the mark location are set to the coordinates of the located address.
The LocateAddress action supports the context arguments Address, Country and CountryValue.
The Address argument can be used to specify the input from which the address to be located will be taken.
The Country argument can be used to specify an input from which will be taken the name of the country to restrict the search for the address.
The CountryValue is an option that determines how the of the name of the country to be searched will be retrieved from the input specified by the Country option. It can be either Value to use the current input value, or SelectedOption to use the text value of the current option of the country input.
This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.
It uses the PEAR::MDB2 API to execute the SQL queries that retrieve auto-complete texts. PEAR::MDB2 is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.
No longer applies.
Database connection object as returned by the function MDB2::connect. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.
Default value: not set
SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark {BEGINSWITH} to specify where it will be inserted the SQL LIKE pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.
Default value: not set
Maximum number of result entries that will be displayed in the auto-complete menu.
Default value: 10
This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.
It uses the PEAR::MDB2 API to execute the SQL queries that retrieve groups of options. PEAR::MDB2 is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.
No longer applies.
Same meaning but the default value has changed.
Default value: 1
Database connection object as returned by the function MDB2::connect. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.
Default value: not set
SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark ? to specify where the group identifier value should be used.
Default value: not set
Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.
Default value: not set
Text value associated to the option specified by the DefaultOption parameter.
Default value: not set
SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.
Default value: not set
This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.
It uses the Metabase API to execute the SQL queries that retrieve auto-complete texts. Metabase is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.
No longer applies.
Database connection setup handle as returned by the function MetabaseSetupDatabase.
Default value: not set
SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark {BEGINSWITH} to specify where it will be inserted the SQL LIKE pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.
Default value: not set
Maximum number of result entries that will be displayed in the auto-complete menu.
Default value: 10
This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.
It uses the Metabase API to execute the SQL queries that retrieve groups of options. Metabase is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.
No longer applies.
Same meaning but the default value has changed.
Default value: 1
Database connection setup handle as returned by the function MetabaseSetupDatabase.
Default value: not set
SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark ? to specify where the group identifier value should be used.
Default value: not set
Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.
Default value: not set
Text value associated to the option specified by the DefaultOption parameter.
Default value: not set
SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.
Default value: not set
This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a MySQL database rather than from static arrays.
This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.
No longer applies.
Database connection handle as returned by the functions mysql_connect or mysql_pconnect.
Default value: not set
SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark {BEGINSWITH} to specify where it will be inserted the SQL LIKE pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.
Default value: not set
Maximum number of result entries that will be displayed in the auto-complete menu.
Default value: 10
This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.
It uses the PHP MySQL functions directly to execute the SQL queries that retrieve groups of options.
This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.
No longer applies.
Same meaning but the default value has changed.
Default value: 1
Database connection setup handle as returned by the functions mysql_connect or mysql_pconnect.
Default value: not set
SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark {GROUP} to specify where the group identifier value should be used.
Default value: not set
Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.
Default value: not set
Text value associated to the option specified by the DefaultOption parameter.
Default value: not set
SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.
Default value: not set
This custom input provides an alternative to the form_captcha_class plug-in to perform CAPTCHA validation based on Google Recaptcha Web service.
The HTTP client class is necessary to send HTTP requests to the Recaptcha Web services API.
Format of the template that defines how the text input, the image and the control links will be presented. There are seven supported place holders for defining how the input layout will be presented:
image - the validation image
instructions_visual - the label for the text input in image validation mode
instructions_audio - the label for the text input in audio validation mode
refresh_btn - the reload image or replay audio link
audio_challenge - the link to switch to the audio validation mode
visual_challenge - the link to switch to the text validation mode
help_btn - the help link
Default value: "<div>{image}</div> <div>{instructions_visual}{instructions_audio} {input}</div> <div>{refresh_btn} {visual_challenge}{audio_challenge} {help_btn}</div>"
Name of the presentation style class with which the text input field should be rendered.
Default value: not set
List of extra attributes that should be added to the text input HTML tag when the form output is generated.
Default value: not set
Definition of the presentation style attributes with which the text input field should be rendered.
Default value: not set
Order of navigation of the text input field when using the tab key, as defined by the HTML TABINDEX attribute.
Default value: not set
Public key text used to generate the challenge text for validation. It should be obtained from the Google Recaptcha site.
Default value: not set
Private key text used to send the text validation request to the Google Recaptcha API. It should be obtained from the Google Recaptcha site.
Default value: not set
Associative array for the text messages displayed by this custom input.
Here follow the current default text messages:
instructions_visual - 'Enter the words above'
instructions_audio - 'Enter the numbers you hear'
visual_challenge - 'Enter text in an image instead'
audio_challenge - 'Enter numbers you hear instead'
refresh_btn - 'Try another'
help_btn - 'Help'
play_again - 'Play the sound again'
cant_hear_this - 'Download the sound as a MP3 file'
image_alt_text - 'Image with text to enter'
Error message to return when the input value does not match the validation text.
Default value: not set
This custom input type can be used to compose and process forms for manipulating entries of records, stored for instance in databases, by the means of common CRUD actions: Create, Read, Update and Delete.
It can display a listing of entries to be edited with links to edit or delete such entries. An additional link is displayed to let the user create a new entry.
This plug-in class is necessary to interact with the server without page reloading.
This plug-in class is necessary to automatically layout the inputs of the forms for editing or deleting entries.
HTML of the message that should be displayed appended to the status message that reports the result of the current operation.
Default value:
Text for the cancel submit button.
Default value: Cancel
Boolean option to determine whether the plug-in will present a form to create a new entry and a link to start the create form next to the existing entries listing.
Default value: 1
HTML of the message that should be displayed when the new entry creation form was canceled.
Default value: Creating a new entry was canceled.
HTML of the message that should be displayed when a new entry is created successfully.
Default value: A new entry was created successfully.
HTML of the message that should be displayed initially along with the new entry creation form.
Default value: Create a new entry
HTML of the message that should be displayed when showing a preview of a new entry in the creation form.
Default value: New entry preview
Array with entries that define the way each column in the entries listing should be displayed.
Each entry in this array should be set to an associative array that defines the respective column properties.
Default value: array()
Class
CSS class used to display values of the column.
Default value:
Delete
Boolean option to tell whether the column should display a link to start the delete form for the respective row entry.
Default value: 0
Format
HTML template that may define how the column values are displayed.
Default value: use the value directly
FormatMap
Associative array that contains alternative HTML templates that may define how the column values are displayed.
If the current listing value is one the keys of the format map array, the respective array entry is used as template.
Default value: use the value directly
FormatParameters
Associative array that defines how each template placeholder should be replaced.
The keys of the array are the template placeholder marks. The values of the array entries define properties that describe how to generate the values that will replace the placeholders.
Default value: array()
Template placeholder properties
Column
Number of the column from which the default template placeholder value should be retrieved.
Default value: current column number
HTML
Boolean option to tell that the value should be encoded as HTML before displaying.
Default value: 0
InputColumn
Name of a column that will contain the identifier of a previously added input to be displayed in the current placeholder position. If the current listing row does not have set the column defined by this parameter value, the placeholder position will not show any input. Other parameters will display to what will appear in the current placeholder position.
Default value: none
LabelColumn
Name of a column that will contain the identifier of a previously added input whose label should be displayed in the current placeholder position. If the current listing row does not have set the column defined by this parameter value, the placeholder position will not show any label. Other parameters will display to what will appear in the current placeholder position.
Default value: none
Map
Associative array that determines how values should be mapped to alternative HTML representations.
Default value: array()
MapNull
Value to use when the column value is undefined.
Default value:
Replace
Associative array that defines a list of regular expressions that will be used to find and replace column values.
Default value: array()
Header
HTML to display in the header row of the column.
Default value:
HTML
Boolean option to tell that the column value should be encoded as HTML before displaying.
Default value: 0
ID
Boolean option to tell whether the column values have the respective entry identifiers.
Default value: 0
InputColumn
Name of a listing column that will contain the identifier of a previously added input to be displayed in the current column for the current listing row. If the current listing row does not have set the column defined by this parameter value, the current listing entry will not show any input. Other parameters will display to what will appear in the current listing entry.
Default value: none
LabelColumn
Name of a listing column that will contain the identifier of a previously added input whose label should be displayed in the current column for the current listing row. If the current listing row does not have set the column defined by this parameter value, the current listing entry will not show any label. Other parameters will display to what will appear in the current listing entry.
Default value: none
Map
Associative array that determines how values should be mapped to alternative HTML representations.
Default value: array()
MapNull
Value to use when the column value is undefined.
Default value:
Replace
Associative array that defines a list of regular expressions that will be used to find and replace column values.
Default value: array()
Style
CSS style used to display values of the column.
Default value:
Update
Boolean option to tell whether the column should display a link to start the update form for the respective row entry.
Default value: 0
View
Boolean option to tell whether the column should display a link to display an entry.
Default value: 0
Associative array with custom parameters and values that applications need to pass to each page to keep context.
Default value: array()
Boolean option to determine whether the plug-in will present a form to delete existing entries and links in the entries listing to start the delete form to confirm the deletion of the respective entries.
Default value: 1
HTML of the message that should be displayed when an existing entry delete form was canceled.
Default value: Deleting the entry was canceled.
HTML of the message that should be displayed when an existing entry is deleted successfully.
Default value: The entry was deleted successfully.
Array with the definitions of each input that will be used in the forms to delete entries.
Default value: array()
Text for the delete links and submit button.
Default value: Delete
HTML of the message that should be displayed along with the entry delete form.
Default value: Are you sure you want to delete this entry?
Boolean flag that tells whether the user is creating, updating or deleting an entry.
Identifier of the entry to be updated or deleted.
Default value: not defined
Array with the definitions of each input that will be used in the forms to create or update entries.
Default value: array()
Array with the names of the entry fields added to the create or update forms.
Default value: array()
HTML template used to display validation errors. The placeholder {errormessage} should be used to define where the actual validation error message should appear.
Default value: <div style="text-align: center; font-weight: bold">{errormessage}</div>
Name of the CSS class to display the even rows of the entries listing table.
Default value:
Background of the even rows of the entries listing table.
Default value:
Associative array with custom parameters and values that applications need to pass to each page to keep context via in the link URLs only, and so not via hidden form inputs.
Default value: array()
Associative array with layout properties for each of the entry fields. The array entry indexes are the identifiers of the fields. The array entry values are also associative arrays with properties for each field as defined for the form_layout_vertical_class Properties attribute plug-in.
Default value: array()
HTML template used to append to the section with the layout of the forms to create, update and delete entries.
Default value:
HTML template used to prepend to the section with the layout of the forms to create, update and delete entries.
Default value:
Number of the column in the array passed to the Rows property that contains the value of the identifier of each entry to be listed.
Default value:
HTML to mark invalid form fields.
Default value: [X]
Name of the CSS class to use for the table that presents the entries listing.
Default value:
HTML of the message that should be displayed while displaying the entries listing.
Default value:
Padding of cells of the entries listing table.
Default value: 2
Spacing for the entries listing table.
Default value: 0
CSS styles to use for the table that presents the entries listing.
Default value:
Boolean value that sets the loaded state of scaffolding input. The loaded state is changed to 1 during the call to the LoadInputValues function. If it is necessary to load the input values again, set this property to 0 before calling the LoadInputValues function.
Default value: 0
HTML of the message that should be displayed when there are no listing entries to display.
Default value:
Name of the CSS class to display the odd rows of the entries listing table.
Default value:
Background of the odd rows of the entries listing table.
Default value:
Number of the current page of the entries listing to display starting from 1.
Default value: 1
Limit number of entries to display on each page of the entries listing. If set to 0 or there are no more entries in the listing than the page entries value, no pagination navigation is displayed.
Default value: 10
Boolean option to determine whether the plug-in will present a submit button in the entry create or update form to display a preview of the entry next to the form and continue editing it.
Default value: 0
Text for the preview submit button.
Default value: Preview
HTML to display an entry being viewed or the preview of the entry being created or updated.
Default value:
Boolean option to determine whether the plug-in will present the listing of existing entries to be eventually edited or deleted.
Default value: 1
Bidimensional array with data to display in the entries listing.
Default value: array()
Name of a listing column that will contain the name of CSS class that should be used for the respective listing table rows. If the listing column defined by this parameter entry is not defined for the current row, the current row CSS class is not changed.
Default value: none
Name of a listing column that will contain a string with CSS styles definitions that should be used for the respective listing table rows. If the listing column defined by this parameter entry is not defined for the current row, the current row CSS styles are not changed.
Default value: none
Boolean option to determine whether the plug-in will present a submit button in the entry create or update forms to save the entry and continue editing it the entry without exiting the form.
Default value: 0
Text for the save submit button.
Default value: Save
Initial state of the user interface. Currently it supports the following states:
The form to create a new entry was canceled.
A preview of the entry being created is displayed.
The form to create a new entry was submitted.
The form to create a new entry is being displayed.
The form to delete an existing entry was canceled.
The form to delete an existing entry was submitted.
The form to delete an existing entry is being displayed.
The listing of entries is being displayed.
The form to update an existing entry was canceled.
A preview of the entry being updated is displayed.
The form to update an existing entry was submitted.
The form to update an existing entry is being displayed.
A view of a stored entry is displayed.
Default value: listing
Text for the main submit button.
Default value: Submit
Identifier of the input to which the event messages will be forwarded. If this property is not set, the event messages will be queued for retrieval by the application.
Default value: none
Total number of the entries that can be displayed.
Default value: 0
Boolean option to determine whether the plug-in will present a form to update existing entries and links in the entries listing to start the update form to edit the respective entries.
Default value: 1
HTML of the message that should be displayed when an existing entry update form was canceled.
Default value: Updating an entry was canceled.
Name of inputs that should have their values updated during AJAX responses. It can be set several times to specify that different inputs should be updated
Default value: none
HTML of the message that should be displayed when an existing entry is updated successfully.
Default value: The entry was updated successfully.
Text for the update links and submit button.
Default value: Update
HTML of the message that should be displayed along with the entry update form.
Default value: Update this entry
HTML of the message that should be displayed when showing a preview of an existing entry in the update form.
Default value: Updated entry preview
Boolean option to determine whether the plug-in will present pages to display individual entries and links in the entries listing to the entries view page.
Default value: 0
Text for the view links.
Default value: View
HTML of the message that should be displayed along with the view of an entry.
Default value: Viewing entry
The scaffolding custom input can capture interactions with the server regardless of whether the form was submitted to the server in the regular way or through an AJAX request.
When the form is submitted, it posts messages to the application during the call to the LoadInputValues function. The messages describe different types of events that should trigger applications actions for storing and retrieving information to show or manipulate the information of the entries that may be displayed or edited by the application.
The posted messages need to be retrieved using the GetNextMessage function, and replied with ReplyMessage function, so the plug-in can generate the appropriate HTML and Javascript to respond to the form submission requests.
The application may need to set some values in the messages before replying them in order to tell the plug-in what to do next. Consequently, the plug-in may post further messages to the application depending on the previous responses. Therefore, applications must process the messages in a loop until there are no more messages need to be handled.
Currently, it post the following types of messages that correspond to all the possible states of the input:
This type of message is posted when the user clicked on the cancel button while the new entry form was being displayed.
Usually, applications do not need to do anything before replying to this type of message.
This type of message is posted when the user clicked on the preview button while the new entry form is being displayed.
Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should generate HTML to display a preview of the of the entry that is being created and set the EntryOutput property.
This type of message is posted when the user submitted the form to create a new entry.
Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should create the new entry.
The message Entry entry should be set to identifier of the newly created entry before replying to the message.
This type of message is posted when user is editing a new entry, eventually because he clicked on the new entry creation link.
Usually, applications do not need to do anything before replying to this type of message.
This type of message is posted when the user clicked on the cancel button while the delete entry form was being displayed.
The message Entry entry is set to the identifier of the entry to be deleted.
Usually, applications do not need to do anything before replying to this type of message.
This type of message is posted when the user submitted the form to delete an existing entry.
The message Entry entry is set to the identifier of the entry to be deleted.
Applications should call the LoadInputValues and the Validate like with a regular form submission if the delete form had any additional inputs. If the form is valid the application should update the entry records.
This type of message is posted when user is about to delete an existing entry, eventually because he clicked on the delete link of the respective entry in the entries listing.
The message Entry entry is set to the identifier of the entry to be deleted.
Usually, applications do not need to do anything before replying to this type of message.
This type of message is posted when the entries listing needs to be displayed. The application must set the properties TotalEntries, PageEntries, Rows to let the plug-in determine what it should list.
Applications may also set the IDColumn and Columns properties to define the how the listing should be presented, if those properties were not previously defined when the custom input was added.
The message has the Page entry set to the page of the entries listing should be displayed starting from 1.
If it is requested a page that is outside the range of available listing pages, applications may fix the current page to a value within the allowed range by setting the Page property.
This type of message is posted when the user clicked on the cancel button while the update entry form was being displayed.
The message Entry entry is set to the identifier of the entry being edited.
Usually, applications do not need to do anything before replying to this type of message.
This type of message is posted when the user clicked on the preview button while the update entry form is being displayed.
The message Entry entry is set to the identifier of the entry being edited.
Usually applications should do the same when processing create_previewing messages.
This type of message is posted when the user submitted the form to update an existing entry.
The message Entry entry is set to the identifier of the entry being edited.
Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should update the entry records.
This type of message is posted when user is editing an existing entry, eventually because he clicked on the edit link of the respective entry in the entries listing.
The message Entry entry is set to the identifier of the entry being edited.
Applications need to retrieve the values of the entry properties to assign to the respective form inputs that will allow the user to change those entry properties.
This type of message is posted when the user clicked on a link to view an entry.
The message Entry entry is set to the identifier of the entry to be displayed.
Usually applications should do the same when processing update_previewing messages, but display the stored entry values instead.
All the types of posted messages contain certain common entries. These common entries should not be changed by the application.
The Event entry is set to the type of message. The From and ReplyTo entries define the identifier of the custom input that posted the message. The AJAX entry is set when the form was submitted via AJAX.
Besides the types of entries that applications should set when replying to each type of message, applications may also set the Cancel entry to 1 when an error occurred, for instance while trying to update or delete an entry that does not exist, or when creating, updating or deleting an entry failed for some reason.
When there is a validation error, applications do not need to set any special message entries. The plug-in automatically detects and marks inputs that were flagged as invalid during validation.
This input is used to prevent Cross-Site Request Forgery (CSRF) security attacks.
It emulates a common form submit or image input, but has an hidden input attached to it with a validation key that changes every time the form is presented.
When applications query the forms class to check whether the submit input was submitted, it only responds positively if the secret key is correct and it has not expired. Otherwise, this plug-in class pretends the submit input was not clicked.
This approach aims to frustrate CSRF attack attempts to forge a form submission using validation values scrapped from the form HTML page during a previous access.
The class requires the PHP is configured to use the mcrypt library extension to be able to encrypt the validation value.
This custom input plug-in class takes the same properties as the inputs of type submit and image. Additionally, the class also supports the properties below.
If you specify the SRC property, an image input will be added. Otherwise, it will be added an input of type submit.
Number of seconds of the time for which the validation value generated by the class remains valid. It must be a value greater than 0.
Default value: 300
Boolean flag that tells whether the validation value has expired after calling the main forms class WasSubmitted function.
Default value: 0
Private key that is used to encrypt the validation value.
Default value: not set
This custom input type monitors the progress of submission of a form to the server with file inputs. It can provide several statistics to the user to give an idea of how much of the uploading task was done and how much it remains.
The class requires at least PHP 5.2 or an older version patched to provide upload monitor support. Patches are available to provide upload monitor support to older PHP versions.
The class also requires that the current PHP installation has the upload progress extension available. Currently that extension can be obtained from the PECL repository.
The class requires the form AJAX submit custom input plug-in to monitor the upload progress during the form submission. This plug-in is available with the regular forms class distribution.
Identifier of the page element within which the progress bar and other upload statistic details will appear.
Default value: none
String with an HTML template that defines how the progress bar and other details may appear. This plug-in replaces special template marks with upload progress statistic values. Then it updates the page element defined by the FeedbackElement with the resulting HTML data. Here follows the supported template marks:
Percentage of the amount of data uploaded so far. This value is represented as a decimal value.
Average speed of the upload considering the amount of data uploaded so far and the time that elapsed since the beginning of the upload. This value may appear with the suffixes K, M or G to represent speeds in KB/s, MB/s or GB/s if the speed is large enough.
Speed of upload of the last chunk of data that was received. This value may appear with the suffixes K, M or G to represent speeds in KB/s, MB/s or GB/s if the speed is large enough.
Percentage of the amount of data uploaded so far. This value is represented as a rounded integer value.
Expected time remaining till the end of the upload. This value may appear with : within the values of remaining seconds, minutes and hours.
Total amount of data expected to be sent when the upload finishes. This value may appear with the suffixes K, M or G to represent the amount in KB, MB or GB if the amount is large enough.
Amount of data uploaded so far. This value may appear with the suffixes K, M or G to represent the amount in KB, MB or GB if the amount is large enough.
Default value: {PROGRESS}%
Example value: <table style="width: 200px" border="1"><tr> <td style="width: {ACCURATE_PROGRESS}%; border-style: none; background-color: #0000ff; background-image: url(progress.gif); text-align: center;">{PROGRESS}%</td> <td style="border-style: none;"></td> </tr></table>