Author: Manuel Lemos (mlemos-at-acm.org)
Version control: @(#) $Id: forms.documentation,v 1.142 2010/08/01 10:53:29 mlemos Exp $
Contents
"ReplacePatterns"=>array(
/*
* trim whitespace at the beginning of the text value
*/
"^\\s+"=>"",
/*
* trim whitespace at the end of the text value
*/
"\\s+\$"=>"",
/*
* Prepend the text http:// in values that start with www.
*/
"^([wW]{3}.)"=>"http://\\1"
)
ReplacePatternsOnlyOnClientSide
When this option is specified the action of replacing patterns, defined by the ReplacePatterns attribute, is only performed on the client side with the Javascript code generated by the class within the form HTML output.
ReplacePatternsOnlyOnServerSide
When this option is specified the action of replacing patterns, defined by the ReplacePatterns attribute, is only performed on the server side. Therefore, no Javascript code is generated by the class within the form HTML output to perform this action on the client side.
SubForm
Name of the sub-form within which the field is contained. When the user presses a submit button that is contained in a given sub-form, only the values of the fields that belong to that sub-form are subject of validation.
If the submit button that is pressed is not contained in any sub-form or the form is submitted in any way other than using a submit button, the values of all the fields in the form are subject of validation.
TITLE
Input title text as defined for the TITLE attribute of the <INPUT> HTML tag. Usually browsers present this text as tool tip that appears when the user leaves the mouse pointer stopped over the input.
ValidateAsCreditCard
Type argument that indicates that the field value should be validated as a credit card number. Supported types are: amex, carteblanche, dinersclub, discover, enroute, jcb, mastercard and visa.
If the argument is set to unknown, the class will just validate the number by verifying the digit checksum using the MOD10 algorithm and will not perform any extra card type specific verifications. Any spaces, dashes ('-') or dots ('.') within the number digits are ignored.
If the argument is set to field, the class will determine the card type verification to perform according to the value of a given select type field defined by the ValidationCreditCardTypeField argument.
ValidateAsCreditCardErrorMessage
Error message to be used when the field value is meant to contain a credit card number but it is invalid.
ValidateAsDifferentFrom
Name of another field that the field value should be different. This type of validation is useful for password reminder fields where the reminder text should not be the same as the password value.
ValidateAsDifferentFromErrorMessage
Error message to be used when the field value is meant to be different from another given field value but it is not.
ValidateAsDifferentFromText
Text that the field value should be different. This type of validation is useful rejecting the default value of select fields to make the user choose another option explicitly.
ValidateAsDifferentFromTextErrorMessage
Error message to be used when the field value is meant to be different from a given text value but it is not.
ValidateAsEmail
Flag argument that indicates that the field value should be validated as an e-mail address.
ValidateAsEmailErrorMessage
Error message to be used when the field value is meant to contain an e-mail address but it is invalid.
ValidateAsEqualTo
Name of another field that the field value should be equal to. This type of validation is useful for password confirmation fields.
ValidateAsEqualToErrorMessage
Error message to be used when the field value is meant to be equal to another given field value but it is not.
ValidateAsFloat
Flag argument that indicates that the field value should be validated to verify that it contains a valid floating point number.
ValidateAsFloatErrorMessage
Error message to be used when the field value is meant to be a valid floating point number but it is not.
ValidateAsInteger
Flag argument that indicates that the field value should be validated to verify that it contains a valid integer number.
ValidateAsIntegerErrorMessage
Error message to be used when the field value is meant to be a valid integer number but it is not.
ValidateAsNotEmpty
Flag argument that indicates that the field value should not be empty. For file fields, the class also verifies that a valid file was uploaded.
ValidateAsNotEmptyErrorMessage
Error message to be used when the field value is meant to not be empty but it is not.
ValidateAsNotRegularExpression
Parameter that indicates that the field value should be validated to not match the one or more given regular expressions. This parameter value can be a single regular expression string or an array of regular expressions.
ValidateAsNotRegularExpressionErrorMessage
One or more error messages to be used when the field value is meant to not match given regular expressions but it is does. It should be an error message string except when the ValidateAsNotRegularExpression parameter is an array of regular expressions. In that case this parameter should be an array with an equal number of error messages.
ValidateAsSet
Flag argument that indicates that at least one option of a multiple select type field, or one of a radio type field of the same group of the field being defined, or a checkbox should be set.
radio and checkbox fields should be set to the same NAME attribute value to be considered of the same group, but should have different ID attribute values.
checkbox fields of the same group should also be defined setting MULTIPLE attribute to indicate that they belong to a group and at least one of the group fields should be checked.
ValidateAsSetErrorMessage
Error message to be used when on select option or a radio or checkbox field value is meant to be set but it is not.
ValidationErrorMessage
Default error message to be used when no validation type specific message is defined.
ValidateMinimumLength
Integer argument that indicates the minimum length of the field value in number of characters.
ValidateMinimumLengthErrorMessage
Error message to be used when the field value length is less than the specified by the ValidateMinimumLength option.
ValidateOnlyOnClientSide
When this option is specified the validation checks that would be done by the Validate function for this input are not performed.
ValidateOnlyOnServerSide
When this option is specified the validation checks that would be done on the client side by the Javascript code are not performed and the validation code is not generated by the Output function.
ValidateOptionalValue
When this option is specified, it indicates a field value that is accepted without further validation. This option is useful to specify a value that is meant to be always accepted as default even if it does not satisfy any validation conditions.
ValidateRegularExpression
Parameter that indicates that the field value should be validated to match the one or more given regular expressions. This parameter value can be a single regular expression string or an array of regular expressions.
ValidateRegularExpressionErrorMessage
One or more error messages to be used when the field value is meant to match given regular expressions but it is does not. It should be an error message string except when the ValidateRegularExpression parameter is an array of regular expressions. In that case this parameter should be an array with an equal number of error messages.
ValidationClientFunction
Name of a programmer defined Javascript function to be called to validate the field value on the client side. The form field object is passed as argument to that function. It should return true if the field value is valid.
ValidationClientFunctionErrorMessage
Error message to be used when the client side validation function returns false.
ValidationCreditCardTypeField
Name of the select type field that defines the credit card type to be assumed when the ValidationAsCreditCard argument is set to field.
ValidationDecimalPlaces
Maximum number of decimal places to the right of the decimal point that a field validated as floating point may have. If this argument is specified, floating point values with exponents represented in the scientific notation (e.g. 10.3E+11) are no longer accepted as valid.
ValidationLowerLimit
Lower limit value to be accepted when the field is meant to be validated as integer or floating point number. If this argument is not specified, no lower limit checking is done.
ValidationServerFunction
Name of a programmer defined PHP function to be called to validate the field value on the server side. The field value is passed as argument to that function. It should return true if the field value is valid.
ValidationServerFunctionErrorMessage
Error message to be used when the server side validation function returns false.
ValidationUpperLimit
Upper limit value to be accepted when the field is meant to be validated as integer or floating point number. If this argument is not specified, no upper limit checking is done.
Synopsis
$error=$my_form_object->AddHiddenInputs($inputs)
Purpose
Add a set of hidden input fields to the form definition.
Usage
The $inputs argument is an associative array that enumerates a set of input fields that are meant to be added to the form definition as hidden fields. The index of each entry of the $inputs array indicates the name of the input field. The respective array entry value indicates the initial value of the input field.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->AddHiddenInputs($inputs)
Purpose
Add a set of hidden input fields to the output that is generated for the form with the Output method.
Usage
The $inputs argument is an associative array that enumerates a set of input fields that are meant to be added to the form output. The index of each entry of the $inputs array indicates the name of the input field. The respective array entry value indicates a value that the field will be set to, thus overriding its initial value.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->AddInputHiddenPart($input)
Purpose
Add a field input to the output that is generated for the form with the Output method as if it was a hidden field.
Usage
The $input argument is the identifier of the field to be added to the form output.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->AddInputPart($input)
Purpose
Add an input field to the output that is generated for the form with the Output method.
Usage
The $input argument is the identifier of the field to be added to the form output.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->AddInputReadOnlyPart($input)
Purpose
Add a field input to the output that is generated for the form with the Output method in read-only mode. The input is rendered in a way that the user cannot edit it, but its current value is also passed in an hidden input.
Usage
The $input argument is the identifier of the field to be added to the form output.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->AddLabelPart($arguments)
Purpose
Add a label for an input field to the output that is generated for the form with the Output method.
Usage
The $arguments argument is an associative array that takes pairs of tag names and values that define the properties of the label to be added to the form output.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
- ACCESSKEY
Key to be associated as shortcut to activate the given input field for keyboard control as defined for the ACCESSKEY attribute of the <LABEL> HTML 4 tag. Keyboard activation only happens on browsers that fully support the HTML 4 standard. On some platforms the user has to hold the Alt key when the activation key is pressed. This argument may be omitted as long as it was specified when it is defined the input field with the AddInput function.
- CLASS
Name of the presentation style class with which the label should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.
- FOR
Identifier of the input field to which the label is meant to be associated as defined by the ID argument passed when calling the AddInput. That input field has to be added to the form output by calling the AddInputPart either before or after calling this method but always before calling the Output method.
- ExtraAttributes
Associative array with a list of extra attributes that should be added to the label HTML tag when the form output is generated.
- ID
Identifier of the label document element as defined for the ID attribute of the <LABEL> HTML tag.
- LABEL
Data that is outputted as the definition of the label. Usually it is some text eventually with character style HTML markup that is used to denote the access key that is associated with the given input field. This argument may be omitted as long as it was specified when it is defined the input field with the AddInput function.
Notice that the label data is not encoded by this class when it is outputted as part of the form output. Therefore, be careful when using data for the label that is submitted by the user or other untrusted external data source, as it may contain tags that may open the potential security abuse with cross-site scripting exploits.
- STYLE
Definition of the presentation style attributes with which the label should be rendered.
- TITLE
Label title text as defined for the TITLE attribute of the <LABEL> HTML tag. Usually browsers present this text as tool tip that appears when the user leaves the mouse pointer stopped over the label.
Synopsis
$error=$my_form_object->Connect($from, $to, $event, $action, $context)
Purpose
Connect two form inputs in such way that when a given event occurs in the connection origin input on the client side (user browser), it is triggered an action that is executed in the context of the target input.
Usage
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $to argument is the identifier of the connection target input that will execute an action after the trigger event occurs in the origin input.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser). All event types that may be triggered by the base input types are supported. Custom input types may support other types of events.
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input. Currently, several actions are supported by all base input types, except for the hidden type.
The Click action emulates the same effect of an user clicking in the target input. The Focus action gives the focus to the target input. The Select action selects all the text of a text target input. The Enable action enables the target input. The Disable action disables the target input. 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.
Synopsis
$error=$my_form_object->ConnectFormToInput($input, $event, $action, $context)
Purpose
Connect the form to an input in such way that when a given event occurs in the form on the client side (user browser), it is triggered an action that is executed in the context of the target input.
Usage
The $input argument is the identifier of the connection target input that will execute an action after the trigger event occurs in the form.
The $event argument is the name of event that may occur in the form in the client side. Currently, the supported events are: ONSUBMIT for when the form is submitted but before validation or any other action occurs, ONSUBMITTING for when the the form is submitted but after validation or other any actions occurs, ONRESET for when the form is reset, ONLOAD for when the form page is loaded, ONUNLOAD for when the form page is unloaded, and ONERROR when a validation error occurred.
The $action argument is the name of an action that will be executed in the context of the target input after the trigger event occurs in the form. Currently, several actions are supported by all base input types, except for the hidden type.
The Click action emulates the same effect of an user clicking in the target input. The Focus action gives the focus to the target input. The Select action selects all the text of a text target input. The Enable action enables the target input. The Disable action disables the target input. Custom input types may support other types of actions.
The $context argument is an associative array that may pass additional context information to configure details of the action that will be executed. Most actions do not require any additional context information, so the $context argument should be an empty array.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->DisplayOutput()
Purpose
Output the HTML generate for the form.
Usage
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$encoded=$my_form_object->EncodeJavascriptString($string)
Purpose
Encode a string value for use as a string expression in Javascript code.
Usage
The $string argument specifies the string value to be encoded.
The $encoded return value is a string that defines a Javascript string expression that represents the encoded string value.
Synopsis
$error=$my_form_object->EndLayoutCapture()
Purpose
Stop capturing the current script output to compose the form layout.
Usage
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$output=$my_form_object->FetchOutput()
Purpose
Fetch the generated form output into a string.
Usage
The $output return value contains a string that contains the generated form output. If there was an error, an empty string is returned.
Synopsis
$sub_form=$my_form_object->FlagInvalidInput($input, $error)
Purpose
Flag a given input as invalid.
Usage
The $input argument specifies the identifier of the input to be flagged as invalid.
The $error argument specifies the validation error message to associate to the invalid input.
The $sub_form return value is a string of the sub-form that the flagged input belongs.
Synopsis
$name=$my_form_object->GetFileValues($input,$values)
Purpose
Retrieve the values that identify a file uploaded when the form is submitted.
Usage
The $input argument defines the identifier of the file field from which the values are meant to be retrieved.
The $values argument is a reference to an associative array variable that will hold the values that identify the uploaded file. If the file was uploaded successfully, this associative array contains the following entries:
- name - name of the file
- tmp_name - path of a temporary file that holds the file contents.
- type - MIME content type of the file
- size - size of the file
The return value $name contains the name of the file. If the specified input does not exist or if it was not uploaded a valid file, the return value is an empty string.
Synopsis
$input=$my_form_object->GetCheckedRadio($name)
Purpose
Retrieve the form radio input of a given name that is currently checked.
Usage
The $name argument defines the name of the radio inputs that should be looked up to see which one is checked.
The return $input value is a string value that indicates the identifier of the radio input field of the given name that is currently checked. If the specified name does not correspond to an existing field or it is not a radio field or it is but it is not checked, the return value is an empty string.
Synopsis
$value=$my_form_object->GetCheckedRadioValue($name,$default)
Purpose
Retrieve the value of the form radio input of a given name that is currently checked.
Usage
The $name argument defines the name of the radio inputs that should be looked up to see which one is checked.
The $default argument defines the value that should be returned if there is no radio field with the given name that is checked. If this argument is not specified the default value is an empty string.
The return $value value is a string that indicates the value assigned to the radio input field of the given name that is currently checked. If the specified name does not correspond to an existing field or it is not a radio field or it is but it is not checked, the return value is the value passed by to the $default argument.
Synopsis
$checked=$my_form_object->GetCheckedState($input)
Purpose
Retrieve the current checked state of a radio or checkbox input.
Usage
The $input argument defines the identifier of the input to determine its checked state.
The return $checked value is a boolean value that indicates the checked state of the given field. If the specified input does not exist or it is not a radio or a checkbox, the return value is an error string.
Synopsis
$error=$my_form_object->GetContainedInputs($input, $kind, $contained)
Purpose
Retrieve the list of inputs contained within a given input of the form.
Usage
The $input argument is a string that specifies the identifier of the input.
The $kind argument is a string that specifies the kind of contained input to be retrieved. Currently this argument is ignored. Set to an empty string for future compatibility.
The $contained argument is a reference to a variable that will be assigned by this function to an array of identifier strings of the contained inputs.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->GetInputProperty($input, $property, $value)
Purpose
Retrieve the current value of an input field property.
Usage
The $input argument defines the identifier of the field.
The $property argument defines the name of the property of the field to be retrieved. Currently supported properties are:
- ApplicationData
Arbitrary application defined data.
- LABEL
HTML text value of the input label, if set.
- SelectedOption
Value the option of a select input that is currently selected.
- TYPE
Type of the given input.
- ApplicationData
Arbitrary application defined data.
The $value argument should be a reference to a variable that is assigned by the function to the value of the given field property.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$value=$my_form_object->GetInputValue($input)
Purpose
Retrieve the current value that is set to the given field.
Usage
The $input argument defines the identifier of the field from which the value is to be retrieved.
The return $value contains the current value of the given field. If the specified input does not exist, the return value is an error string.
Synopsis
$error=$my_form_object->GetInputEventURL($input, $event, $parameters, $url)
Purpose
Retrieve an URL that can be used on the client side to submit a request to handle a given event to be associated with a give input.
This function is useful to write plug-in classes that implement capabilities of custom inputs that require accessing the server to execute input event handling actions or retrieve information necessary on the client side that is only available on the server side.
For instance, if a custom input needs to present an image that is served dynamically, this function can be used to generate an URL that can be used as the image source. When the browser accesses the URL returned by this function, the form processing script would have to call the HandleEvent method of this class, so the event handling request can be routed to the specified custom input class.
Usage
The $input argument is a string that specifies the identifier of the given custom input field.
The $event argument is a string that specifies the name of the event that is going to be passed to the custom input class so it can execute the corresponding event handling action.
The $parameters argument is an associative array that specifies a list of optional parameters that are going to be passed to the custom input class so it can execute the corresponding event handling action.
The $error return value contains an error message if the function call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$inputs=$my_form_object->GetInputs($parent)
Purpose
Retrieve the list of inputs of the form.
Usage
The $parent argument is a string that specifies the identifier of the parent input when it is intended to retrieve all private inputs managed by a given custom input. Specify an empty string as argument to retrieve all inputs except any managed private inputs.
The $inputs return value is an array with the identifiers of the requested inputs.
Synopsis
$javascript_value=$my_form_object->GetJavascriptCheckedRadioValue($form_object, $name, $default)
Purpose
Generate a Javascript expression that represents the value of the currently checked radio input field with a given name to be used to on client side scripts in Javascript.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the radio input belongs.
The $name argument defines the name of the radio inputs that should be looked up to see which one is checked.
The $default argument defines the value that should be returned if there is no radio field with the given name that is checked. If this argument is not specified, the default value is an empty string.
The $javascript_value return value is a string that represents the value of the checked radio input field in Javascript.
Synopsis
$javascript_value=$my_form_object->GetJavascriptCheckedState($form_object, $input)
Purpose
Generate a Javascript expression that represents the checked state of a given checkbox, radio, or custom input field to be used to on client side scripts in Javascript.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $input argument is a string that specifies the identifier of the given input field.
The $javascript_value return value is a string that represents the given input field checked state in Javascript.
Synopsis
$error=$my_form_object->GetJavascriptConnectionAction($form_object, $from, $to, $event, $action, $context, $javascript)
Purpose
Generate the necessary Javascript code that will be used to implement the action that is executed when the trigger event occurs in a connected input.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs. If this parameter is an empty string, the function will automatically determine the form object expression using either the form NAME or ID class variables, if these variables are not set to empty strings.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $to argument is the identifier of the connection target input on which the event action is executed.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $javascript argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$javascript_object=$my_form_object->GetJavascriptInputObject($form_object, $input)
Purpose
Generate a Javascript expression that represents a given input field as an object to be used to access its variables and functions on client side scripts in Javascript.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $input argument is a string that specifies the identifier of the given input field.
The $javascript_object return value is a string that represents the given input field Javascript object.
Synopsis
$javascript_value=$my_form_object->GetJavascriptInputValue($form_object, $input)
Purpose
Generate a Javascript expression that represents the value of a given input field to be used to on client side scripts in Javascript.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $input argument is a string that specifies the identifier of the given input field.
The $javascript_value return value is a string that represents the given input field value in Javascript.
Synopsis
$javascript=$my_form_object->GetJavascriptSelectedOption($form_object, $input)
Purpose
Generate a Javascript expression that evaluates to the current selected option of a select or custom input field.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $input argument is a string that specifies the identifier of the given input field.
The $javascript return value is a string with Javascript expression of the input selected option.
Synopsis
$javascript=$my_form_object->GetJavascriptSetCheckedState($form_object, $input, $checked)
Purpose
Generate a Javascript expression to set the checked state of a given checkbox, radio, or custom input field.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $input argument is a string that specifies the identifier of the given input field.
The $checked argument is a string that specifies the Javascript expression to set the given input checked state.
The $javascript return value is a string with Javascript statements to set the given input checked state.
Synopsis
$javascript=$my_form_object->GetJavascriptSetFormProperty($form_object, $property, $value)
Purpose
Generate a Javascript expression to assign the value of a form property.
Usage
The $form_object argument is a string that represents the Javascript object of the form.
The $property argument is a string that specifies the name of the form property to be assigned. Currently, only the property SubForm.
The $value argument is a string that specifies the Javascript expression to assign to the given form property.
The $javascript return value is a string with Javascript statements to assign the given form property.
Synopsis
$javascript=$my_form_object->GetJavascriptSetInputProperty($form_object, $input, $property, $value)
Purpose
Generate a Javascript expression to assign the value of a property of a given input field.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $input argument is a string that specifies the identifier of the given input field.
The $property argument is a string that specifies the name of the input property to be assigned. Currently, only the property VALUE is supported for regular input types. Custom inputs may support other properties.
The $value argument is a string that specifies the Javascript expression to assign to the given input property.
The $javascript return value is a string with Javascript statements to assign the given input property.
Synopsis
$javascript=$my_form_object->GetJavascriptSetInputValue($form_object, $input, $value)
Purpose
Generate a Javascript expression to assign the value of a given input field.
Usage
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $input argument is a string that specifies the identifier of the given input field.
The $value argument is a string that specifies the Javascript expression to assign to the given input value.
The $javascript return value is a string with Javascript statements to assign the given input value.
Synopsis
$has_messages=$my_form_object->GetNextMessage($message)
Purpose
Retrieve the next event message pending on the message queue.
Usage
A message describes an event that has occurred on the client side. Usually an event is captured and processed by a custom input class when the HandleEvent function is called.
When the event is not completely handled by the custom input, it may post a message to the form message queue to let the application complete the event handling process.
The message queue may hold multiple messages. The GetNextMessage function should be called to retrieve and reply to the messages until there are no more queued messages.
The $message argument is a reference to an associative array variable that is initialized by this function with the first message pending on the message queue. The variable is not initialized when there are no more queued messages.
The $has_messages return value is a boolean flag that indicates whether there were any queued messages.
Synopsis
$value=$my_form_object->GetSubmittedValue($input)
Purpose
Retrieve the value of a given input that is being submitted.
Usage
The $input argument defines the identifier of the field from which the submitted value is to be retrieved.
The return $value contains the current value of the given field. If the specified input does not exist, the return value is an error string.
Synopsis
$error=$my_form_object->HandleEvent($processed)
Purpose
Handle requests to process events in order to execute an action resulting from a client side user interaction or serve additional information that could not be served when the page with the form was served.
This function is usually necessary to call when there are custom form inputs implemented by plug-in classes that need to interact with the server.
Usage
If the current form has custom inputs, this function should be called right after all form fields are defined and before any form processing functions are called.
This function examines the arguments passed to the current page either via a GET or POST methods to determine whether the current request is for handling an event or for normal form processing.
The $processed argument is used to return a boolean value by reference that is set by this function to indicate whether it is a request for handling an event in case it returns 1, or it is a normal form processing access in case it returns 0.
The $error return value contains an error message if the function call did not succeed. Otherwise it contains an empty string.
If the $processed argument is set to 1, or the $error is set to a non-empty error message string, the current script should exit immediately. Otherwise, the form processing should proceed normally.
This function examines the request arguments with the names defined by the class variables event_parameter and input_parameter to determine if the request is for event handling and which custom form input is expected to handle the event.
Synopsis
$error=$my_form_object->LoadInputValues($submitted)
Purpose
Set the form fields with values passed to the script by the Web server.
Usage
The $submitted argument lets this method know if the script was called to handle a form submitted by the user or the form is just being loaded by the first time, eventually with some initial values defined in the page URL. This argument only affects the interpretation of the values to be loaded in checkbox and multiple select fields.
Note: Currently this method is implemented by loading the field values from the global variables $HTTP_POST_VARS, or from $HTTP_GET_VARS or from the global variables with the same names of the input fields. If you relied on changing the global variables to change the field values that are used by this method, that may not work. Instead, use the SetInputValue method after you call LoadInputValues.
Also, if your PHP configuration has the option magic_quotes_gpc set to On, the LoadInputValues method also tries to strip any ' or \ characters that are added by PHP. This way, the original values submitted with the form are restored. However, that will not fix those values in $HTTP_POST_VARS, $HTTP_GET_VARS or global variables from where the input values are loaded. Use the function GetInputValue to retrieve the fixed values.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->Output($arguments)
Purpose
Generate the output of the form.
Usage
The $arguments argument is an associative array that takes pairs of tag names and values that define options that control the way the form output is generated.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
- EndOfLine
Text data that defines the character sequence that should be used to break the output lines. If this argument is not specified the text lines of the output will not be broken, except for eventual Javascript code that may be generated and the text lines needs to be broken at least with a line feed. A line feed (\n) or character sequence with a carriage return followed by a line feed (\r\n) are usual line breaking sequences in most platforms.
- Function
(required)
Name of the function to be called to output the form data that is generated. The function is usually called multiple times to output the HTML code that defined the form output. The function takes only an argument that is a text string with HTML code.
Synopsis
$my_form_object->OutputDebug($message)
Purpose
Output debugging information using the function specified by the debug variable, if set.
Usage
The $message argument is a message string to pass to the debugging function.
Synopsis
$html=$my_form_object->PageHead()
Purpose
Retrieve the HTML code that is necessary to insert in the page head section to make all the form inputs work correctly.
Usage
This function is usually called when the head section of the form page is being generated. It is necessary to call when using certain types of inputs that need special Javascript code, CSS styles, link or meta tags to be defined in the page head section.
The $html return value contains the necessary HTML tags that should be inserted in the page head section.
Synopsis
$javascript=$my_form_object->PageLoad()
Purpose
Retrieve the Javascript code that is necessary to execute when the page is loaded to make all the form inputs work correctly.
Usage
This function is usually called when the ONLOAD attribute of the page BODY is being defined. It is necessary to call when using certain types of inputs that need special Javascript code to load.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY ONLOAD tag.
Synopsis
$javascript=$my_form_object->PageUnload()
Purpose
Retrieve the Javascript code that is necessary to execute when the page is unloaded to make all the form inputs work correctly.
Usage
This function is usually called when the ONUNLOAD attribute of the page BODY is being defined. It is necessary to call when using certain types of inputs that need special Javascript code to load.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY UNONLOAD tag.
Synopsis
$error=$my_form_object->PostMessage($message)
Purpose
Send a message to the form message queue.
Usage
This function is usually called by custom input classes that handle client side events.
The $message argument is an associative array that describes message. The array may contain some common entries that all event messages have. It may also have some entries that describe event specific details. Here follows a list of common entries:
Event
Name of the event associated to this message.
From
Identifier of the input that is posting the message.
ReplyTo
Identifier of the input that should handle the reply to the message.
Target
Identifier of the input that should handle the message. The target input should be a custom input that implements the PostMessage function. If this entry is missing, the message should be handled by the application using the GetNextMessage function.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->RemoveFunction($name)
Purpose
Remove a previously added function from the form output to be generated by the Output method.
Usage
The $name argument is the name of the function to be removed from the form output.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->ReplyMessage($message, $processed)
Purpose
Send a reply to the message retrieved from the form message queue.
Usage
This function should be called after processing a client side event message retrieved with the GetNextMessage function.
The $message argument is the same associative array of the message retrieved with the GetNextMessage function. It may contain new or altered entries to specify details that may trigger different actions when the message reply is processed.
The $processed argument is used to return a boolean value by reference that is set by this function to indicate whether the response to the current request is finished when it returns 1, or the script may continue with normal form processing in case it returns 0.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$my_form_object->ResetFormParts()
Purpose
Reset the definition of the form output as it is initially when the form object is created.
Synopsis
$radio=$my_form_object->SetCheckedRadio($name, $value)
Purpose
Set the current checked state of all radio inputs of a given name.
Usage
The $name argument defines the name of all the radio inputs to check or uncheck.
The $value argument is the value of the radio input that should be checked. All the other radio inputs with the same name that have a different value will be unchecked.
The $radio return value contains the identifier of the radio button that was checked. An empty string is returned if no radio input was found with the given name and value.
Synopsis
$error=$my_form_object->SetCheckedState($input,$checked)
Purpose
Set the current checked state of a radio or checkbox input.
Usage
The $input argument defines the identifier of the input to be set.
The $checked argument is a boolean value that specifies whether the given input is going to be checked or unchecked.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->SetInputProperty($input, $property, $value)
Purpose
Redefine the current value of an input field property.
Usage
The $input argument defines the identifier of the field to be set.
The $property argument defines the name of the property of the field to be redefined. Currently supported properties are:
- ACCEPT
- ALT
- COLS
- LABEL
- MAXLENGTH
- ONBLUR
- ONCHANGE
- ONCLICK
- ONDBLCLICK
- ONFOCUS
- ONKEYDOWN
- ONKEYPRESS
- ONKEYUP
- ONMOUSEDOWN
- ONMOUSEMOVE
- ONMOUSEOUT
- ONMOUSEOVER
- ONMOUSEUP
- ONSELECT
- ROWS
- SIZE
- SRC
- TABINDEX
- Accessible
- ApplicationData
- Capitalization
- ClientScript
- Content
- ReadOnlyMark
- ReadOnlyMarkUnchecked
- SubForm
- VALUE
- ValidationServerFunctionErrorMessage
- STYLE
- CLASS
The $value argument defines the value to be assigned to the given field property.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->SetInputValue($input,$value)
Purpose
Redefine the current value of an input field.
Usage
The $input argument defines the identifier of the field to be set.
The $value argument defines the value to be assigned to the given field.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->SetSelectOptions($input, $options, $selected)
Purpose
Set the list of options and selected values of a select type input.
Usage
The $input argument defines the identifier of the select input to be set.
The $options argument is an associative array that defines the list of options, like for the OPTIONS argument passed to AddInput function.
The $selected argument is array that defines the values of the list of options that should be selected, like for the SELECTED argument passed to AddInput function. For non MULTIPLE select inputs, it should be passed an array with a single value of the option to be selected.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error=$my_form_object->StartLayoutCapture()
Purpose
Start capturing the current script output to compose the form layout.
Usage
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$error_message=$my_form_object->Validate($verify,$sub_form)
Purpose
Determine if the values set in the form input fields are valid.
The validation of each input is performed according to the respective definition that was passed to the AddInput function. The order of the validation types is as follows:
- ValidateAsNotEmpty
- ValidateAsDifferentFromText
- ValidateMinimumLength
- ValidateRegularExpression
- ValidateAsNotRegularExpression
- ValidateAsInteger
- ValidateAsFloat
- ValidateAsEmail
- ValidateAsCreditCard
- ValidateAsEqualTo
- ValidateAsDifferentFrom
- ValidateAsSet
- ValidationServerFunction
As a side note, the order of the client side validation types implemented by the Javascript code generated by the class is the same, except that, obviously, the ValidationClientFunction validation will be performed instead of ValidationServerFunction.
Usage
The $verify argument is an associative array that should be passed by reference to return the identifiers of the fields that are set with invalid values. The index of each entry in the array is the respective invalid field identifier. The value of each entry is set with the field sub-form name.
The $sub_form argument is the name of the sub-form to which the validation should be restricted. If this argument is an empty string, all fields in the form are validated. Otherwise, only the fields with the same sub-form name are validated.
The $error_message return value contains the error message defined for the first invalid field that was found. If all fields are set with valid values, the function returns an empty string.
Synopsis
$submitted_input=$my_form_object->WasSubmitted($input)
Purpose
Determine if a form was submitted by a given input field.
Usage
The $input argument specifies the identifier of the input field that this method should verify whether it was used to submit the form.
The $submitted_input return value contains the identifier of the field that was used to submit the form. If the $input argument is not an empty string and the field was not used to submit the form, the method returns an empty string.
Usually the specified input is of type submit or image, but if it is specified a field of another type the method just verifies if the respective input value was passed when the form was submitted. So, it is ok to specify for instance a dummy hidden that will only act as a flag to determine if the form was submitted or is meant to be displayed for the first time.
If the $input argument is an empty string the method tries to find whether any submit or image field was used to submit the form and returns its name. If no field was found, the method returns an empty string.
Whenever possible it is recommended to specify the name of an actual field because it takes less time to verify only one field than traversing the whole list of fields of the form.
Properties
- ACTION
URL of the resource (Web page script) that is meant to handle the form submission as defined for the ACTION attribute of the <FORM> HTML tag.
Usually, Web developers define a form in with page script and process it with another. However, since you always have to create the same object to output the HTML code to display the form and validate it, it is convenient to use the same script handle both circumstances. Doing this is also convenient to handle the situation where you need to redisplay the form because some fields where submitted with invalid values.
One simple way to define the ACTION property to make the form be handled by the same script is to set it with an empty string or with ? if you want to avoid passing forward any parameters previously passed with the current page URL.
Default value: ""
- ENCTYPE
MIME Content type of the data that is sent when the form is submitted as defined for the ENCTYPE attribute of the <FORM> HTML tag.
This property only applies when the data is submitted using the POST method. If no encoding type is specified, the browsers use the MIME type application/x-form-urlencoded. If the form includes file input fields, the class uses the MIME type multipart/form-data automatically.
Default value: ""
- ID
Identifier of the form document element as defined for the ID attribute of the <FORM> HTML tag.
Default value: ""
- METHOD
Method that is used to submit the form as defined for the METHOD attribute of the <FORM> HTML tag.
The method that is recommended to be used is POST, but if the amount of information to be submitted to the server between form field names and values is very small (less than 255 characters) the method GET may be used.
If the form being submitted has file inputs, the POST method is used automatically.
Default value: ""
- NAME
Name of the form as defined for the NAME attribute of the <FORM> HTML tag. This property must be set to non-empty string if the Output method needs to generate Javascript code for functions that manipulate the fields added to the form output. This is the case when a field requires client side validation or a function is added to execute an action associated to a given input field.
Default value: ""
- ONERROR
Client side script commands to execute when the form is submitted but has validation errors.
The script may use several variables that are initialized with values related with the validation errors. The form variable is a reference to the form object. The error_message variable is a string with all the errors to be displayed. The Invalid variable is an object whose member names are the fields that failed validation rules. The member values are the respective input error messages.
Default value: ""
- ONSUBMIT
Client side script commands to execute when the form is submitted as defined for the ONSUBMIT attribute of the <FORM> HTML tag.
Any commands specified by this property are executed before executing the client side validation code generated by the class Output method.
Default value: ""
- ONSUBMITTING
Client side script commands to execute when the form is submitted as defined for the ONSUBMIT attribute of the <FORM> HTML tag.
Any commands specified by this property are executed after executing the client side validation code generated by the class Output method. If there are any fields with invalid values, the commands specified by this property are not executed.
Default value: ""
- ONRESET
Client side script commands to execute when the form is reseted as defined for the ONRESET attribute of the <FORM> HTML tag.
Any commands specified by this property are executed before executing the client side validation code generated by the class Output method.
Default value: ""
- TARGET
Name of the Web browser frame on which the results of the form submission are meant to be displayed as defined for the ACTION attribute of the <FORM> HTML tag.
If this property is set to an empty string, the results of the form submission are displayed in the same browser frame as the one on which the form is displayed.
Default value: ""
- error
Some functions return an error message when they fail. This message is also stored in the error property so it can be checked later. This avoids the need to check those functions return value immediately after they are called to determine if they succeeded.
The class functions never reset the value of this property. Therefore its value is overwritten by the last function call that fails.
Default value: ""
- Changes
Associative array that enumerates the form fields that had their values changed after calling the function LoadInputValues. This variable may be used to determine which fields the user has changed before submitting the form. The loaded values are compared against the initial values of the fields as they were set with AddInput and SetInputValue functions.
The indexes of the entries of the array are set to the identifier names of the changed fields. The entry values are set to the values that the respective fields had before calling the LoadInputValues function.
Entries for radio and checkbox are set to an empty string if their prior state was not CHECKED. Entries for MULTIPLE select fields are set to an associative array that enumerates the values that changed in the selection list. The respective values are set to 0 for entries that were deselected and 1 for entries that were selected.
Default value: empty array
- DisableReadOnlyInputs
Boolean flag that determines if the form inputs in read-only mode should be outputted as normal inputs with the DISABLED HTML attribute, or otherwise, as formatted text that represents the the input value.
Default value: 0
- ExtraAttributes
List of extra attributes that should be added to the form's HTML tag when the form output is generated. The list should be defined as an associative array with the attribute names as array entry indexes and the attribute values as array entry values.
Default value: array()
- Invalid
Associative array that enumerates the form fields that have invalid values after calling the function Validate.
The indexes of the entries of the array are set to the identifier names of the invalid fields. The entry values are set to the error messages associated to the first validation rule that the respective fields do not satisfy.
If the Validate function is called passing a specific sub-form name, only the fields that belong to that sub-form are considered.
The Validate function resets the Invalid variable before it starts validating the fields. The information about any fields considered invalid in previous Validate function calls is lost.
Default value: empty array
- InvalidCLASS
Name of the default CSS class used to render invalid fields.
When set to a non-empty string, the specified value replaces the default CSS class attribute of the invalid fields listed in the Invalid forms class variable.
The specified CSS class name is also used to replace invalid fields' CSS class, when the form is validated on the client side using Javascript.
The value of the forms class InvalidCLASS variable can be overriden for fields defined with its own InvalidCLASS argument.
Default value: ""
- InvalidSTYLE
Default CSS style attributes used to render invalid fields.
When set to a non-empty string, the specified styles are merged with the default CSS style attributes of the invalid fields listed in the Invalid forms class variable.
The specified CSS attributes are also used to replace invalid fields' CSS attributes, when the form is validated on the client side using Javascript.
The value of the forms class InvalidSTYLE variable can be overriden for fields defined with its own InvalidSTYLE argument.
Default value: ""
- OptionsSeparator
String that is used to separate the values of MULTIPLE select fields when the form is outputted in ReadOnly mode.
Default value: "\n"
- OutputPasswordValues
Boolean flag that determines if the form password fields values should be outputted with the respective field <input> tags.
For security reasons it is recommended to keep this flag set to 0. If a page with a form with a password field set to some value is cached when this flag is set to 1, somebody with access to the machine of the user browser may recover the password from the page cache file.
If you absolutely need to set this flag to 1, make sure you use the appropriate page headers to tell the user browsers to not cache the pages.
Default value: 0
- ReadOnly
Boolean flag that determines if the form should be outputted as if the fields were set to a read-only mode. If this flag is set to 1 fields are outputted as text that represents their current state and values.
This flag must be set before starting defining the form output adding input parts. The read-only mode may be overridden individually for each input field using the Accessible property. Form output field parts added as hidden parts with the AddHiddenInputsParts function are always outputted as hidden input fields regardless of the value of the form ReadOnly flag and the input Accessible property.
Default value: 0
- ResubmitConfirmMessage
Message to display when the user attempts to submit the same form more than once without waiting for the submission results to be displayed. This property may be used to prevent users from submitting the form multiple times inadvertently.
When the user attempts to submit the form again a confirmation requester is shown displaying the message defined by this property if it is set to a non-empty string. If this property is not set, the user is not stopped from submitting the form multiple times.
Default value: ""
Options
Options are special properties that only need to be changed in particular circumstances. Their default values are appropriate for normal operation.
- ErrorMessagePrefix
Text to prepend to the error messages that are displayed or returned when invalid inputs are found.
Default value: ""
- ErrorMessageSuffix
Text to append to the error messages that are displayed or returned when invalid inputs are found.
Default value: ""
- ShowAlertOnError
Boolean flag that determines whether an alert message box should be used to display error messages when client side validation fails.
Set this option to 0 if you want to implement custom client side error message displaying overriding the default alert message box.
Default value: 1
- ShowAllErrors
Boolean flag that determines whether after the form validation the class should show error messages associated to all invalid inputs or just the first invalid input.
This option affects the error messages shown in the error alert window displayed by the browser when a form with invalid inputs is submitted. It also affects the return value of the Validate function.
Multiple error messages are split by the end of line character sequence defined by the end_of_line.
Default value: 0
- ValidateAsCreditCard
Name of the client side credit card number validation function that the Output method generates. Change this option only when you need to output more than one form with fields that require credit card number validation to avoid function name collision.
Default value: "ValidateCreditCard"
- ValidateAsEmail
Name of the client side e-mail address validation function that the Output method generates. Change this option only when you need to output more than one form with fields that require e-mail address validation to avoid function name collision.
Default value: "ValidateEmail"
- ValidationErrorFunctionName
Name of a client side validation function that the Output method generates. This function is called when the form is submitted but has validation errors. Change this option only when you need to output more than one form with fields that require client side validation to avoid function name collision.
Default value: "ValidationError"
- ValidationFunctionName
Name of the client side validation function that the Output method generates. This function is called when the form is submitted. Change this option only when you need to output more than one form with fields that require client side validation to avoid function name collision.
Default value: "ValidateForm"
- accessibility_tab_index
Name of the global function that is called to determine the number that should be assigned to the TABINDEX attribute the corresponding form field <INPUT> HTML tag. If the field does not have the TABINDEX attribute set and this option is set to a non-empty string the specified function is called passing the identifier of each input field as argument. The return value is assigned to the respective TABINDEX attribute.
Default value: ""
- debug
Name of the global function that is called when one of the methods of the class fails due to invalid arguments. The error message is passed to the debug function right before returning from the failing method call. Change this option when you need to debug the code that uses the class to determine if is there any method call that is failing.
Default value: ""
- decimal_regular_expression
Regular expression that is used to fields set with the option ValidateAsFloat and ValidationDecimalPlaces. The word PLACES in this variable value will be replaced by the value of the ValidationDecimalPlaces option.
Default value: "^-?[0-9]+(\\.[0-9]{0,PLACES})?\$"
- event_parameter
Name of the parameter that is used to pass the name of the event that is passed by custom inputs in requests to handle events on the server side by the respective custom input classes.
The value of this option is use by the GetInputEventURL function to form an event handling URL.
Default value: "___event"
- email_regular_expression
Regular expression that is used to validate an e-mail address text field.
Default value: "^([-!#\$%&'*+./0-9=?A-Z^_`a-z{|}~])+@([-!#\$%&'*+/0-9=?A-Z^_`a-z{|}~]+\\.)+[a-zA-Z]{2,6}\$"
- encoding
Type of encoding that is used in the HTML document within which the form is integrated. This option determines how 8 bit characters are encoded. Currently, only iso-8859-1 (ISO Latin 1) encoding is supported. Change this option if your HTML document uses any other type of encoding. If you specify a different encoding, only <, > and " characters are encoded.
Default value: "iso-8859-1"
- end_of_line
Sequence of characters that will be used to break the lines of the generated Javascript code.
Default value: \n
- float_regular_expression
Regular expression that is used to fields set with the option ValidateAsFloat but not with the option ValidationDecimalPlaces.
Default value: "^-?[0-9]+(\\.[0-9]*)?([Ee][+-]?[0-9]+)?\$"
- form_submitted_test_variable_name
Name of the client side global variable that it is used to store temporary information of whether there was a previous attempt to submit a form by the time the form is being submitted. Change this option if the default value defines a name that collides with global variables unrelated with the client side code generated by this class.
Default value: "form_submitted_test"
- form_submitted_variable_name
Name of the client side global variable that it is used to store the information of whether the form was already submitted by the user. Change this option if the default value defines a name that collides with global variables unrelated with the client side code generated by this class.
Default value: "form_submitted"
- input_parameter
Name of the parameter that is used to pass the identifier of a custom input field in requests to handle events on the server side by the respective custom input classes.
The value of this option is use by the GetInputEventURL function to form an event handling URL.
Default value: "___input"
- sub_form_variable_name
Name of the client side global variable that it is used to store the sub-form name corresponding to the submit button that was used to submit the form. Change this option if the default value defines a name that collides with global variables unrelated with the client side code generated by this class.
Default value: "sub_form"
- tolower_function
Name of the function to be called to convert a text string to lower case. This function is used when the Capitalization attribute of a text field is set to lowercase. Change this option when you can not guarantee that the system locale support is able to do case conversion of non-ASCII characters like those with accents and cedillas.
Default value: "strtolower"
- toupper_function
Name of the function to be called to convert a text string to upper case. This function is used when the Capitalization attribute of a text field is set to uppercase. Change this option when you can not guarantee that the system locale support is able to do case conversion of non-ASCII characters like those with accents and cedillas.
Default value: "strtoupper"
Functions
- FormCaptureOutput
Synopsis
$output=FormCaptureOutput($form,$arguments)
Purpose
Capture the output of a form object in a result text string.
Usage
The $form argument is a reference to an object created by this class. Make sure you pass the form object argument by reference to prevent inadvertent object replication when passing by value.
The $arguments argument is an associative array that takes pairs of tag names and values as defined for the class Output method. The Function argument is overridden by a custom global function that does the output capture.
The $output return value contains the form HTML output if the function call succeed. Otherwise it contains an empty string.
Template processing
- Separating presentation from logic
To compose the layout of a form, the class needs to be called alternating HTML data definitions using AddInputPart calls and input field or label placements. However, this does not help the work of Web developers and designers because HTML code produced by the Web designer needs to be mixed with the programming of the developers, making the work of both harder to conceal and maintain.
To help solving this problem, a template engine could be used to separate the presentation work files from the programming logic work files. Currently there are two supported solutions to use templates to compose the output of forms: using plain HTML template files with embedded PHP commands to place the form inputs and labels, or using the Smarty template engine with a special plug-in to capture the template processing.
- Plain HTML template files with embedded PHP code
PHP itself is already a template language. Since this form class needs to know in advance all the HTML data that will make part of the output and where the form inputs are located, the form layout HTML data needs to be added with the AddDataPart function before generating the whole form output.
An alternative way of defining the layout HTML data for the form output composition is to use PHP script output capturing support available since version 4.
This class is capable of capturing the current PHP script output by calling the function StartLayoutCapture. After calling this function and until the EndLayoutCapture function is called, all the script output is captured to compose the form output.
Plain HTML template files can be used to define the form layout by using the PHP include command. Just place PHP code sections in the points of the HTML template where the inputs and their labels will appear, using the class functions like AddInputPart and AddLabelPart. Here follows an example:
File: my_form_script.php
<?php
$form=new form_class;
$form->AddInput(array(
"NAME"=>"user_name",
"TYPE"=>"text",
"ValidateAsNotEmpty"=>1,
"ValidationErrorMessage"=>"You have not specified the user name"
));
$form->AddInput(array(
"NAME"=>"password",
"TYPE"=>"text",
"ValidateAsNotEmpty"=>1,
"ValidationErrorMessage"=>"You have not specified the password"
));
$form->AddInput(array(
"ID"=>"submit",
"TYPE"=>"submit"
));
$form->StartLayoutCapture();
include("my_form_template.html.php");
$form->EndLayoutCapture();
$form->DisplayOutput();
?>
File: my_form_template.html.php
<table>
<tr>
<th><?php
$form->AddLabelPart(array(
"FOR"=>"user_name",
"LABEL"=>"<u>U</u>ser name",
"ACCESSKEY"=>"U"
));
?>:</th>
<td><?php $form->AddInputPart("user_name"); ?></td>
</tr>
<tr>
<th><?php
$form->AddLabelPart(array(
"FOR"=>"password",
"LABEL"=>"<u>P</u>assword",
"ACCESSKEY"=>"P"
));
?>:</th>
<td><?php $form->AddInputPart("password"); ?></td>
</tr>
<tr>
<td colspan="2"><?php $form->AddInputPart("submit"); ?></td>
</tr>
</table>
Smarty template engine
One of the most popular template engines for PHP is Smarty. It generates PHP scripts that merge the HTML data from templates with the commands of code that execute actions and produce dynamically generated data. Once these scripts are generated, they do not need to be updated as long as the template files are not changed.
Given that even with the generation of processed templates in the form of PHP scripts that are cache, this solution is usually faster than most alternative template engines. However, keep in mind in the end you still need to load a large class that is the Smarty execution engine besides the compiled template script. So, the consumption of CPU and memory resources often is not negligible.
Smarty plug-in filter for form composition
Since the flexibility that is earned by separating presentation from logic motivates many developers to use Smarty, along with this forms class it is provided a plug-in pre-filter function that can be used with the Smarty engine to compose the forms presentation using templates.
The plug-in function is provided in a PHP include file named prefilter.form.php. Currently there are two versions of the plug-in, one for Smarty 2 and another for Smarty 3.
There is also an example form handling script named test_smarty_form.php that uses Smarty 2 with this plug-in function. The version for Smarty 3 is named test_smarty3_form.php. These scripts use a template file named form.tpl that contains the layout of the form defined in HTML.
Besides the HTML markup and the Smarty commands, the form template files may have special place holder marks that define where the form fields will be placed. Currently only three types of marks are supported: {input name="input"}, {hiddeninput name="input"} and {label for="input"}. If you changed Smarty mark left and right delimiters to other characters besides { and }, the form input and label marks must use those other delimiter characters.
The {input} mark specifies an input to be added to the form as it would be added with the AddInputPart. The {hiddeninput} mark specifies an input to be added to the form as a hidden input as it would be added with the AddInputHiddenPart. The {label} mark specifies where a label of a specified input to be added to the form as it would be added with the AddLabelPart.
The current version of this plug-in makes Smarty generate processed template scripts that refer to the object of the forms class referring to a global variable named $form. Make sure your forms class object is assigned to this global variable.
Enhancing forms with custom input type plug-ins
The forms class provides support for using custom form input types that can implement enhanced functionality over the basic HTML form input types.
The custom input types can provide support for sophisticated form handling features, like for instance, managing complex inputs made of several tightly coupled inputs, or providing enhanced usability by the means of special Javascript event handlers that can make the forms more interactive, thus avoiding long delays that make the user wait for needless Web server access round trips to perform special types of manipulation of the input values.
New custom form input types can be implemented by the means of separate plug-in classes, that can provide new form input functionality without requiring the developers to change the code of the main forms class.
Any developer can create new custom form input plug-in classes. Such classes may be distributed with their own license. Since the license of the main forms class is BSD like, it allows unrestricted distribution including of dependent components. So, the license of a plug-in class may be proprietary and it may even be distributed in a closed source format as a commercial product.
- Custom input classes
A form input of a custom type is used very much like the regular types of input. It should be defined also using the forms class function AddInput. The main difference is that you need to specify the name of the class of the custom input using the CustomClass parameter of the AddInput function.
All custom input classes have a common API that is used by the main forms class to provide the custom behavior. New custom input classes should extend the form_custom_class. This class is defined in the forms.php file right before the main forms class.
The form_custom_class base class provides default behavior for all custom input classes by the means of several functions and variables. Some of those functions and variables have necessarily to be reimplemented in the custom input classes. The other functions and variables may be redefined only when necessary.
- Basic steps for developing new custom input classes
If you are interested in developing a new custom input class, here follows a list of common steps that you should take:
- Create a new custom input class
A new custom custom input class should be created by extending the form_custom_class base class. This base class provides default behavior that reduces significantly the effort that is necessary to implement a new custom input.
- Implement the input initialization
The most important function of a custom input class is the AddInput function. It should check the parameter arguments passed to the function and initialize the class variables according to the needs.
If the new custom input is intended to manage a set of one or more new inputs, the AddInput function is the place where such inputs should be defined by using the main forms class AddInput function. Use the GenerateInputID function to create unique identifiers for those new inputs.
If the class is supposed to benefit from the automatic support for rendering from format templates, it should initialize the format and valid_marks class variables using the ParseNewInputFormat function.
This will let the class benefit from inheriting several functions from the base class without having to reimplement them like AddInputPart, AddHiddenInputPart, AddLabelPart and AddFunction.
- Define the page head section or the load and unload events
Some inputs may need to load Javascript code, CSS styles or page meta tags that need to be inserted in the page head section, thus outside the form tags. If the new custom input needs this, it must implement the PageHead function.
If the custom input needs to define head tags only once, even when the form has multiple custom inputs of the same class, the ClassPageHead function should be implemented to define such tags.
Additionally, if it needs to execute Javascript code during the page load or unload events, it must implement the PageLoad or PageUnload functions respectively.
- Retrieve input values
If the new custom input will have an associated input value that can be set or changed by the user, implement the GetInputValue function to provide a means for the applications that use the new form custom input to retrieve its current value.
Also, if the new custom input will emulate the behavior of a checkbox or radio, implement the GetCheckedState function to provide a means for the applications that use the new form custom input to retrieve its checked state.
- Setting properties
If there are any properties that can be changed by the applications after the custom input is added to the form, implement the SetInputProperty function to handle property change requests, including for the main input VALUE property if supported.
Also, if the new custom input will emulate the behavior of a checkbox or radio, implement the SetCheckedState function to provide a means for the applications that use the new form custom input to change its checked state.
- Validate input values
If the custom input value has to be validated according to specific rules, implement the ValidateInput function to enforce such rules. Make sure it is possible to configure details of such validation rules with either the AddInput or SetInputProperty functions, including the text to present to the user every time a rule is not satisfied. If the custom input does not need to perform server side validation, set the server_validate variable needs to be set to 1. In this case, the ValidateInput function does not need to be redefined.
If possible implement the GetJavascriptValidations function to specify the Javascript code and other details that will be used to enforce some or all of the types of validation rules on the client side. This helps improving the usability of the forms that use the new custom input. If the custom input needs to perform client side validation, make sure you set the client_validate variable to 1.
If the custom input is expected to be managed by another custom input, implement GetJavascriptInputValue function to make possible for the manager input to retrieve the custom input value on the client side with Javascript and perform any special type of validation or manipulation.
- Load submitted input values
If the custom input class needs to perform some special action like updating its internal state values when the form values are loaded, implement the LoadInputValues function to define how to execute such special action.
- Connecting inputs to trigger special actions upon client side events
In certain circumstances it may be useful to connect two or more inputs in such way that when a client side (user browser) event occurs in the context of a given input, it triggers the execution of actions in the context of other inputs.
For instance, when updating the quantity of a product in an order form, it would be useful to immediately update another field that shows the total value of the order.
This can be achieved using the Connect function. It associates a client side event in the origin input to an action that is executed in the context of a target input.
The base input types support a limited number of events and actions. New custom input classes can be developed to support more events and actions. Such custom input classes need to implement the Connect to handle new events and GetJavascriptConnectionAction to generate the necessary Javascript code that implements new actions.
- Registering custom client side input events
The base custom input class provides means to automatically register custom input events.
An application just calls the Connect function to trigger the execution of an action on the context of a given input when the event occurs.
The base class implementation of that function registers the details of the event connection. The connections class variable is updated to keep event connection information. The Connect function only accepts registrations of connections for events with an entry already initialized in the connections variable.
When a custom input class needs to generate the Javascript code to execute the registered actions that handle the custom event, it just needs to call the base class GetEventActions function.
That function returns the Javascript code for the actions associated to the registered event connections. The actions Javascript code also includes the value for the respective event default action set in the events class variable.
- Handling client side events on the server side
In certain circumstances a custom input may need to execute actions on the server side to handle special user interaction events.
This is the case, for instance, of highly interactive inputs that may communicate with the server using special purpose Javascript to pass request parameters to the server side in order to execute actions or retrieve information necessary to update their client side state or details of its presentation in the user browser.
In other circumstances a custom input may need to serve dynamically generated information to the browser that cannot be served when the form HTML is generated, like for instance, to present images with graphics generated dynamically.
In either case, these interactions with custom input on the client side and the respective custom input class, can be implemented with the HandleEvent function.
The HandleEvent class function examines the request parameters to determine which custom input is responsible for processing the request. Then it calls the HandleEvent function of the respective custom input class passing the name of the event and any additional parameters that may have been passed to the request.
A custom input class that expects to process event handling requests should execute the necessary actions and eventually server HTTP response headers and body that the browser will use to complete the interaction.
- Forward client side events to custom inputs
A custom input may forward the request to handle an event received by the HandleEvent function. This may be useful to delegate the response of a client side event to a child input.
The class of the custom input receiving a event handling request just needs to call the PostMessage function of the main forms class, setting the message Target parameter to the identifier of the input to which the event should be forwarded. An input receiving a forwarded message must implement the PostMessage function.
- Emulating form submit inputs
A custom input may emulate form submit inputs to provide additional behaviour. In that case, an input emulating form submit inputs may implement the WasSubmitted function.
The following sections provide detailed information on all the custom input public class functions and variables that are inherited from the custom input base class and can be reimplemented in new custom input classes.
- Class variables
- children
Array that stores the names of all the children inputs that have has parent the current custom input.
This variable is updated by the AddChild function and should not be redefined by the custom input class.
Default value: array()
- client_validate
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
- connections
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()
)
- events
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
Format of an HTML template that defines how the custom input will be rendered. This format template is used by the AddInputPart function of the custom input base class to implement the default rendering method.
The syntax of the template consists of arbitrary HTML with special marks that define the position of place holder marks. These marks can appear in any position the format template value.
The special marks start and end with characters defined by the mark_start and mark_end respectively. The text value between the start and end marks defines the mark name.
The meaning of the mark name is defined by the valid_marks variable. Usually it specifies that the mark corresponds to one of several input fields that are managed by the custom input.
This variable should be redefined by the custom input class if it is intended to use the default rendering method provided by the custom input base class.
Default value: ""
Example value: "{day}/{month}/{year}"
- focus_input
Identifier of the default input that is meant to get the input focus. That input may get the focus when:
- A function of type focus or select_focus defined with AddFunction function is called.
- The user clicks on the label associated with the input field using the AddLabelPart function.
- The input has an invalid value when the user submits the form.
If this variable is set to an empty string, no input will get the focus.
This variable should be redefined by the custom input class if it is intended to use the automatic focus input association by the custom input base class.
Default value: ""
Example value: "date_day"
- input
Identifier name of the current custom input. This is set by the main forms class when the custom input object is created.
It is assigned to the ID or NAME value specified by the current script as parameter of the AddInput function of the main forms class to add the custom input to the form definition.
It is meant to be used by any functions of the custom input class that need to know what is the name by which the main forms class registers the current custom input.
Default value: set by the main forms class
- mark_start
Text that identifies the beginning of a place holder mark in format templates.
Usually this variable does not need to be redefined by the custom input class.
Default value: "{"
- mark_end
Text that identifies the end of a place holder mark in format templates.
Usually this variable does not need to be redefined by the custom input class.
Default value: "}"
- server_validate
Boolean flag that tells whether the custom input performs server side validation that occurs after any validations of base inputs that it may have as children.
This variable should be redefined or initialized when the AddInput function is called, if the custom input does not perform any server side validation.
Default value: 1
- valid_marks
Associative array that specifies the meaning of names used in place holder marks used in the format template specified by the format variable.
This array has as entry indexes the types of elements to which each place holder is mapped when it is rendered by the custom input base class implementation of the AddInputPart function. Currently it supports the elements of type input, label and data.
The array values should be also associative arrays that map place holder mark names to the names of the elements that they will represent when the custom input is rendered.
This variable should be redefined by the custom input class if it is intended to use the default rendering method provided by the custom input base class.
Default value: array()
Example value:
array(
"input"=>array(
"year"=>"date_year",
"month"=>"date_month",
"day"=>"date_day"
),
"label"=>array(
"year"=>"date_year"
),
"data"=>array(
"clock"=>'<img src="clock.gif" width="16" height="16" alt="Clock">'
)
)
Class functions
Synopsis
$error=$input_object->AddChild($form, $name)
Purpose
Add the information of the name of a successfully added child input of a custom input.
This function is called when the AddInput function of the main forms class is called by the custom input class to add a child input.
This function should not need to be reimplemented in the actual custom input classes. The default implementation of the custom input base class stores the name of the child input in the children array class variable, so it may be used whenever the class needs to iterate over the children inputs.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $name argument is the identifier name of the just added child input.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->AddFunction($form, $arguments)
Purpose
Add the definition of a Javascript function that is meant to be generated as part of the output of the form. The function to be generated is meant to execute actions related with the elements of the form.
This function is called when the AddFunction function of the main forms class is called to add a function on a custom input element.
Usually this function does not need to be reimplemented in the actual custom input classes. The default implementation of the custom input base class calls the main forms class AddFunction on the input specified by the focus_input variable of the custom input object.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $arguments argument is the array passed to the main forms class AddFunction function.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->AddInput($form, $arguments)
Purpose
Initialize the custom input object with parameters that are meant to configure details of its behavior.
Usually it is used the create any basic inputs to be managed by the object of the custom input class, processing the format template and any other parameters specified by the input definition arguments.
This function is called when the AddInput function of the main forms class is called to add a custom input to the form.
This function needs to be reimplemented in the actual custom input classes.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. Make sure you declare the $form argument to be passed by reference.
The $arguments argument is the array passed to the main forms class AddInput function.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->AddInputHiddenPart($form)
Purpose
Add the input to the output that is generated for the form as if it was a hidden field.
Usually this function does not need to be reimplemented in the actual custom input classes if a format template and the list of valid marks is specified in the format and valid_marks custom input object variables.
Usage
The $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.
Synopsis
$error=$input_object->AddInputPart($form)
Purpose
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.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->AddLabelPart(&$form, $arguments)
Purpose
Add the label of the custom input to the output that is generated for the form with the main forms class Output method.
Usually this function does not need to be reimplemented in the actual custom input classes.
Usage
The $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.
Synopsis
$html=$input_object->ClassPageHead($form)
Purpose
Retrieve the HTML code that is necessary to insert in the page head section to make all custom inputs of the same class work correctly.
This function is called once from the main forms class PageHead function for each class of the custom inputs.
This function needs to be reimplemented in the custom input classes that need special Javascript code, CSS styles, link or meta tags to be defined in the page head section.
Usage
The $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.
Synopsis
$error=$input_object->Connect($form, $to, $event, $action, $context)
Purpose
Handle the request to connect another form input to the custom form input in such way that when a given event occurs in the other input on the client side (user browser), it is triggered an action that is executed in the context of the custom input.
This function is called when the Connect function of the main forms class is called and the custom input is the connection target input.
This function needs to be reimplemented in the actual custom input classes that support executing actions in result of handling input events that occur in other inputs connected to the custom input.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->DefaultConnect($form, $to, $event, $action, $context)
Provide a default implementation for the Connect function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the Connect function to register actions to be associated to events supported by the custom input.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->DefaultJavascriptGetConnectionAction($form, $form_object, $from, $event, $action, $context, $action)
Purpose
Provide a default implementation for the GetJavascriptConnectionAction function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the GetJavascriptConnectionAction function to generate Javascript code for actions that are not directly generated by the custom input class. Currently, it just fails returning an error but that behavior may change in the future.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $action argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->DefaultHandleEvent($form, $event, $parameters, $processed)
Purpose
Provide a default implementation for the HandleEvent function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the HandleEvent function to handle events that are not directly handled by the custom input class. Currently, it just fails returning an error but that behavior may change in the future.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $event argument is the name of the event that has occurred.
The $parameters argument is an associative array with all the parameters that were passed in the event handling request.
The $processed argument is used to pass a boolean variable by reference that is set by this function to indicate whether the event was processed by the function.
The $error return value contains an error message if there was an error while trying to process the specified event. Otherwise it contains an empty string.
Synopsis
$error=$input_object->DefaultPostMessage($form, $message, $processed)
Purpose
Provide a default implementation for the PostMessage function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the PostMessage function to handle messages that are not directly handled by the custom input class. Currently, it just sends a reply to the posted message.
Usage
This function is usually called to handle forwarded messages to delegate the handling of client side events. It only needs to be implemented by custom classes that expect handling forwarded messages.
The $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.
Synopsis
$error=$input_object->DefaultSetInputProperty($form, $property, $value)
Purpose
Provide a default implementation for the SetInputProperty function.
This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the SetInputProperty function to support properties that are not directly implemented by the custom input class. Currently, it only implements the following properties:
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $property argument is the name of the property to be changed.
The $value argument is the new value of the property.
The $error return value contains an error message if the specified property is not supported, or cannot be changed after the input has been created, or for some other reason the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$id=$input_object->GenerateInputID($form, $input, $kind)
Purpose
Helper function to generate input identifier names. It is meant to create names for basic inputs that make part of composite complex custom inputs.
For instance, a custom date input may be made of three basic inputs for the year, month and day. This function can be used to generate their names based on the identifier name of the custom input.
Usually this function does not need to be reimplemented in the actual custom input classes.
Usage
The $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.
Synopsis
$error=$input_object->GetContainedInputs($form, $kind, $contained)
Purpose
Retrieve the list of inputs contained within the custom input.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $kind argument is a string that specifies the kind of contained input to be retrieved. Currently this argument is ignored. Set to an empty string for future compatibility.
The $contained argument is a reference to a variable that will be assigned by this function to an array of identifier strings of the contained inputs.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely ignored if the method call arguments are correctly defined.
Synopsis
$actions=$input_object->GetEventActions($form, $form_object, $event)
Purpose
Generate the necessary Javascript code that will be used to implement the actions registered with the Connect function.
This function is meant to be called by custom input classes that need to generate Javascript that will be associated to a given event.
This function is implemented by the base custom input class and should not be reimplemented by any other custom input class.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $event argument is the name of event for which it is being generated the handling Javascript code.
The $form_object argument is a string that represents the Javascript object of the form to which the custom input belongs.
The $actions return value is the generated event handling Javascript code.
Synopsis
$value=$input_object->GetInputValue($form)
Purpose
Retrieve the current value of the custom input, eventually combining the current values of any of the inputs that compose the custom input.
This function is called when the main forms class GetInputValue is called specifying the current custom input identifier as argument.
This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.
Usage
The $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.
Synopsis
$javascript_value=$input_object->GetJavascriptCheckedState($form, $form_object)
Purpose
Generate a Javascript expression that represents the checked state of a the custom input field to be used to on client side scripts in Javascript.
Usage
The $form 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.
Synopsis
$error=$input_object->GetJavascriptConnectionAction($form, $form_object, $from, $event, $action, $context, $javascript)
Purpose
Generate the necessary Javascript code that will be used to implement the action that is executed when the trigger event occurs in a connected input.
This function is called when the main forms class generates the form output for the connection origin input, so it can assign the generated action Javascript code to the trigger event attribute definition.
This function needs to be reimplemented in the actual custom input classes that support executing actions in result of handling input events that occur in other inputs connected to the custom input.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $form_object argument is a string that represents the Javascript object of the form to which the given input belongs.
The $from argument is the identifier of the connection origin input on which it may occur the trigger event.
The $event argument is the name of event that may occur in the connection origin input in the client side (user browser).
The $action argument is the name of an action that will be executed in the context of the connection target input after the trigger event occurs in the origin input.
The $context argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.
The $javascript argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$javascript_value=$input_object->GetJavascriptInputValue($form, $form_object)
Purpose
Generate a Javascript expression that represents the value of the custom input field expression that be used to on client side scripts in Javascript to retrieve the input value.
This function is called when the main forms class GetJavascriptInputValue is called specifying the current custom input identifier as argument.
This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.
Usage
The $form 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.
Synopsis
$javascript=$my_form_object->GetJavascriptSetCheckedState($form, $form_object, $checked)
Purpose
Generate a Javascript expression to set the checked state of the custom input field.
Usage
The $form 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.
Synopsis
$javascript=$input_object->GetJavascriptSetInputProperty($form, $form_object, $property, $value)
Purpose
Generate Javascript commands to assign the value of a property of the custom input field.
This function is called when the main forms class GetJavascriptSetInputProperty function is called specifying the current custom input identifier as argument.
This function needs to be reimplemented in the actual custom input classes if it supports changing any input properties from Javascript.
Usage
The $form 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.
Synopsis
$error=$input_object->GetJavascriptValidations($form, $form_object, $validations)
Purpose
Retrieve a list of validation tests that are meant to be performed on the client side using Javascript.
This function is called by the main forms class to generate the part of the form output that has the Javascript code that is going to be used to perform the client side validation tests.
The custom input tests are performed after all other input values are validated on the client side. So it is safe to assume that when the custom input tests are executed, all other input fields that are validated on the client side contain valid values.
This function needs to be reimplemented in the actual custom input classes if there are special types of validation tests that can be performed on the client side, besides other tests that are eventually performed on individual inputs that make part of a composite custom input.
Usage
The $form 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:
- Commands
Array that defines a list of arbitrary Javascript commands to be executed right before evaluating the actual validation test condition. These commands can be used to compute the expressions that will be used in the test condition.
Each entry in the array defines a line that will be added to the Javascript function generated by the class to validate the form on the client side. Entries with emptry strings are suppressed.
- Condition
String that specifies a Javascript boolean expression that is evaluated to determine whether the input is valid. If the expression value is true, the field is invalid and no other validation tests are performed.
If the condition string is empty, no validation condition is evaluated.
- ErrorMessage
String that specifies the error message that is displayed to let the user know why the input value is not valid. This error message must not be missing or empty, unless the condition string is empty.
- Focus
String the specifies the identifier of the input that may get the input focus. Giving the focus to an input helps the user start correcting the input value right away.
This parameter is optional. If it is missing, the custom input class variable focus_input determines which input will get the focus. If this parameter is set to an empty string, no input will get the focus regardless of the value of the focus_input variable.
If you reimplement this function in custom input class, make sure you declare the $validations argument to be passed by reference.
Here follows an example of defined a special validation test that checks whether the day of a given month and year is valid:
$day=$form->GetJavascriptInputValue($form_object,$this->day);
$month=$form->GetJavascriptInputValue($form_object,$this->month);
$year=$form->GetJavascriptInputValue($form_object,$this->year);
$validations=array(
array(
"Commands"=>array(
"month=".$month,
"if(month=='04'",
"|| month=='06'",
"|| month=='09'",
"|| month=='11')",
" month_days=30",
"else",
"{",
" if(month=='02')",
" {",
" year=parseInt(".$year.")",
" if((year % 4)==0",
" && ((year % 100)!=0",
" || (year % 400)==0))",
" month_days=29",
" else",
" month_days=28",
" }",
" else",
" month_days=31",
"}",
"date_day=".$day
),
"Condition"=>"month_days<parseInt(date_day)",
"ErrorMessage"=>$this->invalid_day_error_message,
"Focus"=>$this->day
)
);
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->HandleEvent($form, $event, $parameters, $processed)
Purpose
Execute any actions or return information in response to a request to handle an event sent by the by the browser that is presenting the form to the user.
This function is called by the forms class function also named HandleEvent when it determines that a given event handling request should be routed to this custom input object class.
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.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $event argument is the name of the event that has occurred.
The $parameters argument is an associative array with all the parameters that were passed in the event handling request.
The $processed argument is used to pass a boolean variable by reference that is set by this function to indicate whether the event was processed by the function.
The $error return value contains an error message if there was an error while trying to process the specified event. Otherwise it contains an empty string.
Synopsis
$input_object->LoadInputValues($form, $submitted)
Purpose
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.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $submitted argument has the same value that is passed to the main forms class LoadInputValues.
Synopsis
$html=$input_object->PageHead($form)
Purpose
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.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $html return value contains the necessary HTML tags that should be inserted in the page head section.
Synopsis
$javascript=$input_object->PageLoad($form)
Purpose
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.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY ONLOAD tag.
Synopsis
$javascript=$input_object->PageUnload($form)
Purpose
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.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $javascript return value contains the necessary Javascript code that should be used to define the page BODY ONUNLOAD tag.
Synopsis
$error=$input_object->ParseNewInputFormat()
Purpose
Validate and process the current input display format template.
It parses the format template defined by the format variable and validates it to verify whether it complies with definition of place holders specified by the valid_marks variable.
This function is used by the custom input base class when it renders the input with the AddInputPart function. It may also be used to validate a new format template defined from the parameters of the AddInput or SetInputProperty functions.
Usually this function should not be reimplemented in the actual custom input classes.
Usage
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error=$input_object->PostMessage($form, $message, $processed)
Purpose
Handle a message targetted to the input.
Usage
This function is usually called to handle forwarded messages to delegate the handling of client side events. It only needs to be implemented by custom classes that expect handling forwarded messages.
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.
Synopsis
$error=$input_object->ReplyMessage($form, $message, $processed)
Purpose
Handle a message sent in reply to a previously posted event message.
Usually this function should be reimplemented in the actual custom input classes that post event handling messages.
Usage
The $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.
Synopsis
$error=$input_object->SetInputProperty($form, $property, $value)
Purpose
Change the value of a specific property of the custom input.
This function needs to be reimplemented in the actual custom input classes to support setting properties that can be changed after the creation of the custom input with the AddInput function.
Usage
The $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.
Synopsis
$error=$input_object->SetSelectOptions($form, $options, $selected)
Purpose
Set the list of options and selected values of a custom input that implements a behavior similar to a select input type.
This function is called when the SetSelectInput function of the main forms class is called for a custom input class.
This function needs to be reimplemented in the actual custom input classes that implement inputs similar to the select input type.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used.
The $options argument is an associative array that defines the list of options, like for the OPTIONS argument passed to AddInput function.
The $selected argument is array that defines the values of the list of options that should be selected, like for the SELECTED argument passed to AddInput function.
The $error return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.
Synopsis
$error_message=$input_object->ValidateInput($form)
Purpose
Validate the current value of the custom input.
This function is called by the main forms class Validate function after it has successfully validated all the basic type inputs. So, it is safe to retrieve from the ValidateInput function valid values of any basic inputs managed by a custom input class.
This function needs to be reimplemented in the actual custom input classes if they need to perform special types of validation besides the validations that are already performed on the basic inputs managed by custom input classes.
Usage
The $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.
Synopsis
$submitted_input=$my_form_object->WasSubmitted($form, $input)
Purpose
Determine if a form was submitted by the custom input.
Usage
The $form argument is a reference to the forms class object on which this custom input is being used. If you reimplement this function in custom input class, make sure you declare the $form argument to be passed by reference.
The $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.
Available custom input plug-ins classes
The forms class distribution comes with separate custom input plug-in classes that are ready to implement Web forms based user interfaces with sophisticated controls that provide complex functionality and enhanced usuability.
Here follows the list of available custom input classes. More will be made available later.
/*
* Create a form object.
*/
$form = new form_class;
$form->NAME = 'some_form_name';
/*
* The form submission method must be POST.
*/
$form->METHOD = 'POST';
/*
* Make the form be submitted to the current script.
*/
$form->ACTION = '';
/*
* Add some fields.
*/
$form->AddInput(array(
'TYPE' => 'text',
'NAME' => 'login',
'ID' => 'login',
'LABEL' => '<u>L</u>ogin',
'ACCESSKEY' => 'L'
));
$form->AddInput(array(
'TYPE' => 'text',
'NAME' => 'password',
'ID' => 'password',
'LABEL' => '<u>P</u>assword',
'ACCESSKEY' => 'P'
));
$form->AddInput(array(
'TYPE' => 'submit',
'NAME' => 'doit',
'ID' => 'doit',
'VALUE' => 'Submit'
));
/*
* Add the AJAX form submit custom input.
*/
$form->AddInput(array(
'TYPE' => 'custom',
'NAME' => 'sender',
'ID' => 'sender',
'CustomClass' => 'form_ajax_submit_class',
'Timeout' => 60,
'ONTIMEOUT' => 'alert('The communication with the server has timed out.');'
));
/*
* Make the submit button to the AJAX form submit custom input to make
* the form be submitted via AJAX when the submit button is clicked.
* Other client side events could trigger AJAX form submission.
*/
$form->Connect('doit', 'sender', 'ONCLICK', 'Submit', array());
/*
* Call HandleEvent to let the custom input to let
* the class handle the AJAX form submission
*
* Do not output anything before these lines.
*/
$form->HandleEvent($processed);
if($processed)
exit;
/*
* Was the form submitted via AJAX?
* Check whether the AJAX form submit input posted a message.
*/
if($form->GetNextMessage($message))
{
/*
* The form was submitted via AJAX.
* Lets process the messages to build an AJAX response and
* update only the relevant parts of the page on the browser
*/
do
{
/*
* Check what kind of events did occur on the browser?
*/
switch($message['Event'])
{
case 'submit':
/*
* The form was submitted. Lets validate and process it.
*/
$form->LoadInputValues();
$error_message = $form->Validate($verify);
/*
* If the form fields are valid, make any other
* server side only validations
*/
if(strlen($error_message)==0)
{
$error_message = ValidateLoginAndPassword(
$form->GetInputValue('login'),
$form->GetInputValue('password')
);
}
/*
* Are there any form validation errors?
*/
if(strlen($error_message))
{
/*
* Tell the form submitter input to send to the browser
* an order to display validation error feedback message.
*
* Replace the contents of the tags <div id="feedback"></div>
* with a validation error message.
*
* Make sure the message is correctly encoded in HTML using
* HTMLSpecialChars function.
*/
$message['Actions'] = array(
array(
'Action' => 'ReplaceContent',
'Container' => 'feedback',
'Content' => 'Validation error: '.HtmlSpecialChars($error_message);
)
);
}
else
{
/*
* The form was validated without errors.
* Lets execute the form processing actions
*/
/* Some processing actions should be executed here */
/*
* Show some feedback on the browser page.
*/
$message['Actions'][] = array(
'Action' => 'ReplaceContent',
'Container' => 'feedback',
'Content' => 'The form was submitted and processed successfully!'
);
/*
* Wait a few seconds before redirecting
* the browser to a new page.
*/
$message['Actions'][] = array(
'Action' => 'Wait',
'Time' => 3
);
/*
* Redirect the browser to a new page.
*/
$new_page = GetEnv('REQUEST_URI');
$message['Actions'][] = array(
'Action' => 'Redirect',
'URL' => 'http://'.GetEnv('HTTP_HOST').$new_page
);
}
break;
}
/*
* Reply to the form submit event to make it respond
* to the AJAX request in such way to make the browser
* execute to response actions.
*/
if(strlen($form->ReplyMessage($message, $processed)))
exit;
}
/*
* Loop until there are no more event messages
* or the processing was finished
*/
while(!$processed
&& $form->GetNextMessage($message));
/*
* If the request was fully processed, lets exit the script.
*/
if($processed)
exit;
}
/*
* Here validate, process and output the form
* like with any normal non-AJAX form submission
*/
form_animation_class
Purpose
Manage visual effects to be applied to elements of a form page.
Features
- It can manage any number of animations running simultaneously. Each animation consists of a sequence of distinct visual effects. The effects are executed one after another until the sequence ends.
- The animations can be defined to run when events on other form page elements occur.
- Different animations can be configured to run in debugging mode. On this mode, error messages are displayed when animation setup errors are detected.
Requirements
- Javascript animation class
This class requires a Javascript animation class to actually perform the animation effects. The Javascript class is available with this PHP class as a separate file named animation.js.
This PHP class generates the necessary HTML script tags to include the Javascript class file in the HTML page head section. Applications should use the main forms class PageHead function to retrieve the page head section tags that include the animation Javascript class file.
Properties
- JavascriptPath
Directory of the URI of the Javascript class file animation.js. If the directory of the URI of the current script if the same of the animation.js file, just leave this property set to an empty string.
Default value: ""
Event connection actions
This plug-in class implements only one action that can be triggered on the browser side. That action is named AddAnimation. It is used to a given animation to the list of running animation.
The definition of the animation should be passed to the action context parameter. This parameter is an associative array with entries to define several animation properties. Currently, it supports the following properties:
- Debug
Integer value that defines the level of the debug mode. 0 means that debugging is disabled. 1 or more makes the class display alert messages when animations define effects that may not be applied due to animation definition errors or impossible situations.
- Effects (Required)
Array with the definition of each effect in the animation sequence. Each entry of the array is an associative that describes the effect properties. Currently, the following properties are supported:
Animation
Name of the animated associated to the effect. It is required by the CancelAnimation effect.
Content
HTML tags of the content to use by the effect. It is required by the AppendContent, PrependContent and ReplaceContent effects.
Duration
Duration of the effect in seconds. It is required by the FadeIn, FadeOut and Wait effects.
DynamicElement
Javascript expression that defines dynamically the identifier of the page element to apply the effect. It is required in alternative to the Element property.
Element
Identifier of the page element to apply the effect. It is required by the AppendContent, FadeIn, FadeIn, Hide, PrependContent and ReplaceContent and Show effects.
Type (Required)
Name of the type of effect. Currently it supports the following effect types:
AppendContent
Insert more HTML tags at the end of the content of a given page element.
CancelAnimation
Stop and remove an animation given its name.
FadeIn
Make a given hidden page element appear smoothly until it becomes completely visible.
FadeOut
Make a given page element disappear smoothly until it becomes completely invisible.
Hide
Turn a given page element invisible.
PrependContent
Insert more HTML tags at the beginning of the content of a given page element.
ReplaceContent
Replace the HTML tags contained within a given page element.
Show
Turn a given page element visible.
Wait
Wait a given period of time.
Visibility
Defines the CSS property that will be used to control the visibility of an element for the effects: FadeIn, FadeIn, Hide, and Show. It may be set to either visibility or display. The default is visibility.
- Name
Name to associate to the animation being defined.
- Window
Javascript expression that defines the Window object on which the animation will run. It is necessary if it is intended to run an animation on a browser window or frame distinct from the one that is starting the animation.
form_auto_complete_class
Purpose
Automatically complete the values typed by the user in a text input by presenting a menu with a list of possible words that start with the text typed so far.
Features
- A menu is displayed below the text input with the list of possible completion words.
- The text completion is case insensitive.
- The completion values can be retrieved on demand from the server using AJAX, or loaded all at once within the form page.
- The completion words can be rendered in the menu with arbitrary HTML formatting.
- The completion words menu can be browsed using the up or down cursor keys. The enter and escape keys close the menu.
- An optional button input may be used to make the menu show all the possible options at once, regardless of what the user typed in the text input.
Requirements
- AJAX form submit class
In dynamic mode, this class needs the custom input plug-in class form_ajax_submit_class to retrieve the completion values on demand from the server.
Properties
- CompleteDelay
Delay in seconds that the input should wait after the last keystroke before it attempts to complete the text typed by the user.
Default value: 0.5
- CompleteInput
Identifier of the text input that will have the typed text automatically completed. This class does not add the text input to the form. It must be added separately by the application.
Default value: none
- CompleteMinimumLength
Minimum number of characters that the user must have typed before the class attempts to complete the text.
Default value: 3
- CompleteFeedback
HTML code to display within the page feedback element when the completion AJAX request is finished. This option is only relevant in the dynamic mode.
Default value: ""
- CompleteValues
Associative array that enumerates all possible completion values. The indexes of the array are the completion text strings. The array values define the HTML code used to present the completion options in the menu.
Default value: not set
- Dynamic
Boolean flag that determines whether the completion values are retrieved on demand from the server using AJAX, or are loaded all at once within the page Javascript code generated by this class.
Default value: 0
- FeedbackElement
Identifier of a page element within which feedback messages may appear when the completion is performed dynamically using AJAX. This option is only relevant in the dynamic mode.
Default value: ""
- ItemClass
Name of the presentation style class with which the menu items should be rendered.
Default value: not set
- ItemStyle
Definition of the presentation style attributes with which the menu items should be rendered.
Default value: "padding: 1px; color: #000000;"
- MenuClass
Name of the presentation style class with which the menu should be rendered.
Default value: not set
- MenuStyle
Definition of the presentation style attributes with which the menu should be rendered.
Default value: "background-color: #ffffff; border-width: 1px; border-color: #000000; border-style: solid; padding: 1px;"
- SelectedItemClass
Name of the presentation style class with which the menu items should be rendered when they are selected.
Default value: not set
- SelectedItemStyle
Definition of the presentation style attributes with which the menu items should be rendered when they are selected.
Default value: "padding: 1px; color: #ffffff; background-color: #000080;"
- ShowButton
Identifier of the button input that will trigger the action to make the menu display all the available options at once. This class does not add the button input to the form. It must be added separately by the application.
Default value: none
- SubmitFeedback
HTML code to display within the page feedback element when a completion AJAX request is submitted to the server. This option is only relevant in the dynamic mode.
Default value: ""
- Timeout
Limit of time in seconds that a browser should wait to retrieve the completion AJAX request response from the server. This option is only relevant in the dynamic mode.
Default value: 60
- TimeoutFeedback
HTML code to display within the page feedback element when the communication with the server times out. This option is only relevant in the dynamic mode.
Default value: ""
form_captcha_class
Purpose
CAPTCHA is a designation that means: a Completely Automated Public Turing test to tell Computers and Humans Apart.
It is a kind of tests that are used to make it dificult for automated programs to have access to certain resources by imposing challenges that are easy to respond for humans but much harder to solve for the automated programs.
This custom input type implements a CAPTCHA test by requiring that the user enters a text that is presented in an image that appears next to a text input.
Robot programs will have difficulty to determine what is written in the image as it may appear too obfuscated to be read even by OCR programs (Optical Character Recognition).
This kind of custom input is often used to prevent abuses of sites that are accessed by robot programs to perform automated tasks like for instance retrieving all pages of a site in a very short period or even retrieving pages restricted to a limited number of users.
Features
- It generates a text input with a validation image of customizable size with a text displayed in a random position of the image.
- The image can be obfuscated with an optional noise image that is drawn over the text also in a random position.
- It also presents a button to let the users request that the image be redrawn with the text and the noise image in a different position where it may be less difficult to read.
- The text is generated randomly with an optional validation expiry period. When the expiry period is reached the current text is not accepted as valid and a new text is generated.
- The class does not use sessions or cookies to keep track of the text that is displayed by the image. Instead, it uses a private server side key that is used to encrypt the text and the creation time that is passed in an event handling request to the class that decrypts the text to generate the validation image.
Requirements
- The GD image library extension
The class requires the PHP is configured to use the GD image library extension. Certain versions of the GD library do not support GIF images. In this case, the PNG or JPEG formats must be used.
- The mcrypt library extension
The class requires the PHP is configured to use the mcrypt library extension to be able to encrypt the validation text.
Properties
- BackgroundColor (changeable)
Color to be used to clear the background of the verification image. It must be in the hexadecimal RGB format: #RRGGBB. If it is set to an empty string it will appear with transparent background or white in case the image is generated in a format that does not support transparency.
Default value: ""
- ExpiryTime
Number of seconds of the time for which the validation text generated by the class remains valid. It must be a value greater than 0. If it is not set the text never expires.
Default value: not set
- ExpiryTimeValidationErrorMessage
Error message to return when the input value is not valid because the validation time expired. This property is required if the ExpiryTime property is set.
Default value: not set
- Font (changeable)
Specify number of the font that will be used to render the verification text. It can be either a font number from 0 to 5 to use a font built-in the GD library, or a custom font number returned by functions for opening fonts of other types.
Default value: 2
- Format (changeable)
Format of the template that defines how the input elements will be presented. There are four supported place holders for defining how the image, validation text, redraw button and the encrypted validation key fields will be presented: image, text, redraw and validation.
Default value: "{image} {text} {redraw}{validation}"
- ImageAlign (changeable)
Specify the type of vertical alignment of the verification image, like with the ALIGN attribute of the HTML IMG tag.
Default value: "top"
- ImageFormat (changeable)
Specify the type of format that the verification image will be generated. The supported formats are: gif, jpeg, png.
Default value: "gif"
- ImageHeight (changeable)
Specify the height with which the verification image will be generated.
Default value: 20
- ImageWidth (changeable)
Specify the width with which the verification image will be generated.
Default value: 80
- InputClass
Name of the presentation style class with which the text input field should be rendered.
Default value: not set
- InputExtraAttributes
List of extra attributes that should be added to the text input HTML tag when the form output is generated.
Default value: not set
- InputStyle
Definition of the presentation style attributes with which the text input field should be rendered.
Default value: not set
- InputTabIndex
Order of navigation of the text input field when using the tab key, as defined by the HTML TABINDEX attribute.
Default value: not set
- Key (required)
Private key that is used to encrypt the text that is passed back in a separate request to the class to draw and output the image.
Default value: not set
- NoiseFromGIFImage (changeable)
Specify the name of the image file in the GIF format that will be used as visual noise to obfuscate the text in the verification image. It must be a transparent image, or else the validation text will not be visible.
Default value: ""
- NoiseFromPNGImage (changeable)
Specify the name of the image file in the PNG format that will be used as visual noise to obfuscate the text in the verification image. It must be a transparent image, or else the validation text will not be visible.
Default value: ""
- RedrawClass
Name of the presentation style class with which the redraw submit input should be rendered.
Default value: not set
- RedrawStyle
Definition of the presentation style attributes with which the redraw submit input should be rendered.
Default value: not set
- RedrawSubform (changeable)
Text to be used in the redraw submit button.
Default value: "Redraw"
- RedrawText (changeable)
Text to be used in the redraw submit button.
Default value: "Redraw"
- ResetIncorrectText (changeable)
Boolean flag that determines whether the verification text should be changed to a new value when the user enters an incorrect text.
Default value: 0
- TextColor (changeable)
Color to be used to draw the validation text. It must be in the hexadecimal RGB format: #RRGGBB.
Default value: "#000000"
- TextLength (changeable)
Number of characters that will have the validation text.
Default value: 4
- ValidationErrorMessage (required)
Error message to return when the input value does not match the validation text presented in the image.
Default value: not set
- VerificationClass (changeable)
Name of the presentation style class with which the verification image should be rendered.
Default value: not set
- VerificationStyle (changeable)
Definition of the presentation style attributes with which the verification image should be rendered.
Default value: not set
form_date_class
Purpose
Let the user specify a date of the calendar with year, month and day.
Features
- It generates select inputs for the day and month and a text input for the year.
- It can validate any date between the years 1 and 9999 AC. The validation can be performed either on the client side and server side. It supports restricting the accepted period between given start and end dates.
- It can ask the user to enter an age relative to today's date rather than a specific date. The plug-in class subtracts the number of years, months and days entered by the user from today's date to compute the actual date.
- The submitted date value is returned in the ISO 9601 format (YYYY-MM-DD) but the date can be presented in any other format definable in the application that creates the form. The text that is displayed for the months may also be redefined.
- Optionally the date input may show a checkbox to let the user decide whether he wants to choose a date manually or assume a given default.
Properties
- Accessible
The same as the Accessible property for basic inputs.
Default value: not set
- AskAge
Boolean flag that indicates the plug-in class to ask the user for an age relative to today's date.
Default value: 0
- ChoiceDefaultValue
Default value to be used when the ChooseControl option is set whether checkbox that appears should be initially set.
Default value: 0
- Choose
Boolean flag that indicates when the ChooseControl option is set whether checkbox that appears should be initially set.
Default value: 0
- ChooseControl
Boolean flag that indicates whether the date input should show a checkbox to let the user decide whether he wants to choose a date manually or assume a given default.
Default value: 0
- DayClass
Name of the presentation style class with which the day input field should be rendered.
Default value: not set
- DayStyle
Definition of the presentation style attributes with which the day input field should be rendered.
Default value: not set
- FixedDay
Set the date day to a fixed value that cannot be changed by the user.
Default value: not set
- Format (changeable)
Format of the template that defines how the date will be presented. There are three supported place holders for defining how the year, month and day fields will be presented: year, month and day.
Default value: "{year}-{month}-{day}" or "{year}-{month}" when HideDay parameter is set to 1
- HideDay
Hide the day field so it is not displayed to the user. This parameter may only be set to 1 if the FixedDay parameter is also set.
Default value: 0
- MonthClass
Name of the presentation style class with which the month input field should be rendered.
Default value: not set
- MonthStyle
Definition of the presentation style attributes with which the month input field should be rendered.
Default value: not set
- Months
Associative array that defines the text for each of the 12 months of the year. The array entry indexes go from "01" to "12".
Default value: array with all entry values set to the entry indexes
- Optional
Boolean flag that determines whether the date input value is not required. An optional date field is accepted as valid when either the year, month and day fields are empty. In this case, the GetInputValue function returns an empty string.
Default value: 0
- SelectYears
Integer value that is used to determine whether year input will be displayed as input of type text or select.
If the ValidationStartDate and ValidationEndDate arguments are defined and the number of years between the two dates is less than the value of the SelectYears argument, the year is presented as a select type input with the given range of years as option values.
Default value: 10
- TABINDEX
Order of navigation of the input fields when using the tab key, as defined by the HTML TABINDEX attribute. When not set, all fields will have the same TABINDEX property value.
Default value: none
- VALUE (changeable)
Current value of the date. An empty string means, date not set. It may also be set to "now" as an alias to the current day date.
Default value: ""
- ValidationDateErrorMessage
Validation error message for when the user specifies a date that does not exist on the calendar.
Default value: "It was not specified a valid date."
- ValidationDayErrorMessage
Validation error message for when the user specifies an invalid day.
Default value: "It was not specified a valid day."
- ValidationErrorMessage
Default validation error message.
Default value: not set
- ValidationEndDate
Day of the end of the range of allowed dates. It may be set to "now" as an alias to the current day date.
Default value: "9999-12-31"
- ValidationEndDateErrorMessage
Validation error message to present when the current date is set to a day after the end date.
Default value: default validation error message
- ValidationMonthErrorMessage
Validation error message for when the user specifies an invalid month.
Default value: "It was not specified a valid month."
- ValidationStartDate
Day of the start of the range of allowed dates. It may be set to "now" as an alias to the current day date.
Default value: "0001-01-01"
- ValidationStartDateErrorMessage
Validation error message to present when the current date is set to a day before the start date.
Default value: default validation error message
- ValidationYearErrorMessage
Validation error message for when the user specifies an invalid month.
Default value: "It was not specified a valid year."
- YearClass
Name of the presentation style class with which the year input field should be rendered.
Default value: not set
- YearStyle
Definition of the presentation style attributes with which the year input field should be rendered.
Default value: not set
form_html_editor_class
Purpose
Let the user edit an HTML document visually.
Features
- The user can enter text and format it using toolbar buttons.
- Is based on a JavaScript library that works with the most important browsers.
- Fallback to a simple textarea in case JavaScript support is disabled in the browser.
- Can insert custom template marks that presented with configurable preview HTML.
- Can expand implicitly custom template marks in the HTML despite they may not be visible.
- Can use a custom CSS stylesheet for the HTML document.
Properties
- CLASS
Name of the presentation style class with which the editor container should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.
Default value: not set
- COLS
Number of rows of the editor as defined for the COLS attribute of the <TEXTAREA> HTML tag.
Default value: not set
- ExternalCSS
URI of the CSS file that defines styles for use in the editor frame.
Default value: not set
- JavascripPath
Directory of the URI of the Javascript class file html_editor.js. If the directory of the URI of the current script if the same of the html_editor.js file, just leave this property set to an empty string.
Default value: ""
- Mode
Name of the editing mode. Valid modes are visual for the visual editor and html for the HTML editor.
Default value: "visual"
- ROWS
Number of columns of the editor as defined for the COLS attribute of the <TEXTAREA> HTML tag.
Default value: not set
- ShowToolbars
Boolean flag that determines whether the editor toolbars are displayed.
Default value: 1
- STYLE
Definition of the presentation style attributes with which the editor container should be rendered.
Default value: not set
- TemplateVariables
Associative array that defines the properties of the supported template variables. The array entry names are the names of the variables. The array values are also associative arrays that define template property values. Currently the following template properies are supported:
- Alternatives
Associative array that defines all the supported alternative values of template. The array entry names are the alternative variable names. The array entry values are also associative arrays that define properties of the alternative values. Currently only the Preview and Title are supported. They have the same meaning as for the main template variable properties.
Default value: not set
- Inline
Boolean flag that determines whether the template variable should be displayed as inline or block element of the HTML document. If this option is omitted, the variable will be expanded to the value passed to the Value property.
Default value: none
- Preview
HTML to be used when displaying the template variable preview in the visual editor.
Default value: not set
- Title
Text to be used for the template variable in the insert template menu.
Default value: not set
- Value
HTML value to expand the template variable when the Inline variable is not set.
Default value: not set
Default value: not set
form_layout_paged_class
Purpose
This custom input type can be used to display a group of inputs that appear in pages that the user can switch clicking on tab buttons.
Features
- This kind of custom input can be used to split the layout of large forms in several smaller forms with inputs split over multiple pages.
- Only one page is displayed at a time. The pages are rendered near a set of tabs. Each tab corresponds to one page. When the user clicks on a tab, the corresponding page is displayed and the previously displayed page is hidden.
- This plug-in generates the necessary Javascript to switch the form pages to display without having to reload the Web page when the user clicks on the tabs.
If Javascript is disabled when the user clicks on a tab, the form is submitted to the server to be rendered again, showing just the page that corresponds to the clicked tab.
- This plug-in also generates the necessary stylesheet definitions to render the tab buttons. The tabs appear like separators of printed documentation bindings with tabs to quickly go to specific sections of the documentation.
The tabs are rendered in such way to give a 3D look effect to make it clear to the user which is the currentlty selected tab. In some browsers these tabs appear with rounded borders. Alternatively, the page tabs and buttons may be rendered using custom CSS classes.
The tab buttons are rendered in a row one after another. When there are too many tab buttons, there is the possibility to split the buttons in several rows to make them occupy less width.
- By default, each page displays only one input per page. However, the input displayed on each page may be a layout input that manages the presentation of multiple inputs.
The presentation of the each page may also be customized using a sub-class of the form_layout_paged_class with a function named AddPagePart. This function takes just one parameter, which is the identifier of the current page to be rendered.
- A page may appear with a fade-in effect when the user clicks on the respective tab button.
- When a validation error occurs, the page with the first invalid field is switched automatically.
- Can automatically adjust the size of the container of all pages to avoid the resizing that happens when it switches to a new page of a different size.
Properties
- AutoAdjustSize
Boolean flag that indicates whether the size of the container of the pages should be adjusted automatically to fit all pages.
Default value: 0
- CurrentPage (changeable)
Identifier of the page that appears selected initially.
Default value: first page
- FadePagesTime
Time in seconds that it will take the fade effect to make switched pages appear smoothly. It may be a floating point number to express a value below 1 second. Set to 0 to disable the page fade effect.
Default value: 0
- JavascriptPath
Directory of the URI of the Javascript class files necessary to implement animation effects.
Default value: ""
- PageClass
- TabClass
- GapClass
- PageButtonClass
- TabButtonClass
Name of alternative CSS classes that define how certain elements will be rendered, like: tab of the current page, tab of other pages, gaps between tabs, button of the current page, and button of other pages.
Default value: ""
- Pages
Associative array that defines parameters of each form page. The keys of the entries of this array are the identifiers of the pages. The array entry values should be also associative arrays that define the respective page parameters.
Here follows the list of currently supported parameters:
- Name (required)
Name to display in the respective page tab.
Default value: the same as the page identifier
- Caption
Text to display in each page as a caption to explain the purpose of the page fields.
Default value: none
- Break
Name of the option to specify whether the respective page tab button should break the row of tab buttons on which it is displayed.
This option may be either "before" or "after" depending on whether the row of buttons should be split before or after the current page tab button.
Default value: none
Event connection actions
This custom input implements one types of action that can be triggered on the browser side: SwitchPage.
The SwitchPage action is used to switch the currently selected page. It supports the context arguments Page and InputsPage.
The Page argument can be used to specify the identifier of a page to be switched.
The InputsPage argument can be used to specify an expression that references a Javascript object whose members are input identifiers, and the member values are pages to be switched. This argument is used internally to automatically switch the current page when the form has invalid fields.
form_layout_vertical_class
Purpose
This custom input type can be used to automatically compose the layout of a group of inputs that should appear vertically align.
Features
- This kind of custom input can be used to quickly layout many or even all inputs of a form without the need for manually written HTML templates.
- The list of inputs are rendered as a sequence of rows. The layout of each input row is defined by an HTML template that contains marks to specify where and how each input rendered, as well the input label and a mark to denote that the input is invalid, required or optional.
- This input can check the list of inputs considered invalid on the last call to the Validate function and render them with a special invalid input mark.
- The default templates for the input rows can be customized for all inputs or only for specific inputs.
- Individual inputs can be made read-only or invisible depending on a condition value, so they are ommited from the form output or not be editabled under certain circumstances.
- Can display inputs in multiple side-by-side columns.
Properties
- Columns
Bidimensional array that lists groups of identifiers of all the inputs to be included in the layout in side-by-side columns.
Default value: none
- Data
Associative array that specifies which of the inputs listed by the Inputs property should be rendered with custom HTML data. The keys of the entries of this array are the names of the data inputs and the entry values should the HTML data that should be rendered for the row of the respective data inputs.
Default value: none
- DefaultMark
HTML text string that defines how to render the input special mark for inputs that are not flagged as invalid.
Default value: empty string
- Footer
HTML text string that defines what should be rendered after the sequence of input rows.
Default value: </table>
- Header
HTML text string that defines what should be rendered before the sequence of input rows.
Default value: <table>
- InputFormat
HTML template that defines how each input row should be rendered. It must have marks named {input}, {label} and {mark} to denote where the input, label and a special input mark respectively should appear in the input row.
Default value: <tr><td valign="top">{label}:</td><td valign="top">{input} <span id="mark_{id}">{mark}</span></td></tr>
- Inputs
Array that lists the identifiers of all the inputs to be included in the layout.
Default value: none
- InvalidMark
HTML text string that defines how to render the input special mark for inputs that are flagged as invalid.
Default value: empty string
- NoLabelInputFormat
HTML template that defines how each input row should be rendered for inputs that do not have an associated label.
Default value: <tr><td colspan="2" align="center">{input}</td></tr>
- Properties
Associative array that defines special properties to override the default way each input row is rendered. The keys of the entries of this array are the names of the inputs and the entry values should more associative arrays that define the respective input rendering properties.
Here follows the list of currently supported properties:
- CenteredPair
Name of the position that determines whether the input should be presented grouped horizontally with the next inputs within the same row. If this property is left, middle or right, the respective input appears respectively on the left, middle or right of the centered group of inputs. Multiple inputs may be in the middle.
Currently, only inputs without labels can be presented as centered pairs.
Default value: none
- DefaultMark
HTML text string that overrides the DefaultMark property value.
- InputFormat
HTML template that overrides the InputFormat property value.
- InvalidMark
HTML text string that overrides the InvalidMark property value.
- ReadOnly
Boolean flag that determines whether the input should be rendered in read-only mode. If this property is 1, the respective input cannot be edited.
Default value: 0
- Visible
Boolean flag that determines whether the input row should appear in the form output. If this property is 0, the respective input row is ommited from the form output.
Default value: 1
- SwitchedPosition
Boolean flag that determines whether the input row should present the input and the label in switched positions. If this property is 1, the respective input appears in the place of the label and vice-versa.
Default value: 0
- CenteredPairLeftInputFormat
HTML template that defines how each input row should be rendered for inputs that have the CenteredPair property set to left.
Default value: <tr><td colspan="2" align="center">{input}
- CenteredPairRightInputFormat
HTML template that defines how each input row should be rendered for inputs that have the CenteredPair property set to right.
Default value: {input}</td></tr>
- SwitchedPositionInputFormat
HTML template that defines how each input row should be rendered for inputs that have the SwitchedPosition property set.
Default value: <tr><td align="right">{input}</td><td>{label} <span id="mark_{id}">{mark}</span></td></tr>
form_linked_select_class
Purpose
This custom input type implements a select input that can let the user choose one or more options from multiple groups of options.
The current group of options may be switched dynamically on the client side when it changes the value of another input to which this custom input is linked.
Features
- This kind of custom input can be linked to any type of input, including custom inputs of this or other classes. An unlimited number of this kind of custom inputs can be linked in cascade.
- The width and height of the input can be automatically adjusted according to the length of the text of the largest option of all groups and the group with more options.
- It supports select inputs of single or multiple selected options.
Properties
This custom input type supports most of the properties of base select input type.
- Groups
Associative array that contains all the groups of options that may be displayed. The keys of the entries of this array are the names of the groups and the entry values should be more associative arrays that define each group of options as defined by the OPTIONS attribute of the base select type input.
Default value: none
- LinkedInput
Identifier of the input linked to this custom input that defines the group of options that is currently in use. The current value of the linked input defines the current group of options. When the value of that input changes, the group of options of this custom input is switched.
Default value: none
- Dynamic
Boolean flag that tells whether the alternative groups of options should be dynamically retrieved by the browser when the linked input changes. When this option is set to 1, each group of options is retrieved from the server using Javascript and an hidden inline frame. Otherwise, the groups of options are passed all at once within the Javascript code that is generated with the form HTML.
The non-dynamic mode lets the linked input options be switched immediately, but for large groups of options the form page may become very large and slow to load. The dynamic mode is recommended when using large groups of options, or when the options need to be retrieved from a slow storage medium, like for instance a database. Look at the custom input sub-classes that are specialized in retrieving options from databases and other data sources.
Default value: 0
- AutoWidthLimit
Limit number of columns of width that this input will have initially. If this property is set and the Dynamic property is not set, the class will determine which is the longest option of all the specified groups of options. If the property is set to 0 the class sets the initial display width of the select input to the length of the longest option in em units. If this property is more than 0, the initial display width is set to no more columns than the value of this property.
Default value: not set
- AutoHeightLimit
Limit number of rows of height that this input will have. If this property is set and the Dynamic property is not set, the class will determine which is the longest group of options of all the specified groups. If the property is set to 0 the class sets the number of rows of the select input the count of options of the longest group. If this property is more than 0, the number of rows is set to no more than the value of this property.
Default value: not set
form_list_select_class
Purpose
This custom input type implements an emulation of a select input that allows to configure the presentation of the options as rows of a table with customizable HTML content.
Features
- It works in a compatible way with the regular select input.
- It can display the option elements in a table with rows with customizable HTML data for each option. The headers of the options table are configurable.
- The options table can be displayed in a container with limited height that may scroll.
- It uses radio inputs for single select lists and checkbox for multiple select inputs. An additional checkbox input is displayed to toggle the selection of all options of multiple select lists.
Properties
This custom input type supports most of the properties of base select input type.
- Accessible
Boolean option to tell whether the input is accessible when the form is in read only mode, or not accessible otherwise.
Default value: none
- CLASS
CSS style used to render the list select container.
Default value: none
- Columns
Array of options that defines how each column of the list select table will be rendered. Each entry contains an associative array that defines properties of each table column. Here follows the list of supported properties:
- Header
HTML that will be displayed in the column header row.
Default value: none
- Row
Name of the entry of the array passed by the Rows parameter from which it will be displayed the data for the current column.
Default value: none
- Type
String that defines the type of the column. If the type is Input, the column will display a radio input to select the respective option. If the type is Data, the column will display data from the array passed by the Rows input parameter. If the type is Option, the column will display data from the respective option value.
Default value: Data
Default value: array(
array(
'Type'=>'Input',
),
array(
'Type'=>'Option',
),
)
- MULTIPLE
Boolean option to tell whether the list will be a single or multiple select list.
Default value: 0
- ONCHANGE
Javascript code to be executed when the selected input changes.
Default value: none
- OptionReadOnlyMark
HTML that defines what should be displayed in the place of each option input if the input is displayed as not accessible.
Default value: none
- OPTIONS
Associative array that defines the values and text of a select field as defined for the OPTION HTML tag.
Default value: none
- ReadOnlyMark
HTML that defines what should be displayed if the input is displayed as not accessible.
Default value: none
- Rows
Associative array with data to be displayed in the list select table. The array keys are the names of the select options. The array keys are also associative arrays with the rows of data.
Default value: none
- SELECTED
Array of values of selected options when in multiple mode.
Default value: none
- SIZE
Number of rows that occupies container of the list select table. The size of the container is defined in em units, so it may not match exactly the number of list select table rows that will be made visible.
Default value: none
- STYLE
CSS style definition that will be used to render the list select container.
Default value: border-style: solid; border-color: #808080 #ffffff #ffffff #808080; border-width: 1px
- VALUE
Value of the selected option.
Default value: none
form_map_location_class
Purpose
This custom input type lets the user specify a location in the world by pointing it on a map. The input retrieves the latitude and longitude coordinates of the selected location.
Features
- The Google Maps API is used to render and browse the maps.
- The user can specify a location by clicking in any point on the map, or by entering the latitude and longitude coordinates in separate text inputs.
- The currently selected location is denoted by a marker icon. Initially, the selected locations appears on the center of the map.
- The text inputs of the coordinates of the selected may be rendered according to a configurable presentation template. These inputs may also be hidden.
- The map may present additional markers in application defined locations. Each marker may have a custom information window that appears when the mouse is over the marker. The marker may also have a custom tooltip title. When the user clicks on the marker icon, a new page may be opened on the same or a separate browser window.
- The zoom level can be set explicitly, or automatically by defining the coordinates of a bounding box that must fit in the current map size. The zoom level may also be adjusted to fit the area defined by the set of location markers.
- The GetJavascriptSetInputProperty function can be used to generate Javascript commands to change the Latitude and Longitude properties from Javascript.
- The maps can show advertising from Google AdSense to credit a given publisher.
- Can locate an address on the map using the Google Maps API geocoding support. The address to be searched can be taken from another input.
- Can cluster one or more groups of custom markers in case they overlap in the same region.
Requirements
- Google Maps API key
The Google Maps API requires an unique key to work on the pages of each site. The key may be obtained for free in the Google Maps API signup page.
- Page head, load and unload
Most of HTML and Javascript generated for this kind of custom input must be inserted in the page head section. Applications that use forms with this custom inputs must call the main forms class PageHead function to retrieve the necessary HTML tags to be inserted within the page head section.
This kind of input must be initialized from the page body load event. Use the main forms class PageLoad function to retrieve the necessary Javascript code to assign to the ONLOAD attribute of the page BODY HTML tag.
To avoid memory leak bugs of certain browsers, special Javascript code must be executed from the page body unload event. Use the main forms class PageUnload function to retrieve the necessary Javascript code to assign to the ONUNLOAD attribute of the page BODY HTML tag.
Properties
- Accessible
Boolean flag that determines whether the input should accessible. When the input is not accessible, it displays the map but the coordinates of the location point cannot be changed.
Default value: 1
- AdsManager
Associative array that specifies whether the maps may show advertising from Google AdSense to be credited to a given publisher. The array may contain values that define options for controlling aspects of the advertising.
- Channel
Identifier of the publisher account channel to be associated with advertising that is displayed.
Default value: none
- MaxAdsOnMap
Limit number of advertising units that can be displayed in the map.
Default value: 2
- Publisher
Identifier of the AdSense publisher account. Usually starts with ca-pub-.
Default value: none
Default value: none
- BoundsOffset
Value to adjust the coordinates bounding box to set the zoom level automatically when the ZoomMarkers property is specified. A positive value makes the bounding box expand.
Default value: none
- CLASS
CSS stylesheet used to render the <div> tag on which the map will appear.
Default value: none
- Clusters
Array that defines one or more marker managers that may cluster multiple markers in case they overlap in the current zoom level. Each cluster is described by an entry of the array. Each cluster entry should be an associative array that defines several cluster properties. Here follows the list of currently supported cluster properties:
- Manager
Name of the type of cluster that will aggregate the markers. Currently only the MarkerClusterer marker manager is supported.
Default value: none
- Path
Path URL of the script that defines the marker manager Javascript class. For MarkerClusterer marker manager the default path is markerclusterer.js.
Default value: none
- Controls
Associative array that specifies which additional built-in controls will be displayed on the map. The array entry indexes specify the control names. The entry values specify more associative arrays to define properties to customize details of the controls. The supported controls are: "SmallMap", "LargeMap", "SmallZoom", "Scale", "MapOverview" and "MapType". Currently no control properties are supported.
Default value: none
- Coordinates
Boolean flag that determines whether the coordinate values should be displayed along with the map.
Default value: 1
- HideMarker
Boolean flag that determines whether the location marker should not be displayed.
Default value: 0
- Icons
Associative array that defines any custom icons that may be needed. The array keys are names assigned to each custom icon. The array values are associative arrays that define icon properties as described in the Google Maps documentation. Currently the following properties are supported: image, shadow, printImage, mozPrintImage, transparent, dragCrossImage, iconSize, shadowSize, dragCrossSize, iconAnchor, infoWindowAnchor, dragCrossAnchor, maxHeight and imageMap.
Default value: none
- Key
Unique key to enable the access to the Google Maps API. A different key must be used for each site on which this API is used. The API key may be obtained for free in the Google Maps API signup page.
Default value: none
- Format
Format of the template that defines how the map and coordinate text inputs will be presented. There are seven supported place holders for defining how each input and label will be outputted: map, latitude, latitudelabel, longitude, longitudelabel, zoom and maptype.
Default value: "{map}\n<br />\n<div>{latitudelabel} {latitude} {longitudelabel} {longitude}</div>\n{zoom}\n{maptype}"
- Latitude (changeable)
Initial latitude coordinate value of the selected map location.
Default value: 0.0
- LatitudeClass
CSS stylesheet used to render the latitude text input.
Default value: none
- LatitudeLabel
Label for the latitude text input.
Default value: "Latitude:"
- LatitudeStyle
CSS style definition used to render the latitude text input.
Default value: none
- Longitude (changeable)
Initial longitude coordinate value of the selected map location.
Default value: 0.0
- LongitudeClass
CSS stylesheet used to render the longitude text input.
Default value: none
- LongitudeLabel
Label for the longitude text input.
Default value: "Longitude:"
- LongitudeStyle
CSS style definition used to render the longitude text input.
Default value: none
- MapType
Type of rendering used to display the map. There are three types of map rendering: Normal for rendering maps as colored polygons, Satellite for display satellite photographs, and Hybrid for rendering roads as polygons over satellite photographs.
Default value: "Normal"
- MarkerIcon
Name of a custom icon to be used as the marker.
Default value: none
- Markers
Array that defines additional custom markers to display on the map. Each marker is described by an entry of the array. Each marker entry should be an associative array that defines several marker properties. Here follows the list of currently supported marker properties:
- Cluster
Name of the cluster that will aggregate the markers that overlap in the current zoom level for being in the same region.
Default value: none
- Information
HTML string that defines the contents of the marker information window. This window opens when the mouse is over the marker.
Default value: none
- Icon
Name of a custom icon to be used as the marker.
Default value: none
- Latitude
Latitude coordinate value of the marker location.
Default value: none
- Link
URL of the page to be opened when the user clicks on the marker icon.
Default value: none
- Longitude
Longitude coordinate value of the marker location.
Default value: none
- Title
Title text to associate to the marker. Usually it appears as a tooltip when the mouse is over the marker, like with the HTML TITLE tag.
Default value: none
- Target
Name of the window or frame on which the page specified the Link marker property will be opened. If this marker property is not specified, the page will be opened on the same browser window.
Default value: none
Default value: none
- NoCoordinatesFormat
Format of the template that defines how the map and coordinate text inputs will be presented when the coordinates are not displyed. There are five supported place holders for defining how each input and label will be outputted: map, latitude, longitude, zoom and maptype.
Default value: "{map}\n{latitude}\n{longitude}\n{zoom}\n{maptype}"
- STYLE
CSS style definition used to render the <div> tag on which the map will appear.
Default value: none
- ValidationErrorMessage
Error message to display when the user enters invalid coordinate values.
Default value: "It was not specified a valid location."
- ZoomBounds
Array that defines the coordinates of a bounding box that must fit in the current map size. The zoom level will be adjusted to assure that the given coordinates will be visible. The array must have the four coordinates of the bounding box: South latitude, East longitude, North latitude and West longitude.
Default value: none
- ZoomMarkers
Boolean option that determines whether the zoom level and the map center should be adjusted to fit all the markers on the visible portion of the map.
Default value: none
- ZoomLevel
Level of zoom to display the map. 0 means show the whole world. Higher values make the map display an area closer to the selected location. The maximum accepted zoom level depends on the zone of the world.
Default value: 0
Event connection actions
This custom input implements one type of action that can be triggered on the browser side: LocateAddress.
The LocateAddress action is used to send a request to the Google Maps API to find the location of an address. The address value to be located is taken from another form input. If found, the map center and the mark location are set to the coordinates of the located address.
The LocateAddress action supports the context arguments Address, Country and CountryValue.
The Address argument can be used to specify the input from which the address to be located will be taken.
The Country argument can be used to specify an input from which will be taken the name of the country to restrict the search for the address.
The CountryValue is an option that determines how the of the name of the country to be searched will be retrieved from the input specified by the Country option. It can be either Value to use the current input value, or SelectedOption to use the text value of the current option of the country input.
form_mdb2_auto_complete_class
Purpose
This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.
It uses the PEAR::MDB2 API to execute the SQL queries that retrieve auto-complete texts. PEAR::MDB2 is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
Properties
This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.
- CompleteValues
No longer applies.
- Connection
Database connection object as returned by the function MDB2::connect. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.
Default value: not set
- CompleteValuesQuery
SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark {BEGINSWITH} to specify where it will be inserted the SQL LIKE pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.
Default value: not set
- CompleteValuesLimit
Maximum number of result entries that will be displayed in the auto-complete menu.
Default value: 10
form_mdb2_linked_select_class
Purpose
This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.
It uses the PEAR::MDB2 API to execute the SQL queries that retrieve groups of options. PEAR::MDB2 is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
Properties
This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.
- Groups
No longer applies.
- Dynamic
Same meaning but the default value has changed.
Default value: 1
- Connection
Database connection object as returned by the function MDB2::connect. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.
Default value: not set
- OptionsQuery
SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark ? to specify where the group identifier value should be used.
Default value: not set
- DefaultOption
Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.
Default value: not set
- DefaultOptionValue
Text value associated to the option specified by the DefaultOption parameter.
Default value: not set
- GroupsQuery
SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.
Default value: not set
form_metabase_auto_complete_class
Purpose
This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.
It uses the Metabase API to execute the SQL queries that retrieve auto-complete texts. Metabase is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
Properties
This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.
- CompleteValues
No longer applies.
- Connection
Database connection setup handle as returned by the function MetabaseSetupDatabase.
Default value: not set
- CompleteValuesQuery
SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark {BEGINSWITH} to specify where it will be inserted the SQL LIKE pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.
Default value: not set
- CompleteValuesLimit
Maximum number of result entries that will be displayed in the auto-complete menu.
Default value: 10
form_metabase_linked_select_class
Purpose
This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.
It uses the Metabase API to execute the SQL queries that retrieve groups of options. Metabase is a RDBMS independent PHP database abstraction layer. Therefore, this custom input class can work with many databases of different vendors.
Properties
This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.
- Groups
No longer applies.
- Dynamic
Same meaning but the default value has changed.
Default value: 1
- Connection
Database connection setup handle as returned by the function MetabaseSetupDatabase.
Default value: not set
- OptionsQuery
SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark ? to specify where the group identifier value should be used.
Default value: not set
- DefaultOption
Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.
Default value: not set
- DefaultOptionValue
Text value associated to the option specified by the DefaultOption parameter.
Default value: not set
- GroupsQuery
SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.
Default value: not set
form_mysql_auto_complete_class
Purpose
This custom input type extends the form_auto_complete_class. It provides the same functionality but retrieves the list of auto-complete texts from a MySQL database rather than from static arrays.
Properties
This custom input type supports most of the properties of base form_auto_complete_class custom input type but the context of some properties has changed.
- CompleteValues
No longer applies.
- Connection
Database connection handle as returned by the functions mysql_connect or mysql_pconnect.
Default value: not set
- CompleteValuesQuery
SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark {BEGINSWITH} to specify where it will be inserted the SQL LIKE pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.
Default value: not set
- CompleteValuesLimit
Maximum number of result entries that will be displayed in the auto-complete menu.
Default value: 10
form_mysql_linked_select_class
Purpose
This custom input type extends the form_linked_select_class. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.
It uses the PHP MySQL functions directly to execute the SQL queries that retrieve groups of options.
Properties
This custom input type supports most of the properties of base form_linked_select_class custom input type but the context of some properties has changed.
- Groups
No longer applies.
- Dynamic
Same meaning but the default value has changed.
Default value: 1
- Connection
Database connection setup handle as returned by the functions mysql_connect or mysql_pconnect.
Default value: not set
- OptionsQuery
SQL query string that should be executed to retrieve the list of options for a given group. This query takes a parameter to pass the group identifier value. The query condition clause should use the mark {GROUP} to specify where the group identifier value should be used.
Default value: not set
- DefaultOption
Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.
Default value: not set
- DefaultOptionValue
Text value associated to the option specified by the DefaultOption parameter.
Default value: not set
- GroupsQuery
SQL query string that should be executed to retrieve the list all groups. This query is executed in non-dynamic mode to retrieve all groups of options.
Default value: not set
form_scaffolding_class
Purpose
This custom input type can be used to compose and process forms for manipulating entries of records, stored for instance in databases, by the means of common CRUD actions: Create, Read, Update and Delete.
It can display a listing of entries to be edited with links to edit or delete such entries. An additional link is displayed to let the user create a new entry.
Features
- The create, read, update and delete actions can be enabled or disabled as needed by the application.
- Initially, a listing of entries is presented as a table with columns that display the values of different entry properties.
- The listing table may show different background colors for odd and even rows. A special color may be used to highlight the row under the mouse pointer.
- Optional pagination links may be displayed to let the user browse long listings of entries split over multiple pages.
- The listing rows for each entries may present links to trigger actions to edit or delete the respective entry. A separate link is displayed to trigger the action to create a new entry.
- The create, update and delete actions present a form with a configurable list of inputs to let the user set the entry properties.
- The form for creating or editing entries may show an optional submit button to show a preview of the entry being edited. Another optional button can be used to let the user save the entry and continue editing.
- The texts of all feedback messages are configurable.
- Several actions may trigger accesses to the server using AJAX to minimize server interaction access by avoiding page reloading. If Javascript support is disabled in the browser, the interactions will gracefully fallback to regular page reloading accesses.
Requirements
- form_ajax_submit_class
This plug-in class is necessary to interact with the server without page reloading.
- form_layout_vertical_class
This plug-in class is necessary to automatically layout the inputs of the forms for editing or deleting entries.
Properties
- CancelLabel
Text for the cancel submit button.
Default value: Cancel
- Create
Boolean option to determine whether the plug-in will present a form to create a new entry and a link to start the create form next to the existing entries listing.
Default value: 1
- CreateCanceledMessage (changeable)
HTML of the message that should be displayed when the new entry creation form was canceled.
Default value: Creating a new entry was canceled.
- CreatedMessage (changeable)
HTML of the message that should be displayed when a new entry is created successfully.
Default value: A new entry was created successfully.
- CreateMessage (changeable)
HTML of the message that should be displayed initially along with the new entry creation form.
Default value: Create a new entry
- CreatePreviewMessage (changeable)
HTML of the message that should be displayed when showing a preview of a new entry in the creation form.
Default value: New entry preview
- Columns (changeable)
Array with entries that define the way each column in the entries listing should be displayed.
Each entry in this array should be set to an associative array that defines the respective column properties.
Default value: array()
Column properties
Class
CSS class used to display values of the column.
Default value:
Delete
Boolean option to tell whether the column should display a link to start the delete form for the respective row entry.
Default value: 0
Format
HTML template that may define how the column values are displayed.
Default value: use the value directly
FormatParameters
Associative array that defines how each template placeholder should be replaced.
The keys of the array are the template placeholder marks. The values of the array entries define properties that describe how to generate the values that will replace the placeholders.
Default value: array()
Template placeholder properties
Column
Number of the column from which the default template placeholder value should be retrieved.
Default value: current column number
HTML
Boolean option to tell that the value should be encoded as HTML before displaying.
Default value: 0
Map
Associative array that determines how values should be mapped to alternative HTML representations.
Default value: array()
MapNull
Value to use when the column value is undefined.
Default value:
Replace
Associative array that defines a list of regular expressions that will be used to find and replace column values.
Default value: array()
Header
HTML to display in the header row of the column.
Default value:
HTML
Boolean option to tell that the column value should be encoded as HTML before displaying.
Default value: 0
ID
Boolean option to tell whether the column values have the respective entry identifiers.
Default value: 0
Map
Associative array that determines how values should be mapped to alternative HTML representations.
Default value: array()
MapNull
Value to use when the column value is undefined.
Default value:
Replace
Associative array that defines a list of regular expressions that will be used to find and replace column values.
Default value: array()
Style
CSS style used to display values of the column.
Default value:
Update
Boolean option to tell whether the column should display a link to start the update form for the respective row entry.
Default value: 0
View
Boolean option to tell whether the column should display a link to display an entry.
Default value: 0
- CustomParameters
Associative array with custom parameters and values that applications need to pass to each page to keep context.
Default value: array()
- Delete
Boolean option to determine whether the plug-in will present a form to delete existing entries and links in the entries listing to start the delete form to confirm the deletion of the respective entries.
Default value: 1
- DeleteCanceledMessage (changeable)
HTML of the message that should be displayed when an existing entry delete form was canceled.
Default value: Deleting the entry was canceled.
- DeletedMessage (changeable)
HTML of the message that should be displayed when an existing entry is deleted successfully.
Default value: The entry was deleted successfully.
- DeleteFields
Array with the definitions of each input that will be used in the forms to delete entries.
Default value: array()
- DeleteLabel
Text for the delete links and submit button.
Default value: Delete
- DeleteMessage (changeable)
HTML of the message that should be displayed along with the entry delete form.
Default value: Are you sure you want to delete this entry?
- Editing (get only)
Boolean flag that tells whether the user is creating, updating or deleting an entry.
- Entry (changeable)
Identifier of the entry to be updated or deleted.
Default value: not defined
- EntryFields
Array with the definitions of each input that will be used in the forms to create or update entries.
Default value: array()
- ErrorMessageFormat
HTML template used to display validation errors. The placeholder {errormessage} should be used to define where the actual validation error message should appear.
Default value: <div style="text-align: center; font-weight: bold">{errormessage}</div>
- EvenRowListingClass
Name of the CSS class to display the even rows of the entries listing table.
Default value:
- EvenRowListingColor
Background of the even rows of the entries listing table.
Default value:
- ExternalParameters
Associative array with custom parameters and values that applications need to pass to each page to keep context via in the link URLs only, and so not via hidden form inputs.
Default value: array()
- FormFooter (changeable)
HTML template used to append to the section with the layout of the forms to create, update and delete entries.
Default value:
- FormHeader (changeable)
HTML template used to prepend to the section with the layout of the forms to create, update and delete entries.
Default value:
- IDColumn (changeable)
Number of the column in the array passed to the Rows property that contains the value of the identifier of each entry to be listed.
Default value:
- InvalidMark
HTML to mark invalid form fields.
Default value: [X]
- ListingClass
Name of the CSS class to use for the table that presents the entries listing.
Default value:
- ListingMessage (changeable)
HTML of the message that should be displayed while displaying the entries listing.
Default value:
- ListingPadding
Padding of cells of the entries listing table.
Default value: 2
- ListingSpacing
Spacing for the entries listing table.
Default value: 0
- ListingStyle
CSS styles to use for the table that presents the entries listing.
Default value:
- NoEntriesMessage (changeable)
HTML of the message that should be displayed when there are no listing entries to display.
Default value:
- OddRowListingClass
Name of the CSS class to display the odd rows of the entries listing table.
Default value:
- OddRowListingColor
Background of the odd rows of the entries listing table.
Default value:
- Page (changeable)
Number of the current page of the entries listing to display starting from 1.
Default value: 1
- PageEntries (changeable)
Limit number of entries to display on each page of the entries listing.
Default value: 10
- Preview
Boolean option to determine whether the plug-in will present a submit button in the entry create or update form to display a preview of the entry next to the form and continue editing it.
Default value: 0
- PreviewLabel
Text for the preview submit button.
Default value: Preview
- EntryOutput (changeable)
HTML to display an entry being viewed or the preview of the entry being created or updated.
Default value:
- Read
Boolean option to determine whether the plug-in will present the listing of existing entries to be eventually edited or deleted.
Default value: 1
- Rows (changeable)
Bidimensional array with data to display in the entries listing.
Default value: array()
- Save
Boolean option to determine whether the plug-in will present a submit button in the entry create or update forms to save the entry and continue editing it the entry without exiting the form.
Default value: 0
- SaveLabel
Text for the save submit button.
Default value: Save
- State
Initial state of the user interface. Currently it supports the following states:
- create_canceled
The form to create a new entry was canceled.
- create_previewing
A preview of the entry being created is displayed.
- created
The form to create a new entry was submitted.
- creating
The form to create a new entry is being displayed.
- delete_canceled
The form to delete an existing entry was canceled.
- deleted
The form to delete an existing entry was submitted.
- deleting
The form to delete an existing entry is being displayed.
- listing
The listing of entries is being displayed.
- update_canceled
The form to update an existing entry was canceled.
- update_previewing
A preview of the entry being updated is displayed.
- updated
The form to update an existing entry was submitted.
- updating
The form to update an existing entry is being displayed.
- viewing
A view of a stored entry is displayed.
Default value: listing
- SubmitLabel
Text for the main submit button.
Default value: Submit
- TotalEntries (changeable)
Total number of the entries that can be displayed.
Default value: 0
- Update
Boolean option to determine whether the plug-in will present a form to update existing entries and links in the entries listing to start the update form to edit the respective entries.
Default value: 1
- UpdateCanceledMessage (changeable)
HTML of the message that should be displayed when an existing entry update form was canceled.
Default value: Updating an entry was canceled.
- UpdateInput
Name of inputs that should have their values updated during AJAX responses. It can be set several times to specify that different inputs should be updated
Default value: none
- UpdatedMessage (changeable)
HTML of the message that should be displayed when an existing entry is updated successfully.
Default value: The entry was updated successfully.
- UpdateLabel
Text for the update links and submit button.
Default value: Update
- UpdateMessage (changeable)
HTML of the message that should be displayed along with the entry update form.
Default value: Update this entry
- UpdatePreviewMessage (changeable)
HTML of the message that should be displayed when showing a preview of an existing entry in the update form.
Default value: Updated entry preview
- View
Boolean option to determine whether the plug-in will present pages to display individual entries and links in the entries listing to the entries view page.
Default value: 0
- ViewLabel
Text for the view links.
Default value: View
- ViewingMessage (changeable)
HTML of the message that should be displayed along with the view of an entry.
Default value: Viewing entry
Messages
The scaffolding custom input can capture interactions with the server regardless of whether the form was submitted to the server in the regular way or through an AJAX request.
When the form is submitted, it posts messages to the application during the call to the LoadInputValues function. The messages describe different types of events that should trigger applications actions for storing and retrieving information to show or manipulate the information of the entries that may be displayed or edited by the application.
The posted messages need to be retrieved using the GetNextMessage function, and replied with ReplyMessage function, so the plug-in can generate the appropriate HTML and Javascript to respond to the form submission requests.
The application may need to set some values in the messages before replying them in order to tell the plug-in what to do next. Consequently, the plug-in may post further messages to the application depending on the previous responses. Therefore, applications must process the messages in a loop until there are no more messages need to be handled.
Currently, it post the following types of messages that correspond to all the possible states of the input:
- create_canceled
This type of message is posted when the user clicked on the cancel button while the new entry form was being displayed.
Usually, applications do not need to do anything before replying to this type of message.
- create_previewing
This type of message is posted when the user clicked on the preview button while the new entry form is being displayed.
Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should generate HTML to display a preview of the of the entry that is being created and set the EntryOutput property.
- created
This type of message is posted when the user submitted the form to create a new entry.
Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should create the new entry.
The message Entry entry should be set to identifier of the newly created entry before replying to the message.
- creating
This type of message is posted when user is editing a new entry, eventually because he clicked on the new entry creation link.
Usually, applications do not need to do anything before replying to this type of message.
- delete_canceled
This type of message is posted when the user clicked on the cancel button while the delete entry form was being displayed.
The message Entry entry is set to the identifier of the entry to be deleted.
Usually, applications do not need to do anything before replying to this type of message.
- deleted
This type of message is posted when the user submitted the form to delete an existing entry.
The message Entry entry is set to the identifier of the entry to be deleted.
Applications should call the LoadInputValues and the Validate like with a regular form submission if the delete form had any additional inputs. If the form is valid the application should update the entry records.
- deleting
This type of message is posted when user is about to delete an existing entry, eventually because he clicked on the delete link of the respective entry in the entries listing.
The message Entry entry is set to the identifier of the entry to be deleted.
Usually, applications do not need to do anything before replying to this type of message.
- listing
This type of message is posted when the entries listing needs to be displayed. The application must set the properties TotalEntries, PageEntries, Rows to let the plug-in determine what it should list.
Applications may also set the IDColumn and Columns properties to define the how the listing should be presented, if those properties were not previously defined when the custom input was added.
The message has the Page entry set to the page of the entries listing should be displayed starting from 1.
If it is requested a page that is outside the range of available listing pages, applications may fix the current page to a value within the allowed range by setting the Page property.
- update_canceled
This type of message is posted when the user clicked on the cancel button while the update entry form was being displayed.
The message Entry entry is set to the identifier of the entry being edited.
Usually, applications do not need to do anything before replying to this type of message.
- update_previewing
This type of message is posted when the user clicked on the preview button while the update entry form is being displayed.
The message Entry entry is set to the identifier of the entry being edited.
Usually applications should do the same when processing create_previewing messages.
- updated
This type of message is posted when the user submitted the form to update an existing entry.
The message Entry entry is set to the identifier of the entry being edited.
Applications should call the LoadInputValues and the Validate like with a regular form submission. If the form is valid the application should update the entry records.
- updating
This type of message is posted when user is editing an existing entry, eventually because he clicked on the edit link of the respective entry in the entries listing.
The message Entry entry is set to the identifier of the entry being edited.
Applications need to retrieve the values of the entry properties to assign to the respective form inputs that will allow the user to change those entry properties.
- viewing
This type of message is posted when the user clicked on a link to view an entry.
The message Entry entry is set to the identifier of the entry to be displayed.
Usually applications should do the same when processing update_previewing messages, but display the stored entry values instead.
Message parameters
All the types of posted messages contain certain common entries. These common entries should not be changed by the application.
The Event entry is set to the type of message. The From and ReplyTo entries define the identifier of the custom input that posted the message. The AJAX entry is set when the form was submitted via AJAX.
Besides the types of entries that applications should set when replying to each type of message, applications may also set the Cancel entry to 1 when an error occurred, for instance while trying to update or delete an entry that does not exist, or when creating, updating or deleting an entry failed for some reason.
When there is a validation error, applications do not need to set any special message entries. The plug-in automatically detects and marks inputs that were flagged as invalid during validation.
form_secure_submit_class
Purpose
This input is used to prevent Cross-Site Request Forgery (CSRF) security attacks.
It emulates a common form submit or image input, but has an hidden input attached to it with a validation key that changes every time the form is presented.
When applications query the forms class to check whether the submit input was submitted, it only responds positively if the secret key is correct and it has not expired. Otherwise, this plug-in class pretends the submit input was not clicked.
This approach aims to frustrate CSRF attack attempts to forge a form submission using validation values scrapped from the form HTML page during a previous access.
Features
- It adds a submit or image input and an hidden input to validate the form submission. The validation value stored in the hidden input is generated using a secret key specified by the application. This key is used to encrypt the actual validation value. It is recommended to use different keys to present the same form to different site users
- The validation value expires after a given period of time. Applications may retrieve the Expired input property to determine whether the validation failed because someone forged a request with an invalid key or because the validation value expired. Applications may use this information to tell the user to submit the form again when the validation value expired.
- The validation value is not accepted when the current request was done using an HTTP method (GET or POST) different than the current form object method. Applications should use preferrably the POST method.
Requirements
- The mcrypt library extension
The class requires the PHP is configured to use the mcrypt library extension to be able to encrypt the validation value.
Properties
This custom input plug-in class takes the same properties as the inputs of type submit and image. Additionally, the class also supports the properties below.
If you specify the SRC property, an image input will be added. Otherwise, it will be added an input of type submit.
- ExpiryTime
Number of seconds of the time for which the validation value generated by the class remains valid. It must be a value greater than 0.
Default value: 300
- Expired (read-only)
Boolean flag that tells whether the validation value has expired after calling the main forms class WasSubmitted function.
Default value: 0
- Key (required)
Private key that is used to encrypt the validation value.
Default value: not set
form_upload_progress_class
Purpose
This custom input type monitors the progress of submission of a form to the server with file inputs. It can provide several statistics to the user to give an idea of how much of the uploading task was done and how much it remains.
Features
- A progress bar may be displayed in a specified position of the form page. The format of the bar can be customized.
- Form upload statistics may be displayed along with the progress bar, such as the percentage done, size of data being uploaded, upload speed and remaining time.
- The form upload statistics are monitored no more than one time per second to avoid delaying the upload excessively with the progress update information that is sent for display in the browser.
Requirements
- PHP version with upload monitor support
The class requires at least PHP 5.2 or an older version patched to provide upload monitor support. Patches are available to provide upload monitor support to older PHP versions.
- PHP upload progress extension
The class also requires that the current PHP installation has the upload progress extension available. Currently that extension can be obtained from the PECL repository.
- Form AJAX submit plug-in
The class requires the form AJAX submit custom input plug-in to monitor the upload progress during the form submission. This plug-in is available with the regular forms class distribution.
Properties
- FeedbackElement
Identifier of the page element within which the progress bar and other upload statistic details will appear.
Default value: none
- FeedbackFormat
String with an HTML template that defines how the progress bar and other details may appear. This plug-in replaces special template marks with upload progress statistic values. Then it updates the page element defined by the FeedbackElement with the resulting HTML data. Here follows the supported template marks:
- {ACCURATE_PROGRESS}
Percentage of the amount of data uploaded so far. This value is represented as a decimal value.
- {AVERAGE_SPEED}
Average speed of the upload considering the amount of data uploaded so far and the time that elapsed since the beginning of the upload. This value may appear with the suffixes K, M or G to represent speeds in KB/s, MB/s or GB/s if the speed is large enough.
- {CURRENT_SPEED}
Speed of upload of the last chunk of data that was received. This value may appear with the suffixes K, M or G to represent speeds in KB/s, MB/s or GB/s if the speed is large enough.
- {PROGRESS}
Percentage of the amount of data uploaded so far. This value is represented as a rounded integer value.
- {REMAINING}
Expected time remaining till the end of the upload. This value may appear with : within the values of remaining seconds, minutes and hours.
- {TOTAL}
Total amount of data expected to be sent when the upload finishes. This value may appear with the suffixes K, M or G to represent the amount in KB, MB or GB if the amount is large enough.
- {UPLOADED}
Amount of data uploaded so far. This value may appear with the suffixes K, M or G to represent the amount in KB, MB or GB if the amount is large enough.
Default value: {PROGRESS}%
Example value: <table style="width: 200px" border="1"><tr> <td style="width: {ACCURATE_PROGRESS}%; border-style: none; background-color: #0000ff; background-image: url(progress.gif); text-align: center;">{PROGRESS}%</td> <td style="border-style: none;"></td> </tr></table>
|
