fanir/feedizer-php
1
0
Fork 0
Code Releases Activity
feedizer-php/htdocs/libraries/formsgeneration/forms.html

4420 lines
349 KiB
HTML
Raw Normal View History

initial commit
2015-11-13 23:51:46 +01:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Forms class documentation</title>
</head>
<body>
<center><h1>Forms class documentation</h1></center>
<hr />
<ul>
<p><b>Author:</b> Manuel Lemos (<a href="mailto:mlemos-at-acm.org">mlemos-at-acm.org</a>)</p>
<p><b>Version control:</b> <tt>@(#) $Id: forms.documentation,v 1.164 2014/08/11 03:47:06 mlemos Exp $</tt></p>
<h2>Contents</h2>
<ul>
<li><a href="#2.1.1">Summary</a></li>
<li><a href="#3.1.2">Methods</a></li>
<ul>
<li><a href="#4.2.0">AddDataPart</a></li>
<li><a href="#5.2.0">AddFunction</a></li>
<ul>
<li><a href="#6.3.0">Arguments</a></li>
<ul>
<li><a href="#7.4.1">Element</a></li>
<li><a href="#7.4.2">Function</a></li>
<li><a href="#7.4.3">Type</a></li>
</ul>
</ul>
<li><a href="#7.2.0">AddInput</a></li>
<ul>
<li><a href="#8.3.0">Arguments</a></li>
<ul>
<li><a href="#9.4.1">ACCEPT</a></li>
<li><a href="#9.4.2">ACCESSKEY</a></li>
<li><a href="#9.4.3">ALT</a></li>
<li><a href="#9.4.4">ALIGN</a></li>
<li><a href="#9.4.5">ApplicationData</a></li>
<li><a href="#9.4.6">CHECKED</a></li>
<li><a href="#9.4.7">CLASS</a></li>
<li><a href="#9.4.8">COLS</a></li>
<li><a href="#9.4.9">Content</a></li>
<li><a href="#9.4.10">DisableResubmitCheck</a></li>
<li><a href="#9.4.11">ID</a></li>
<li><a href="#9.4.12">IgnoreAnonymousSubmitCheck</a></li>
<li><a href="#9.4.13">InvalidCLASS</a></li>
<li><a href="#9.4.14">InvalidSTYLE</a></li>
<li><a href="#9.4.15">LABEL</a></li>
<li><a href="#9.4.16">LabelCLASS</a></li>
<li><a href="#9.4.17">LabelExtraAttributes</a></li>
<li><a href="#9.4.18">LabelID</a></li>
<li><a href="#9.4.19">LabelSTYLE</a></li>
<li><a href="#9.4.20">LabelTITLE</a></li>
<li><a href="#9.4.21">MAXLENGTH</a></li>
<li><a href="#9.4.22">MULTIPLE</a></li>
<li><a href="#9.4.23">NAME</a></li>
<li><a href="#9.4.24">NoParent</a></li>
<li><a href="#9.4.25">ONBLUR</a></li>
<li><a href="#9.4.26">ONCHANGE</a></li>
<li><a href="#9.4.27">ONCLICK</a></li>
<li><a href="#9.4.28">ONDBLCLICK</a></li>
<li><a href="#9.4.29">ONFOCUS</a></li>
<li><a href="#9.4.30">ONKEYDOWN</a></li>
<li><a href="#9.4.31">ONKEYPRESS</a></li>
<li><a href="#9.4.32">ONKEYUP</a></li>
<li><a href="#9.4.33">ONMOUSEDOWN</a></li>
<li><a href="#9.4.34">ONMOUSEMOVE</a></li>
<li><a href="#9.4.35">ONMOUSEOUT</a></li>
<li><a href="#9.4.36">ONMOUSEOVER</a></li>
<li><a href="#9.4.37">ONMOUSEUP</a></li>
<li><a href="#9.4.38">ONSELECT</a></li>
<li><a href="#9.4.39">OPTIONS</a></li>
<li><a href="#9.4.40">ROWS</a></li>
<li><a href="#9.4.41">SELECTED</a></li>
<li><a href="#9.4.42">SIZE</a></li>
<li><a href="#9.4.43">SRC</a></li>
<li><a href="#9.4.44">STYLE</a></li>
<li><a href="#9.4.45">TABINDEX</a></li>
<li><a href="#9.4.46">TYPE</a></li>
<li><a href="#9.4.47">VALUE</a></li>
<li><a href="#9.4.48">Accessible</a></li>
<li><a href="#9.4.49">Capitalization</a></li>
<li><a href="#9.4.50">ClientScript</a></li>
<li><a href="#9.4.51">CustomClass</a></li>
<li><a href="#9.4.52">DependentValidation</a></li>
<li><a href="#9.4.53">DiscardInvalidValues</a></li>
<li><a href="#9.4.54">EncodedField</a></li>
<li><a href="#9.4.55">Encoding</a></li>
<li><a href="#9.4.56">EncodingFunctionScriptFile</a></li>
<li><a href="#9.4.57">EncodingFunctionVerification</a></li>
<li><a href="#9.4.58">ExtraAttributes</a></li>
<li><a href="#9.4.59">PLACEHOLDER</a></li>
<li><a href="#9.4.60">ReadOnlyMark</a></li>
<li><a href="#9.4.61">ReadOnlyMarkUnchecked</a></li>
<li><a href="#9.4.62">ReplacePatterns</a></li>
<li><a href="#9.4.63">ReplacePatternsOnlyOnClientSide</a></li>
<li><a href="#9.4.64">ReplacePatternsOnlyOnServerSide</a></li>
<li><a href="#9.4.65">SubForm</a></li>
<li><a href="#9.4.66">TITLE</a></li>
<li><a href="#9.4.67">ValidateAsCreditCard</a></li>
<li><a href="#9.4.68">ValidateAsCreditCardErrorMessage</a></li>
<li><a href="#9.4.69">ValidateAsDifferentFrom</a></li>
<li><a href="#9.4.70">ValidateAsDifferentFromErrorMessage</a></li>
<li><a href="#9.4.71">ValidateAsDifferentFromText</a></li>
<li><a href="#9.4.72">ValidateAsDifferentFromTextErrorMessage</a></li>
<li><a href="#9.4.73">ValidateAsEmail</a></li>
<li><a href="#9.4.74">ValidateAsEmailErrorMessage</a></li>
<li><a href="#9.4.75">ValidateAsEqualTo</a></li>
<li><a href="#9.4.76">ValidateAsEqualToErrorMessage</a></li>
<li><a href="#9.4.77">ValidateAsFloat</a></li>
<li><a href="#9.4.78">ValidateAsFloatErrorMessage</a></li>
<li><a href="#9.4.79">ValidateAsInteger</a></li>
<li><a href="#9.4.80">ValidateAsIntegerErrorMessage</a></li>
<li><a href="#9.4.81">ValidateAsNotEmpty</a></li>
<li><a href="#9.4.82">ValidateAsNotEmptyErrorMessage</a></li>
<li><a href="#9.4.83">ValidateAsNotRegularExpression</a></li>
<li><a href="#9.4.84">ValidateAsNotRegularExpressionErrorMessage</a></li>
<li><a href="#9.4.85">ValidateAsSet</a></li>
<li><a href="#9.4.86">ValidateAsSetErrorMessage</a></li>
<li><a href="#9.4.87">ValidationErrorMessage</a></li>
<li><a href="#9.4.88">ValidateMinimumLength</a></li>
<li><a href="#9.4.89">ValidateMinimumLengthErrorMessage</a></li>
<li><a href="#9.4.90">ValidateOnlyOnClientSide</a></li>
<li><a href="#9.4.91">ValidateOnlyOnServerSide</a></li>
<li><a href="#9.4.92">ValidateOptionalValue</a></li>
<li><a href="#9.4.93">ValidateRegularExpression</a></li>
<li><a href="#9.4.94">ValidateRegularExpressionErrorMessage</a></li>
<li><a href="#9.4.95">ValidationClientFunction</a></li>
<li><a href="#9.4.96">ValidationClientFunctionErrorMessage</a></li>
<li><a href="#9.4.97">ValidationCreditCardTypeField</a></li>
<li><a href="#9.4.98">ValidationDecimalPlaces</a></li>
<li><a href="#9.4.99">ValidationLowerLimit</a></li>
<li><a href="#9.4.100">ValidationServerFunction</a></li>
<li><a href="#9.4.101">ValidationServerFunctionErrorMessage</a></li>
<li><a href="#9.4.102">ValidationUpperLimit</a></li>
</ul>
</ul>
<li><a href="#9.2.0">AddHiddenInputs</a></li>
<li><a href="#10.2.0">AddHiddenInputsParts</a></li>
<li><a href="#11.2.0">AddInputHiddenPart</a></li>
<li><a href="#12.2.0">AddInputPart</a></li>
<li><a href="#13.2.0">AddInputReadOnlyPart</a></li>
<li><a href="#14.2.0">AddLabelPart</a></li>
<ul>
<li><a href="#15.3.0">Arguments</a></li>
<ul>
<li><a href="#16.4.1">ACCESSKEY</a></li>
<li><a href="#16.4.2">CLASS</a></li>
<li><a href="#16.4.3">FOR</a></li>
<li><a href="#16.4.4">ExtraAttributes</a></li>
<li><a href="#16.4.5">ID</a></li>
<li><a href="#16.4.6">LABEL</a></li>
<li><a href="#16.4.7">STYLE</a></li>
<li><a href="#16.4.8">TITLE</a></li>
</ul>
</ul>
<li><a href="#16.2.0">Connect</a></li>
<li><a href="#17.2.0">ConnectFormToInput</a></li>
<li><a href="#18.2.0">DisplayOutput</a></li>
<li><a href="#19.2.0">EncodeJavascriptString</a></li>
<li><a href="#20.2.0">EndLayoutCapture</a></li>
<li><a href="#21.2.0">FetchOutput</a></li>
<li><a href="#22.2.0">FlagInvalidInput</a></li>
<li><a href="#23.2.0">GetFileValues</a></li>
<li><a href="#25.2.0">GetCheckable</a></li>
<li><a href="#26.2.0">GetCheckedRadio</a></li>
<li><a href="#27.2.0">GetCheckedRadioValue</a></li>
<li><a href="#28.2.0">GetCheckedState</a></li>
<li><a href="#29.2.0">GetContainedInputs</a></li>
<li><a href="#30.2.0">GetInputProperty</a></li>
<li><a href="#32.2.0">GetInputValue</a></li>
<li><a href="#33.2.0">GetInputEventURL</a></li>
<li><a href="#34.2.0">GetInputs</a></li>
<li><a href="#35.2.0">GetJavascriptCheckedRadioValue</a></li>
<li><a href="#36.2.0">GetJavascriptCheckedState</a></li>
<li><a href="#37.2.0">GetJavascriptConnectionAction</a></li>
<li><a href="#38.2.0">GetJavascriptInputObject</a></li>
<li><a href="#39.2.0">GetJavascriptInputValue</a></li>
<li><a href="#40.2.0">GetJavascriptSelectedOption</a></li>
<li><a href="#41.2.0">GetJavascriptSetCheckedState</a></li>
<li><a href="#42.2.0">GetJavascriptSetFormProperty</a></li>
<li><a href="#43.2.0">GetJavascriptSetInputProperty</a></li>
<li><a href="#44.2.0">GetJavascriptSetInputValue</a></li>
<li><a href="#45.2.0">GetNextMessage</a></li>
<li><a href="#46.2.0">GetSubmittedValue</a></li>
<li><a href="#47.2.0">HandleEvent</a></li>
<li><a href="#48.2.0">LoadInputValues</a></li>
<li><a href="#49.2.0">Output</a></li>
<ul>
<li><a href="#50.3.0">Arguments</a></li>
<ul>
<li><a href="#51.4.1">EndOfLine</a></li>
<li><a href="#51.4.2">Function</a></li>
</ul>
</ul>
<li><a href="#51.2.0">OutputDebug</a></li>
<li><a href="#52.2.0">PageHead</a></li>
<li><a href="#53.2.0">PageLoad</a></li>
<li><a href="#54.2.0">PageUnload</a></li>
<li><a href="#55.2.0">PostMessage</a></li>
<li><a href="#57.2.0">RemoveFunction</a></li>
<li><a href="#58.2.0">ReplyMessage</a></li>
<li><a href="#59.2.0">ResetFormParts</a></li>
<li><a href="#60.2.0">SetCheckedRadio</a></li>
<li><a href="#61.2.0">SetCheckedState</a></li>
<li><a href="#62.2.0">SetInputProperty</a></li>
<li><a href="#64.2.0">SetInputValue</a></li>
<li><a href="#65.2.0">SetSelectOptions</a></li>
<li><a href="#66.2.0">StartLayoutCapture</a></li>
<li><a href="#67.2.0">Validate</a></li>
<li><a href="#69.2.0">WasSubmitted</a></li>
</ul>
<li><a href="#70.1.3">Properties</a></li>
<ul>
<li><a href="#71.2.1">ACTION</a></li>
<li><a href="#71.2.2">ENCTYPE</a></li>
<li><a href="#71.2.3">ID</a></li>
<li><a href="#71.2.4">METHOD</a></li>
<li><a href="#71.2.5">NAME</a></li>
<li><a href="#71.2.6">ONERROR</a></li>
<li><a href="#71.2.7">ONSUBMIT</a></li>
<li><a href="#71.2.8">ONSUBMITTING</a></li>
<li><a href="#71.2.9">ONRESET</a></li>
<li><a href="#71.2.10">TARGET</a></li>
<li><a href="#71.2.11">error</a></li>
<li><a href="#71.2.12">Changes</a></li>
<li><a href="#71.2.13">DisableReadOnlyInputs</a></li>
<li><a href="#71.2.14">ExtraAttributes</a></li>
<li><a href="#71.2.15">Invalid</a></li>
<li><a href="#71.2.16">InvalidCLASS</a></li>
<li><a href="#71.2.17">InvalidSTYLE</a></li>
<li><a href="#71.2.18">OptionsSeparator</a></li>
<li><a href="#71.2.19">OutputPasswordValues</a></li>
<li><a href="#71.2.20">ReadOnly</a></li>
<li><a href="#71.2.21">ResubmitConfirmMessage</a></li>
</ul>
<li><a href="#71.1.4">Options</a></li>
<ul>
<li><a href="#72.2.1">ErrorMessagePrefix</a></li>
<li><a href="#72.2.2">ErrorMessageSuffix</a></li>
<li><a href="#72.2.3">ShowAlertOnError</a></li>
<li><a href="#72.2.4">ShowAllErrors</a></li>
<li><a href="#72.2.5">ValidateAsCreditCard</a></li>
<li><a href="#72.2.6">ValidateAsEmail</a></li>
<li><a href="#72.2.7">ValidationErrorFunctionName</a></li>
<li><a href="#72.2.8">ValidationFunctionName</a></li>
<li><a href="#72.2.9">ValidateOnlyOnServerSide</a></li>
<li><a href="#72.2.10">accessibility_tab_index</a></li>
<li><a href="#72.2.11">debug</a></li>
<li><a href="#72.2.12">decimal_regular_expression</a></li>
<li><a href="#72.2.13">event_parameter</a></li>
<li><a href="#72.2.14">email_regular_expression</a></li>
<li><a href="#72.2.15">encoding</a></li>
<li><a href="#72.2.16">end_of_line</a></li>
<li><a href="#72.2.17">float_regular_expression</a></li>
<li><a href="#72.2.18">form_submitted_test_variable_name</a></li>
<li><a href="#72.2.19">form_submitted_variable_name</a></li>
<li><a href="#72.2.20">input_parameter</a></li>
<li><a href="#72.2.21">sub_form_variable_name</a></li>
<li><a href="#72.2.22">tolower_function</a></li>
<li><a href="#72.2.23">toupper_function</a></li>
</ul>
<li><a href="#72.1.5">Functions</a></li>
<ul>
<li><a href="#73.2.1">FormCaptureOutput</a></li>
</ul>
<li><a href="#74.1.6">Template processing</a></li>
<ul>
<li><a href="#75.2.1">Separating presentation from logic</a></li>
<li><a href="#75.2.2">Plain HTML template files with embedded PHP code</a></li>
<li><a href="#75.2.3">Smarty template engine</a></li>
<li><a href="#75.2.4">Smarty plug-in filter for form composition</a></li>
</ul>
<li><a href="#75.1.7">Enhancing forms with custom input type plug-ins</a></li>
<ul>
<li><a href="#76.2.1">Custom input classes</a></li>
<ul>
<li><a href="#77.3.1">Basic steps for developing new custom input classes</a></li>
<ul>
<li><a href="#78.4.1">Create a new custom input class</a></li>
<li><a href="#78.4.2">Implement the input initialization</a></li>
<li><a href="#78.4.3">Define the page head section or the load and unload events</a></li>
<li><a href="#78.4.4">Retrieve input values</a></li>
<li><a href="#78.4.5">Setting properties</a></li>
<li><a href="#78.4.6">Validate input values</a></li>
<li><a href="#78.4.7">Load submitted input values</a></li>
<li><a href="#78.4.8">Connecting inputs to trigger special actions upon client side events</a></li>
<li><a href="#78.4.9">Registering custom client side input events</a></li>
<li><a href="#78.4.10">Handling client side events on the server side</a></li>
<li><a href="#78.4.11">Forward client side events to custom inputs</a></li>
<li><a href="#78.4.12">Emulating form submit inputs</a></li>
</ul>
<li><a href="#78.3.2">Class variables</a></li>
<ul>
<li><a href="#79.4.1">children</a></li>
<li><a href="#79.4.2">client_validate</a></li>
<li><a href="#79.4.3">connections</a></li>
<li><a href="#79.4.4">events</a></li>
<li><a href="#79.4.5">format</a></li>
<li><a href="#79.4.6">focus_input</a></li>
<li><a href="#80.4.7">input</a></li>
<li><a href="#80.4.8">mark_start</a></li>
<li><a href="#80.4.9">mark_end</a></li>
<li><a href="#80.4.10">server_validate</a></li>
<li><a href="#80.4.11">valid_marks</a></li>
</ul>
<li><a href="#80.3.3">Class functions</a></li>
<ul>
<li><a href="#81.4.0">AddChild</a></li>
<li><a href="#82.4.0">AddFunction</a></li>
<li><a href="#83.4.0">AddInput</a></li>
<li><a href="#84.4.0">AddInputHiddenPart</a></li>
<li><a href="#85.4.0">AddInputPart</a></li>
<li><a href="#86.4.0">AddLabelPart</a></li>
<li><a href="#87.4.0">ClassPageHead</a></li>
<li><a href="#88.4.0">Connect</a></li>
<li><a href="#89.4.0">DefaultConnect</a></li>
<li><a href="#90.4.0">DefaultJavascriptGetConnectionAction</a></li>
<li><a href="#91.4.0">DefaultHandleEvent</a></li>
<li><a href="#92.4.0">DefaultPostMessage</a></li>
<li><a href="#93.4.0">DefaultSetInputProperty</a></li>
<li><a href="#95.4.0">GenerateInputID</a></li>
<li><a href="#96.4.0">GetContainedInputs</a></li>
<li><a href="#97.4.0">GetEventActions</a></li>
<li><a href="#98.4.0">GetInputValue</a></li>
<li><a href="#99.4.0">GetJavascriptCheckedState</a></li>
<li><a href="#100.4.0">GetJavascriptConnectionAction</a></li>
<li><a href="#101.4.0">GetJavascriptInputValue</a></li>
<li><a href="#102.4.0">GetJavascriptSetCheckedState</a></li>
<li><a href="#103.4.0">GetJavascriptSetInputProperty</a></li>
<li><a href="#104.4.0">GetJavascriptValidations</a></li>
<li><a href="#106.4.0">HandleEvent</a></li>
<li><a href="#107.4.0">LoadInputValues</a></li>
<li><a href="#108.4.0">PageHead</a></li>
<li><a href="#109.4.0">PageLoad</a></li>
<li><a href="#110.4.0">PageUnload</a></li>
<li><a href="#111.4.0">ParseNewInputFormat</a></li>
<li><a href="#112.4.0">PostMessage</a></li>
<li><a href="#113.4.0">ReplyMessage</a></li>
<li><a href="#114.4.0">SetInputProperty</a></li>
<li><a href="#115.4.0">SetSelectOptions</a></li>
<li><a href="#116.4.0">ValidateInput</a></li>
<li><a href="#117.4.0">WasSubmitted</a></li>
</ul>
</ul>
<li><a href="#118.2.2">Available custom input plug-ins classes</a></li>
<ul>
<li><a href="#119.3.1">form_ajax_submit_class</a></li>
<li><a href="#136.3.2">form_animation_class</a></li>
<li><a href="#144.3.3">form_auto_complete_class</a></li>
<li><a href="#148.3.4">form_captcha_class</a></li>
<li><a href="#152.3.5">form_crud_class</a></li>
<ul>
<li><a href="#155.4.1">form_crud_data_source_class</a></li>
</ul>
<li><a href="#167.3.6">form_date_class</a></li>
<li><a href="#170.3.7">form_html_editor_class</a></li>
<li><a href="#174.3.8">form_layout_paged_class</a></li>
<li><a href="#179.3.9">form_layout_vertical_class</a></li>
<li><a href="#183.3.10">form_linked_select_class</a></li>
<li><a href="#186.3.11">form_list_select_class</a></li>
<li><a href="#190.3.12">form_map_location_class</a></li>
<li><a href="#198.3.13">form_mdb2_auto_complete_class</a></li>
<li><a href="#200.3.14">form_mdb2_linked_select_class</a></li>
<li><a href="#202.3.15">form_metabase_auto_complete_class</a></li>
<li><a href="#204.3.16">form_metabase_linked_select_class</a></li>
<li><a href="#206.3.17">form_mysql_auto_complete_class</a></li>
<li><a href="#208.3.18">form_mysql_linked_select_class</a></li>
<li><a href="#210.3.19">form_recaptcha_class</a></li>
<li><a href="#214.3.20">form_scaffolding_class</a></li>
<li><a href="#222.3.21">form_secure_submit_class</a></li>
<li><a href="#226.3.22">form_upload_progress_class</a></li>
</ul>
</ul>
</ul>
</ul>
<hr />
<ul>
<h2><li><a name="2.1.1">Summary</a></li></h2>
<ul>
<h3>Name</h3>
<p>Forms class</p>
<h3>Purpose</h3>
<p>Class for generation and validation of HTML Forms.</p>
<h3>Author</h3>
<p>Manuel Lemos (<a href="mailto:mlemos-at-acm.org">mlemos-at-acm.org</a>)</p>
<h3>Files</h3>
<p><tt>forms.php</tt></p>
</ul>
<h2><li><a name="3.1.2">Methods</a></li></h2>
<ul>
<h3><a name="4.2.0">AddDataPart</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddDataPart($data)</tt></p>
<h4>Purpose</h4>
<p>Add arbitrary data to the output that is generated for the form with the <tt>Output</tt> method. Usually this method is used to add the HTML code that will define the layout of the form, but it could be anything else as programmer defined Javascript code.</p>
<h4>Usage</h4>
<p>The <tt>$data</tt> argument is a text string that contains the data to be added to the form output.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="5.2.0">AddFunction</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddFunction($arguments)</tt></p>
<h4>Purpose</h4>
<p>Add the definition of a Javascript function that is meant to be generated as part of the output of the form with the <tt>Output</tt> method. The function to be generated is meant to execute actions related with the elements of the form.</p>
<p>The function may be called from an event handler associated with any element of the page. For instance, the function may be called from the page <tt>&lt;BODY&gt;</tt> <tt>ONLOAD</tt> event handler to activate a give input field when the page is loaded.</p>
<h4>Usage</h4>
<p>The <tt>$arguments</tt> argument is an associative array that takes pairs of tag names and values that define the properties of the function to be added to the form output.</p>
<p>The <tt>$error</tt> 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.</p>
<h4><a name="6.3.0">Arguments</a></h4>
<ul>
<p><tt><li><a name="7.4.1">Element</a></li></tt> (required)</p>
<p>Identifier of the input field to be associated with the function. The field must have been previously added to the form output with the <tt>AddInputPart</tt> method.</p>
<p><tt><li><a name="7.4.2">Function</a></li></tt> (required)</p>
<p>Name of the function to be added.</p>
<p><tt><li><a name="7.4.3">Type</a></li></tt> (required)</p>
<p>Type of the action that the function is meant to perform when executed. Not all types of actions supported by the class are supported by all browsers. However, this class generates conditional code in such way, that if the specified action is not supported by a browser, no Javascript errors will occur as the code is not run.</p>
<p>Supported function types are: <tt>focus</tt> to activate the input of the given field, <tt>select</tt> to select all the text in a <tt>text</tt> input field, <tt>select_focus</tt> to activate and select the text of the field, <tt>disable</tt> to prevent the field to receive user input, <tt>enable</tt> to let the field receive user input, and <tt>markValidated</tt> to set the style or CSS class of input depending whether it is valid or not.</p>
</ul>
</ul>
<h3><a name="AddInput"></a><a name="7.2.0">AddInput</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddInput($arguments)</tt></p>
<h4>Purpose</h4>
<p>Add an input field to the form definition.</p>
<h4>Usage</h4>
<p>The <tt>$arguments</tt> argument is an associative array that takes pairs of tag names and values that define the properties of the input field to be added to the form definition.</p>
<p>The <tt>$error</tt> 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.</p>
<h4><a name="8.3.0">Arguments</a></h4>
<ul>
<p><tt><li><a name="9.4.1">ACCEPT</a></li></tt></p>
<p>MIME file types to be accepted by the <tt>file</tt> fields as defined for the <tt>ACCEPT</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.2">ACCESSKEY</a></li></tt></p>
<p>Key to be associated as shortcut to activate the given input field for keyboard control. The shortcut key may also be defined with the function <a href="#AddLabelPart">AddLabelPart</a> but for input fields without a label the shortcut key has to be defined with <a href="#AddInput">AddInput</a> function.</p>
<p><tt><li><a name="9.4.3">ALT</a></li></tt></p>
<p>Alternative text argument for <tt>image</tt> fields as defined for the <tt>ALT</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.4">ALIGN</a></li></tt></p>
<p>Alignment argument for <tt>image</tt> fields as defined for the <tt>ALIGN</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.5">ApplicationData</a></li></tt></p>
<p>Arbitrary application defined data.</p>
<p><tt><li><a name="9.4.6">CHECKED</a></li></tt></p>
<p>Flag argument for <tt>radio</tt> and <tt>checkbox</tt> fields as defined for the <tt>CHECKED</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.7">CLASS</a></li></tt></p>
<p>Name of the presentation style class with which the input field should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.</p>
<p><tt><li><a name="9.4.8">COLS</a></li></tt></p>
<p>Number of columns of a <tt>textarea</tt> field as defined for the <tt>COLS</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.9">Content</a></li></tt></p>
<p>HTML content to display in input buttons of type <tt>submit</tt>, <tt>reset</tt> and <tt>button</tt>. When this option is defined, the input is rendered with the HTML <tt>BUTTON</tt> tags instead of <tt>INPUT</tt> tags.</p>
<p><tt><li><a name="9.4.10">DisableResubmitCheck</a></li></tt></p>
<p>Boolean flag that indicates whether the Javascript code to avoid form resubmission should not be generated for submit type inputs.</p>
<p><tt><li><a name="9.4.11">ID</a></li></tt></p>
<p>Identifier of the field as defined for the <tt>ID</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag. This attribute is required if the <tt>NAME</tt> attribute is missing. The <tt>ID</tt> is used as unique reference to the input fields in the class if the <tt>NAME</tt> is missing.</p>
<p><tt><li><a name="9.4.12">IgnoreAnonymousSubmitCheck</a></li></tt></p>
<p>Boolean flag that indicates whether calls to the <tt>WasSubmitted</tt> function, without specifying an input to check, should ignore this input when checking whether it was submitted.</p>
<p><tt><li><a name="9.4.13">InvalidCLASS</a></li></tt></p>
<p>Name of the CSS class used to render the input when it is invalid.</p>
<p>The specified value replaces the input CSS class attribute when it is listed in the <tt>Invalid</tt> forms class variable.</p>
<p>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.</p>
<p><tt><li><a name="9.4.14">InvalidSTYLE</a></li></tt></p>
<p>CSS style attributes used to render the input when it is invalid.</p>
<p>The specified styles are merged with the input default CSS style attributes when it is listed in the <tt>Invalid</tt> forms class variable.</p>
<p>The specified CSS attributes are also used to replace there input CSS attributes, when the form is validated on the client side using Javascript.</p>
<p><tt><li><a name="9.4.15">LABEL</a></li></tt></p>
<p>Default data value that is outputted as the definition of the input label. See the function <a href="#AddLabelPart">AddLabelPart</a> for more information.</p>
<p><tt><li><a name="9.4.16">LabelCLASS</a></li></tt></p>
<p>Name of the presentation style class with which the label associated to this input field should be rendered. Using this attribute implies that you have defined the specified style class in the appropriate places of the HTML page.</p>
<p><tt><li><a name="9.4.17">LabelExtraAttributes</a></li></tt></p>
<p>Associative array with a list of extra attributes that should be added to the input label HTML tag when the form output is generated.</p>
<p><tt><li><a name="9.4.18">LabelID</a></li></tt></p>
<p>Identifier of the label document element associated to this input field as defined for the <tt>ID</tt> attribute of the <tt>&lt;LABEL&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.19">LabelSTYLE</a></li></tt></p>
<p>Definition of the presentation style attributes with which the label associated to this input field should be rendered.</p>
<p><tt><li><a name="9.4.20">LabelTITLE</a></li></tt></p>
<p>Label title text as defined for the <tt>TITLE</tt> attribute of the <tt>&lt;LABEL&gt;</tt> HTML tag. Usually browsers present this text as tool tip that appears when the user leaves the mouse pointer stopped over the label.</p>
<p><tt><li><a name="9.4.21">MAXLENGTH</a></li></tt></p>
<p>Maximum number of characters that a <tt>text</tt>, <tt>password</tt> or <tt>file</tt> field may contain as defined for the <tt>MAXLENGTH</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag. The <tt>LoadInputValues</tt> class function enforces this limit on the server side.</p>
<p><tt><li><a name="9.4.22">MULTIPLE</a></li></tt></p>
<p>Flag argument for <tt>select</tt> and <tt>checkbox</tt> fields. The meaning of this argument is the same for <tt>select</tt> as defined for the <tt>MULTIPLE</tt> attribute of the <tt>&lt;SELECT&gt;</tt> HTML tag. For <tt>checkbox</tt> fields, the use of this argument indicates that that the field belongs to a group of <tt>checkbox</tt> fields with the same <tt>NAME</tt> attribute value that should be validated together.</p>
<p><tt><li><a name="9.4.23">NAME</a></li></tt></p>
<p>Name of the field as defined for the <tt>NAME</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag. This attribute is optional if the ID attribute is specified. The <tt>NAME</tt> is used as unique reference to the input fields in the class if the <tt>ID</tt> is missing.</p>
<p><tt><li><a name="9.4.24">NoParent</a></li></tt></p>
<p>Boolean flag that indicates whether the input should be considered independent when it is added by custom inputs.</p>
<p><tt><li><a name="9.4.25">ONBLUR</a></li></tt></p>
<p><tt><li><a name="9.4.26">ONCHANGE</a></li></tt></p>
<p><tt><li><a name="9.4.27">ONCLICK</a></li></tt></p>
<p><tt><li><a name="9.4.28">ONDBLCLICK</a></li></tt></p>
<p><tt><li><a name="9.4.29">ONFOCUS</a></li></tt></p>
<p><tt><li><a name="9.4.30">ONKEYDOWN</a></li></tt></p>
<p><tt><li><a name="9.4.31">ONKEYPRESS</a></li></tt></p>
<p><tt><li><a name="9.4.32">ONKEYUP</a></li></tt></p>
<p><tt><li><a name="9.4.33">ONMOUSEDOWN</a></li></tt></p>
<p><tt><li><a name="9.4.34">ONMOUSEMOVE</a></li></tt></p>
<p><tt><li><a name="9.4.35">ONMOUSEOUT</a></li></tt></p>
<p><tt><li><a name="9.4.36">ONMOUSEOVER</a></li></tt></p>
<p><tt><li><a name="9.4.37">ONMOUSEUP</a></li></tt></p>
<p><tt><li><a name="9.4.38">ONSELECT</a></li></tt></p>
<p>Client side script commands to execute when the field value changes as defined for the event handling definition attribute of the same name of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.39">OPTIONS</a></li></tt></p>
<p>Associative array that defines the values and text of a select field as defined for the <tt>OPTION</tt> HTML tag.</p>
<p><tt><li><a name="9.4.40">ROWS</a></li></tt></p>
<p>Number of rows of a <tt>textarea</tt> field as defined for the <tt>COLS</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.41">SELECTED</a></li></tt></p>
<p>Flag argument for <tt>select</tt> fields that indicates the value of an option is to appear selected as defined for the <tt>SELECTED</tt> attribute of the <tt>&lt;OPTION&gt;</tt> HTML tag. If the <tt>select</tt> field is of type <tt>MULTIPLE</tt>, the <tt>SELECTED</tt> argument should be an array with the values of the options that should be pre-selected.</p>
<p><tt><li><a name="9.4.42">SIZE</a></li></tt></p>
<p>Number of characters that a <tt>text</tt> field displays at once as defined for the <tt>SIZE</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.43">SRC</a></li></tt></p>
<p>URL argument for <tt>image</tt> fields as defined for the <tt>SRC</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.44">STYLE</a></li></tt></p>
<p>Definition of the presentation style attributes with which the input field should be rendered.</p>
<p><tt><li><a name="9.4.45">TABINDEX</a></li></tt></p>
<p>Number that defines the order position of the field in the sequence of fields that are activated when the <tt>TAB</tt> key is used as defined for the <tt>TABINDEX</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag.</p>
<p><tt><li><a name="9.4.46">TYPE</a></li></tt> (required)</p>
<p>Type of the field as defined for the <tt>TYPE</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag. Supported input types are: <tt>textarea</tt>, <tt>select</tt>, <tt>text</tt>, <tt>file</tt>, <tt>password</tt>, <tt>checkbox</tt>, <tt>radio</tt>, <tt>submit</tt>, <tt>reset</tt>, <tt>button</tt> and <tt>hidden</tt>.</p>
<p>Additionally, there is a special type named <tt>custom</tt> that should be specified to add custom inputs defined by separate plug-in classes.</p>
<p><tt><li><a name="9.4.47">VALUE</a></li></tt></p>
<p>Default value of a field as defined for the <tt>VALUE</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag. This property is required for <tt>select</tt> type fields and it must have a value that is the index of an entry of the <tt>OPTIONS</tt> property associative array.</p>
<p><tt><li><a name="9.4.48">Accessible</a></li></tt></p>
<p>Boolean flag that determines whether the field should outputted as an accessible input when it is added to the form output definition with the <tt>AddInputPart</tt> function.</p>
<p>If this flag is set to <tt>0</tt>, the field is outputted as text that represents its current state or value, preserving the presentation style defined by the <tt>STYLE</tt> and <tt>CLASS</tt> attributes.</p>
<p>If this flag is set to <tt>1</tt>, the field is outputted as an usual accessible input, regardless of the value of the form <tt>ReadOnly</tt> flag. If the field <tt>Accessible</tt> property is not specified, the form <tt>ReadOnly</tt> flag value is considered to determine how the field is outputted.</p>
<p><tt><li><a name="9.4.49">Capitalization</a></li></tt></p>
<p>Type of case conversion that is meant to be done on the field text value. If the argument value is <tt>lowercase</tt> the text is converted to lower case. If the argument value is <tt>uppercase</tt> the text is converted to upper case. If the argument value is <tt>words</tt> the first letter of each word is converted to upper case and the other letters are converted to lower case.</p>
<p><tt><li><a name="9.4.50">ClientScript</a></li></tt></p>
<p>Javascript code to be inserted when the field is added to the form output. The argument should be a string that may have line breaking or other types of white space characters. It may be used to define functions to perform custom validation or event handling.</p>
<p><tt><li><a name="9.4.51">CustomClass</a></li></tt></p>
<p>Name of a class that implements the behavior of a custom input implemented as a separate plug-in.</p>
<p><tt><li><a name="9.4.52">DependentValidation</a></li></tt></p>
<p>Identifier of another input that determines whether the validation of the current input will be performed depending on the state of the other input.</p>
<p>If the other input check state is true, the current input will be validated. Otherwise, the current input validation will be skipped.</p>
<p>The other input must support checking its state. So it must be of the type <tt>checkbox</tt>, <tt>radio</tt>, or <tt>custom</tt>.</p>
<p><tt><li><a name="9.4.53">DiscardInvalidValues</a></li></tt></p>
<p>Flag argument that indicates whether invalid values should be discarded when the function <tt>LoadInputValues</tt> is called.</p>
<p>This is meant to help preventing security exploits performed by attackers that may spoof values passed in fields that usually are not editable by real users, like for instance context values passed in hidden fields.</p>
<p>If this argument is <tt>1</tt>, the inputs are validated from within the <tt>LoadInputValues</tt> function. If the submitted values are invalid, it is ignored and the input default values are restored.</p>
<p>If the argument is <tt>0</tt>, validation is only performed when the <tt>Validate</tt> function is called. In the case of the <tt>select</tt> type inputs, invalid option values that may have been submitted are not discarded by the <tt>LoadInputValues</tt> function.</p>
<p><tt><li><a name="9.4.54">EncodedField</a></li></tt></p>
<p>Identifier of the field that will hold the result of the encoding of the value of a <tt>password</tt> field. If this argument is specified the password field value is cleared after storing the encoded value in the given field. Usually, this field is of type <tt>hidden</tt>.</p>
<p><tt><li><a name="9.4.55">Encoding</a></li></tt></p>
<p>Name of the Javascript function to be called to encode a password field when a form is submitted.</p>
<p><tt><li><a name="9.4.56">EncodingFunctionScriptFile</a></li></tt></p>
<p>URL of an external Javascript file that needs to be loaded from within the form HTML output to include the definition of the <tt>Encoding</tt> function.</p>
<p><tt><li><a name="9.4.57">EncodingFunctionVerification</a></li></tt></p>
<p>A Javascript expression (function call or variable) that should be used if function defined by the <tt>Encoding</tt> argument is available. This argument may be used in the case that the <tt>Encoding</tt> function is meant to be loaded from an external Javascript file and that file may only be loaded in some browser versions.</p>
<p><tt><li><a name="9.4.58">ExtraAttributes</a></li></tt></p>
<p>List of extra attributes that should be added to the field's HTML tag when the form output is generated. These extra attributes are ignored if the field is added to the form output as a hidden input part with the <tt>AddInputHiddenPart</tt> class function.</p>
<p>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.</p>
<p><tt><li><a name="9.4.59">PLACEHOLDER</a></li></tt></p>
<p>Text to be displayed in a text input until it has any input text.</p>
<p><tt><li><a name="9.4.60">ReadOnlyMark</a></li></tt></p>
<p>Mark that should be outputted in the place of the field when the form is displayed as read-only or when the field is set as not accessible. If this argument is not specified, it is displayed the current field value.</p>
<p>The read-only mark is outputted without being encoded, so it can include actual HTML markup to display images or other types of marks instead of the submitted field values.</p>
<p>This is useful for instance to mask password values or display nice alternate images for read-only radio buttons or checkboxes.</p>
<p>Notice that this mark data is not encoded by this class when it is outputted as part of the form output. Therefore, be careful when using data for the mark that is submitted by the user or other untrusted external data source, as it may contain tags that may open the potential security abuse with cross-site scripting exploits.</p>
<p><tt><li><a name="9.4.61">ReadOnlyMarkUnchecked</a></li></tt></p>
<p>Mark that should be outputted in the place of a <tt>radio</tt> or <tt>checkbox</tt> field when it is not checked and the form is displayed as read-only or when the field is set as not accessible.</p>
<p>Notice that this mark data is not encoded by this class when it is outputted as part of the form output. Therefore, be careful when using data for the mark that is submitted by the user or other untrusted external data source, as it may contain tags that may open the potential security abuse with cross-site scripting exploits.</p>
<p><a name="ReplacePatterns"></a><tt><li><a name="9.4.62">ReplacePatterns</a></li></tt></p>
<p>List of transformations that may be applied to a text input value when it is changed by the user. The transformations are defined in the form of regular expressions patterns that define the form of the text that should be searched and the corresponding replacement expressions.</p>
<p>The transformations may occur on the server side when the class function <tt>LoadInputValues</tt> is called. The transformations may also occur on the client side if the user browser has enabled Javascript with regular expression based text replacement support. The generated form Javascript code automatically detects whether client side transformations can be applied.</p>
<p>The transformations list should be defined as an associative array with the search regular expressions as array entry indexes and the replacement text as array entry values.</p>
<p>It is beyond the scope of this document to give a full explanation of how regular expressions work and their syntax. You may want to study the PHP function <tt><a href="http://www.php.net/ereg_replace">ereg_replace</a></tt> to learn the syntax of search and replacement regular expressions.</p>
<p>In general terms you should know that the parts of the text input value that match the search regular expression are substituted by the replacement expression.</p>
<p>The replacement expression may contain place holders that will be substituted by matching parts of the original value. Place holders are specified by a backslash character \ followed by the number of the part of the original value. A matching part is denoted in the search regular expression by enclosing its definition within brackets ( ) .</p>
<p>Given this, \1 in the replacement expression represents the first search match text, \2 the second, \3 the third and so on up to \9.</p>
<p>Here follows the definition of a few examples of useful replacement expressions:</p>
<pre style="background-color: #ddddcc; ">
&quot;ReplacePatterns&quot;=&gt;array(
/*
* trim whitespace at the beginning of the text value
*/
&quot;^\\s+&quot;=&gt;&quot;&quot;,
/*
* trim whitespace at the end of the text value
*/
&quot;\\s+\$&quot;=&gt;&quot;&quot;,
/*
* Prepend the text http:// in values that start with www.
*/
&quot;^([wW]{3}.)&quot;=&gt;&quot;http://\\1&quot;
)
</pre>
<p><tt><li><a name="9.4.63">ReplacePatternsOnlyOnClientSide</a></li></tt></p>
<p>When this option is specified the action of replacing patterns, defined by the <a href="#ReplacePatterns">ReplacePatterns</a> attribute, is only performed on the client side with the Javascript code generated by the class within the form HTML output.</p>
<p><tt><li><a name="9.4.64">ReplacePatternsOnlyOnServerSide</a></li></tt></p>
<p>When this option is specified the action of replacing patterns, defined by the <a href="#ReplacePatterns">ReplacePatterns</a> 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.</p>
<p><tt><li><a name="9.4.65">SubForm</a></li></tt></p>
<p>Name of the sub-form within which the field is contained. When the user presses a <tt>submit</tt> 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.</p>
<p>If the <tt>submit</tt> button that is pressed is not contained in any sub-form or the form is submitted in any way other than using a <tt>submit</tt> button, the values of all the fields in the form are subject of validation.</p>
<p><tt><li><a name="9.4.66">TITLE</a></li></tt></p>
<p>Input title text as defined for the <tt>TITLE</tt> attribute of the <tt>&lt;INPUT&gt;</tt> HTML tag. Usually browsers present this text as tool tip that appears when the user leaves the mouse pointer stopped over the input.</p>
<p><tt><li><a name="9.4.67">ValidateAsCreditCard</a></li></tt></p>
<p>Type argument that indicates that the field value should be validated as a credit card number. Supported types are: <tt>amex</tt>, <tt>carteblanche</tt>, <tt>dinersclub</tt>, <tt>discover</tt>, <tt>enroute</tt>, <tt>jcb</tt>, <tt>mastercard</tt> and <tt>visa</tt>.</p>
<p>If the argument is set to <tt>unknown</tt>, 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.</p>
<p>If the argument is set to <tt>field</tt>, the class will determine the card type verification to perform according to the value of a given <tt>select</tt> type field defined by the <tt>ValidationCreditCardTypeField</tt> argument.</p>
<p><tt><li><a name="9.4.68">ValidateAsCreditCardErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to contain a credit card number but it is invalid.</p>
<p><tt><li><a name="9.4.69">ValidateAsDifferentFrom</a></li></tt></p>
<p>Name of another field that the field value should be different. This type of validation is useful for <tt>password</tt> reminder fields where the reminder text should not be the same as the password value.</p>
<p><tt><li><a name="9.4.70">ValidateAsDifferentFromErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to be different from another given field value but it is not.</p>
<p><tt><li><a name="9.4.71">ValidateAsDifferentFromText</a></li></tt></p>
<p>Text that the field value should be different. This type of validation is useful rejecting the default value of <tt>select</tt> fields to make the user choose another option explicitly.</p>
<p><tt><li><a name="9.4.72">ValidateAsDifferentFromTextErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to be different from a given text value but it is not.</p>
<p><tt><li><a name="9.4.73">ValidateAsEmail</a></li></tt></p>
<p>Flag argument that indicates that the field value should be validated as an e-mail address.</p>
<p><tt><li><a name="9.4.74">ValidateAsEmailErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to contain an e-mail address but it is invalid.</p>
<p><tt><li><a name="9.4.75">ValidateAsEqualTo</a></li></tt></p>
<p>Name of another field that the field value should be equal to. This type of validation is useful for <tt>password</tt> confirmation fields.</p>
<p><tt><li><a name="9.4.76">ValidateAsEqualToErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to be equal to another given field value but it is not.</p>
<p><tt><li><a name="9.4.77">ValidateAsFloat</a></li></tt></p>
<p>Flag argument that indicates that the field value should be validated to verify that it contains a valid floating point number.</p>
<p><tt><li><a name="9.4.78">ValidateAsFloatErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to be a valid floating point number but it is not.</p>
<p><tt><li><a name="9.4.79">ValidateAsInteger</a></li></tt></p>
<p>Flag argument that indicates that the field value should be validated to verify that it contains a valid integer number.</p>
<p><tt><li><a name="9.4.80">ValidateAsIntegerErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to be a valid integer number but it is not.</p>
<p><tt><li><a name="9.4.81">ValidateAsNotEmpty</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="9.4.82">ValidateAsNotEmptyErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value is meant to not be empty but it is not.</p>
<p><tt><li><a name="9.4.83">ValidateAsNotRegularExpression</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="9.4.84">ValidateAsNotRegularExpressionErrorMessage</a></li></tt></p>
<p>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 <tt>ValidateAsNotRegularExpression</tt> parameter is an array of regular expressions. In that case this parameter should be an array with an equal number of error messages.</p>
<p><tt><li><a name="9.4.85">ValidateAsSet</a></li></tt></p>
<p>Flag argument that indicates that at least one option of a <tt>multiple</tt> <tt>select</tt> type field, or one of a <tt>radio</tt> type field of the same group of the field being defined, or a <tt>checkbox</tt> should be set.</p>
<p><tt>radio</tt> and <tt>checkbox</tt> fields should be set to the same <tt>NAME</tt> attribute value to be considered of the same group, but should have different <tt>ID</tt> attribute values.</p>
<p><tt>checkbox</tt> fields of the same group should also be defined setting <tt>MULTIPLE</tt> attribute to indicate that they belong to a group and at least one of the group fields should be checked.</p>
<p><tt><li><a name="9.4.86">ValidateAsSetErrorMessage</a></li></tt></p>
<p>Error message to be used when on <tt>select</tt> option or a <tt>radio</tt> or <tt>checkbox</tt> field value is meant to be set but it is not.</p>
<p><tt><li><a name="9.4.87">ValidationErrorMessage</a></li></tt></p>
<p>Default error message to be used when no validation type specific message is defined.</p>
<p><tt><li><a name="9.4.88">ValidateMinimumLength</a></li></tt></p>
<p>Integer argument that indicates the minimum length of the field value in number of characters.</p>
<p><tt><li><a name="9.4.89">ValidateMinimumLengthErrorMessage</a></li></tt></p>
<p>Error message to be used when the field value length is less than the specified by the <tt>ValidateMinimumLength</tt> option.</p>
<p><tt><li><a name="9.4.90">ValidateOnlyOnClientSide</a></li></tt></p>
<p>When this option is specified the validation checks that would be done by the <tt>Validate</tt> function for this input are not performed.</p>
<p><tt><li><a name="9.4.91">ValidateOnlyOnServerSide</a></li></tt></p>
<p>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 <tt>Output</tt> function.</p>
<p><tt><li><a name="9.4.92">ValidateOptionalValue</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="9.4.93">ValidateRegularExpression</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="9.4.94">ValidateRegularExpressionErrorMessage</a></li></tt></p>
<p>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 <tt>ValidateRegularExpression</tt> parameter is an array of regular expressions. In that case this parameter should be an array with an equal number of error messages.</p>
<p><tt><li><a name="9.4.95">ValidationClientFunction</a></li></tt></p>
<p>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 <tt>true</tt> if the field value is valid.</p>
<p><tt><li><a name="9.4.96">ValidationClientFunctionErrorMessage</a></li></tt></p>
<p>Error message to be used when the client side validation function returns false.</p>
<p><tt><li><a name="9.4.97">ValidationCreditCardTypeField</a></li></tt></p>
<p>Name of the <tt>select</tt> type field that defines the credit card type to be assumed when the <tt>ValidationAsCreditCard</tt> argument is set to <tt>field</tt>.</p>
<p><tt><li><a name="9.4.98">ValidationDecimalPlaces</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="9.4.99">ValidationLowerLimit</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="9.4.100">ValidationServerFunction</a></li></tt></p>
<p>Function to be called to validate the field value on the server side. It may be a string with the name of a global function, or a form of defining a callable function of an object, static class function or an anonymous function. The field value is passed as argument to that function. It should return <tt>true</tt> if the field value is valid.</p>
<p><tt><li><a name="9.4.101">ValidationServerFunctionErrorMessage</a></li></tt></p>
<p>Error message to be used when the server side validation function returns false.</p>
<p><tt><li><a name="9.4.102">ValidationUpperLimit</a></li></tt></p>
<p>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.</p>
</ul>
</ul>
<h3><a name="9.2.0">AddHiddenInputs</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddHiddenInputs($inputs)</tt></p>
<h4>Purpose</h4>
<p>Add a set of hidden input fields to the form definition.</p>
<h4>Usage</h4>
<p>The <tt>$inputs</tt> 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 <tt>$inputs</tt> array indicates the name of the input field. The respective array entry value indicates the initial value of the input field.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="10.2.0">AddHiddenInputsParts</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddHiddenInputs($inputs)</tt></p>
<h4>Purpose</h4>
<p>Add a set of hidden input fields to the output that is generated for the form with the <tt>Output</tt> method.</p>
<h4>Usage</h4>
<p>The <tt>$inputs</tt> 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 <tt>$inputs</tt> 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.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="11.2.0">AddInputHiddenPart</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddInputHiddenPart($input)</tt></p>
<h4>Purpose</h4>
<p>Add a field input to the output that is generated for the form with the <tt>Output</tt> method as if it was a <tt>hidden</tt> field.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument is the identifier of the field to be added to the form output.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="12.2.0">AddInputPart</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddInputPart($input)</tt></p>
<h4>Purpose</h4>
<p>Add an input field to the output that is generated for the form with the <tt>Output</tt> method.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument is the identifier of the field to be added to the form output.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="13.2.0">AddInputReadOnlyPart</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddInputReadOnlyPart($input)</tt></p>
<h4>Purpose</h4>
<p>Add a field input to the output that is generated for the form with the <tt>Output</tt> 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.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument is the identifier of the field to be added to the form output.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="AddLabelPart"></a><a name="14.2.0">AddLabelPart</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;AddLabelPart($arguments)</tt></p>
<h4>Purpose</h4>
<p>Add a label for an input field to the output that is generated for the form with the <tt>Output</tt> method.</p>
<h4>Usage</h4>
<p>The <tt>$arguments</tt> 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.</p>
<p>The <tt>$error</tt> 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.</p>
<h4><a name="15.3.0">Arguments</a></h4>
<ul>
<p><tt><li><a name="16.4.1">ACCESSKEY</a></li></tt></p>
<p>Key to be associated as shortcut to activate the given input field for keyboard control as defined for the <tt>ACCESSKEY</tt> attribute of the <tt>&lt;LABEL&gt;</tt> 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 <tt>Alt</tt> 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 <a href="#AddInput">AddInput</a> function.</p>
<p><tt><li><a name="16.4.2">CLASS</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="16.4.3">FOR</a></li></tt></p>
<p>Identifier of the input field to which the label is meant to be associated as defined by the <tt>ID</tt> argument passed when calling the <tt>AddInput</tt>. That input field has to be added to the form output by calling the <tt>AddInputPart</tt> either before or after calling this method but always before calling the <tt>Output</tt> method.</p>
<p><tt><li><a name="16.4.4">ExtraAttributes</a></li></tt></p>
<p>Associative array with a list of extra attributes that should be added to the label HTML tag when the form output is generated.</p>
<p><tt><li><a name="16.4.5">ID</a></li></tt></p>
<p>Identifier of the label document element as defined for the <tt>ID</tt> attribute of the <tt>&lt;LABEL&gt;</tt> HTML tag.</p>
<p><tt><li><a name="16.4.6">LABEL</a></li></tt></p>
<p>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 <a href="#AddInput">AddInput</a> function.</p>
<p>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.</p>
<p><tt><li><a name="16.4.7">STYLE</a></li></tt></p>
<p>Definition of the presentation style attributes with which the label should be rendered.</p>
<p><tt><li><a name="16.4.8">TITLE</a></li></tt></p>
<p>Label title text as defined for the <tt>TITLE</tt> attribute of the <tt>&lt;LABEL&gt;</tt> HTML tag. Usually browsers present this text as tool tip that appears when the user leaves the mouse pointer stopped over the label.</p>
</ul>
</ul>
<h3><a name="Connect"></a><a name="16.2.0">Connect</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;Connect($from, $to, $event, $action, $context)</tt></p>
<h4>Purpose</h4>
<p>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.</p>
<h4>Usage</h4>
<p>The <tt>$from</tt> argument is the identifier of the connection origin input on which it may occur the trigger event.</p>
<p>The <tt>$to</tt> argument is the identifier of the connection target input that will execute an action after the trigger event occurs in the origin input.</p>
<p>The <tt>$event</tt> 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.</p>
<p>The <tt>$action</tt> 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 <tt>hidden</tt> type.</p>
<p>The <tt>Click</tt> action emulates the same effect of an user clicking in the target input. The <tt>Focus</tt> action gives the focus to the target input. The <tt>Select</tt> action selects all the text of a text target input. The <tt>Enable</tt> action enables the target input. The <tt>Disable</tt> action disables the target input. The <tt>MarkValidated</tt> action sets the style or CSS class of input depending whether it is valid or not.</p>
<p>Custom input types may support other types of actions.</p>
<p>The <tt>$context</tt> 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 <tt>$context</tt> argument may be an empty array.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="ConnectFormToInput"></a><a name="17.2.0">ConnectFormToInput</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;ConnectFormToInput($input, $event, $action, $context)</tt></p>
<h4>Purpose</h4>
<p>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.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument is the identifier of the connection target input that will execute an action after the trigger event occurs in the form.</p>
<p>The <tt>$event</tt> argument is the name of event that may occur in the form in the client side. Currently, the supported events are: <tt>ONSUBMIT</tt> for when the form is submitted but before validation or any other action occurs, <tt>ONSUBMITTING</tt> for when the the form is submitted but after validation or other any actions occurs, <tt>ONRESET</tt> for when the form is reset, <tt>ONLOAD</tt> for when the form page is loaded, <tt>ONUNLOAD</tt> for when the form page is unloaded, and <tt>ONERROR</tt> when a validation error occurred.</p>
<p>The <tt>$action</tt> 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 <tt>hidden</tt> type.</p>
<p>The <tt>Click</tt> action emulates the same effect of an user clicking in the target input. The <tt>Focus</tt> action gives the focus to the target input. The <tt>Select</tt> action selects all the text of a text target input. The <tt>Enable</tt> action enables the target input. The <tt>Disable</tt> action disables the target input. Custom input types may support other types of actions.</p>
<p>The <tt>$context</tt> 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 <tt>$context</tt> argument should be an empty array.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="18.2.0">DisplayOutput</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;DisplayOutput()</tt></p>
<h4>Purpose</h4>
<p>Output the HTML generate for the form.</p>
<h4>Usage</h4>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="19.2.0">EncodeJavascriptString</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$encoded=$my_form_object-&gt;EncodeJavascriptString($string)</tt></p>
<h4>Purpose</h4>
<p>Encode a string value for use as a string expression in Javascript code.</p>
<h4>Usage</h4>
<p>The <tt>$string</tt> argument specifies the string value to be encoded.</p>
<p>The <tt>$encoded</tt> return value is a string that defines a Javascript string expression that represents the encoded string value.</p>
</ul>
<h3><a name="20.2.0">EndLayoutCapture</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;EndLayoutCapture()</tt></p>
<h4>Purpose</h4>
<p>Stop capturing the current script output to compose the form layout.</p>
<h4>Usage</h4>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="21.2.0">FetchOutput</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$output=$my_form_object-&gt;FetchOutput()</tt></p>
<h4>Purpose</h4>
<p>Fetch the generated form output into a string.</p>
<h4>Usage</h4>
<p>The <tt>$output</tt> return value contains a string that contains the generated form output. If there was an error, an empty string is returned.</p>
</ul>
<h3><a name="22.2.0">FlagInvalidInput</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$sub_form=$my_form_object-&gt;FlagInvalidInput($input, $error)</tt></p>
<h4>Purpose</h4>
<p>Flag a given input as invalid.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument specifies the identifier of the input to be flagged as invalid.</p>
<p>The <tt>$error</tt> argument specifies the validation error message to associate to the invalid input.</p>
<p>The <tt>$sub_form</tt> return value is a string of the sub-form that the flagged input belongs.</p>
</ul>
<h3><a name="23.2.0">GetFileValues</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$name=$my_form_object-&gt;GetFileValues($input,$values)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the values that identify a file uploaded when the form is submitted.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the file field from which the values are meant to be retrieved.</p>
<p>The <tt>$values</tt> 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:</p>
<ul>
<li><tt>name </tt> - name of the file</li><li><tt>tmp_name</tt> - path of a temporary file that holds the file contents.</li><li><tt>type </tt> - MIME content type of the file</li><li><tt>size </tt> - size of the file</li></ul>
<p>The return value <tt>$name</tt> 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.</p>
</ul>
<h3><a name="25.2.0">GetCheckable</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;GetCheckable($input, $checkable)</tt></p>
<h4>Purpose</h4>
<p>Return the information of whether a given input can be treated like a <tt>checkbox</tt> or <tt>radio</tt> so its state can be checked or unchecked.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the input to be queried.</p>
<p>The return <tt>$error</tt> value is a string value that indicates whether there was an error, eventually because it is a custom input that does not implement the <tt>GetCheckable</tt> function.</p>
</ul>
<h3><a name="26.2.0">GetCheckedRadio</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$input=$my_form_object-&gt;GetCheckedRadio($name)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the form radio input of a given name that is currently checked.</p>
<h4>Usage</h4>
<p>The <tt>$name</tt> argument defines the name of the radio inputs that should be looked up to see which one is checked.</p>
<p>The return <tt>$input</tt> 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.</p>
</ul>
<h3><a name="27.2.0">GetCheckedRadioValue</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$value=$my_form_object-&gt;GetCheckedRadioValue($name,$default)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the value of the form radio input of a given name that is currently checked.</p>
<h4>Usage</h4>
<p>The <tt>$name</tt> argument defines the name of the radio inputs that should be looked up to see which one is checked.</p>
<p>The <tt>$default</tt> 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.</p>
<p>The return <tt>$value</tt> 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 <tt>$default</tt> argument.</p>
</ul>
<h3><a name="28.2.0">GetCheckedState</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$checked=$my_form_object-&gt;GetCheckedState($input)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the current checked state of a radio or checkbox input.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the input to determine its checked state.</p>
<p>The return <tt>$checked</tt> 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.</p>
</ul>
<h3><a name="29.2.0">GetContainedInputs</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;GetContainedInputs($input, $kind, $contained)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the list of inputs contained within a given input of the form.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the input.</p>
<p>The <tt>$kind</tt> 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.</p>
<p>The <tt>$contained</tt> argument is a reference to a variable that will be assigned by this function to an array of identifier strings of the contained inputs.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="30.2.0">GetInputProperty</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;GetInputProperty($input, $property, $value)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the current value of an input field property.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the field.</p>
<p>The <tt>$property</tt> argument defines the name of the property of the field to be retrieved. Currently supported properties are:</p>
<ul>
<p><li><tt>ApplicationData</tt></li></p>
<p>Arbitrary application defined data.</p>
<p><li><tt>LABEL</tt></li></p>
<p>HTML text value of the input label, if set.</p>
<p><li><tt>SelectedOption</tt></li></p>
<p>Value the option of a <tt>select</tt> input that is currently selected.</p>
<p><li><tt>TYPE</tt></li></p>
<p>Type of the given input.</p>
<p><li><tt>ApplicationData</tt></li></p>
<p>Arbitrary application defined data.</p>
</ul>
<p>The <tt>$value</tt> argument should be a reference to a variable that is assigned by the function to the value of the given field property.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="32.2.0">GetInputValue</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$value=$my_form_object-&gt;GetInputValue($input)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the current value that is set to the given field.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the field from which the value is to be retrieved.</p>
<p>The return <tt>$value</tt> contains the current value of the given field. If the specified input does not exist, the return value is an error string.</p>
</ul>
<h3><a name="33.2.0">GetInputEventURL</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;GetInputEventURL($input, $event, $parameters, $url)</tt></p>
<h4>Purpose</h4>
<p>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.</p>
<p>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.</p>
<p>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 <tt>HandleEvent</tt> method of this class, so the event handling request can be routed to the specified custom input class.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given custom input field.</p>
<p>The <tt>$event</tt> 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.</p>
<p>The <tt>$parameters</tt> 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.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="34.2.0">GetInputs</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$inputs=$my_form_object-&gt;GetInputs($parent)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the list of inputs of the form.</p>
<h4>Usage</h4>
<p>The <tt>$parent</tt> 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.</p>
<p>The <tt>$inputs</tt> return value is an array with the identifiers of the requested inputs.</p>
</ul>
<h3><a name="35.2.0">GetJavascriptCheckedRadioValue</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript_value=$my_form_object-&gt;GetJavascriptCheckedRadioValue($form_object, $name, $default)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression that represents the value of the currently checked <tt>radio</tt> input field with a given name to be used to on client side scripts in Javascript.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the radio input belongs.</p>
<p>The <tt>$name</tt> argument defines the name of the radio inputs that should be looked up to see which one is checked.</p>
<p>The <tt>$default</tt> 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.</p>
<p>The <tt>$javascript_value</tt> return value is a string that represents the value of the checked radio input field in Javascript.</p>
</ul>
<h3><a name="36.2.0">GetJavascriptCheckedState</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript_value=$my_form_object-&gt;GetJavascriptCheckedState($form_object, $input)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression that represents the checked state of a given <tt>checkbox</tt>, <tt>radio</tt>, or <tt>custom</tt> input field to be used to on client side scripts in Javascript.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given input field.</p>
<p>The <tt>$javascript_value</tt> return value is a string that represents the given input field checked state in Javascript.</p>
</ul>
<h3><a name="37.2.0">GetJavascriptConnectionAction</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;GetJavascriptConnectionAction($form_object, $from, $to, $event, $action, $context, $javascript)</tt></p>
<h4>Purpose</h4>
<p>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.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> 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 <tt>NAME</tt> or <tt>ID</tt> class variables, if these variables are not set to empty strings.</p>
<p>The <tt>$from</tt> argument is the identifier of the connection origin input on which it may occur the trigger event.</p>
<p>The <tt>$to</tt> argument is the identifier of the connection target input on which the event action is executed.</p>
<p>The <tt>$event</tt> argument is the name of event that may occur in the connection origin input in the client side (user browser).</p>
<p>The <tt>$action</tt> 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.</p>
<p>The <tt>$context</tt> argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.</p>
<p>The <tt>$javascript</tt> argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h3><a name="38.2.0">GetJavascriptInputObject</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript_object=$my_form_object-&gt;GetJavascriptInputObject($form_object, $input)</tt></p>
<h4>Purpose</h4>
<p>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.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given input field.</p>
<p>The <tt>$javascript_object</tt> return value is a string that represents the given input field Javascript object.</p>
</ul>
<h3><a name="39.2.0">GetJavascriptInputValue</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript_value=$my_form_object-&gt;GetJavascriptInputValue($form_object, $input)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression that represents the value of a given input field to be used to on client side scripts in Javascript.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given input field.</p>
<p>The <tt>$javascript_value</tt> return value is a string that represents the given input field value in Javascript.</p>
</ul>
<h3><a name="40.2.0">GetJavascriptSelectedOption</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript=$my_form_object-&gt;GetJavascriptSelectedOption($form_object, $input)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression that evaluates to the current selected option of a <tt>select</tt> or <tt>custom</tt> input field.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given input field.</p>
<p>The <tt>$javascript</tt> return value is a string with Javascript expression of the input selected option.</p>
</ul>
<h3><a name="41.2.0">GetJavascriptSetCheckedState</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript=$my_form_object-&gt;GetJavascriptSetCheckedState($form_object, $input, $checked)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression to set the checked state of a given <tt>checkbox</tt>, <tt>radio</tt>, or <tt>custom</tt> input field.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given input field.</p>
<p>The <tt>$checked</tt> argument is a string that specifies the Javascript expression to set the given input checked state.</p>
<p>The <tt>$javascript</tt> return value is a string with Javascript statements to set the given input checked state.</p>
</ul>
<h3><a name="42.2.0">GetJavascriptSetFormProperty</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript=$my_form_object-&gt;GetJavascriptSetFormProperty($form_object, $property, $value)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression to assign the value of a form property.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form.</p>
<p>The <tt>$property</tt> argument is a string that specifies the name of the form property to be assigned. Currently, only the property <tt>SubForm</tt>.</p>
<p>The <tt>$value</tt> argument is a string that specifies the Javascript expression to assign to the given form property.</p>
<p>The <tt>$javascript</tt> return value is a string with Javascript statements to assign the given form property.</p>
</ul>
<h3><a name="43.2.0">GetJavascriptSetInputProperty</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript=$my_form_object-&gt;GetJavascriptSetInputProperty($form_object, $input, $property, $value)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression to assign the value of a property of a given input field.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given input field.</p>
<p>The <tt>$property</tt> argument is a string that specifies the name of the input property to be assigned. Currently, only the property <tt>VALUE</tt> is supported for regular input types. Custom inputs may support other properties.</p>
<p>The <tt>$value</tt> argument is a string that specifies the Javascript expression to assign to the given input property.</p>
<p>The <tt>$javascript</tt> return value is a string with Javascript statements to assign the given input property.</p>
</ul>
<h3><a name="44.2.0">GetJavascriptSetInputValue</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript=$my_form_object-&gt;GetJavascriptSetInputValue($form_object, $input, $value)</tt></p>
<h4>Purpose</h4>
<p>Generate a Javascript expression to assign the value of a given input field.</p>
<h4>Usage</h4>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$input</tt> argument is a string that specifies the identifier of the given input field.</p>
<p>The <tt>$value</tt> argument is a string that specifies the Javascript expression to assign to the given input value.</p>
<p>The <tt>$javascript</tt> return value is a string with Javascript statements to assign the given input value.</p>
</ul>
<h3><a name="45.2.0">GetNextMessage</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$has_messages=$my_form_object-&gt;GetNextMessage($message)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the next event message pending on the message queue.</p>
<h4>Usage</h4>
<p>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 <tt>HandleEvent</tt> function is called.</p>
<p>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.</p>
<p>The message queue may hold multiple messages. The <tt>GetNextMessage</tt> function should be called to retrieve and reply to the messages until there are no more queued messages.</p>
<p>The <tt>$message</tt> 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.</p>
<p>The <tt>$has_messages</tt> return value is a boolean flag that indicates whether there were any queued messages.</p>
</ul>
<h3><a name="46.2.0">GetSubmittedValue</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$value=$my_form_object-&gt;GetSubmittedValue($input)</tt></p>
<h4>Purpose</h4>
<p>Retrieve the value of a given input that is being submitted.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the field from which the submitted value is to be retrieved.</p>
<p>The return <tt>$value</tt> contains the current value of the given field. If the specified input does not exist, the return value is an error string.</p>
</ul>
<h3><a name="47.2.0">HandleEvent</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;HandleEvent($processed)</tt></p>
<h4>Purpose</h4>
<p>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.</p>
<p>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.</p>
<h4>Usage</h4>
<p>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.</p>
<p>This function examines the arguments passed to the current page either via a <tt>GET</tt> or <tt>POST</tt> methods to determine whether the current request is for handling an event or for normal form processing.</p>
<p>The <tt>$processed</tt> 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 <tt>1</tt>, or it is a normal form processing access in case it returns <tt>0</tt>.</p>
<p>The <tt>$error</tt> return value contains an error message if the function call did not succeed. Otherwise it contains an empty string.</p>
<p>If the <tt>$processed</tt> argument is set to <tt>1</tt>, or the <tt>$error</tt> is set to a non-empty error message string, the current script should exit immediately. Otherwise, the form processing should proceed normally.</p>
<p>This function examines the request arguments with the names defined by the class variables <tt>event_parameter</tt> and <tt>input_parameter</tt> to determine if the request is for event handling and which custom form input is expected to handle the event.</p>
</ul>
<h3><a name="48.2.0">LoadInputValues</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;LoadInputValues($submitted)</tt></p>
<h4>Purpose</h4>
<p>Set the form fields with values passed to the script by the Web server.</p>
<h4>Usage</h4>
<p>The <tt>$submitted</tt> 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 <tt>checkbox</tt> and <tt>multiple select</tt> fields.</p>
<p>Note: Currently this method is implemented by loading the field values from the global variables <tt>$HTTP_POST_VARS</tt>, or from <tt>$HTTP_GET_VARS</tt> 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 <tt>SetInputValue</tt> method after you call <tt>LoadInputValues</tt>.</p>
<p>Also, if your PHP configuration has the option <tt>magic_quotes_gpc</tt> set to <tt>On</tt>, the <tt>LoadInputValues</tt> method also tries to strip any <tt>'</tt> or <tt>\</tt> 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 <tt>$HTTP_POST_VARS</tt>, <tt>$HTTP_GET_VARS</tt> or global variables from where the input values are loaded. Use the function <tt>GetInputValue</tt> to retrieve the fixed values.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string. This return value may be safely unless the form is using custom input that may trigger error conditions.</p>
</ul>
<h3><a name="49.2.0">Output</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;Output($arguments)</tt></p>
<h4>Purpose</h4>
<p>Generate the output of the form.</p>
<h4>Usage</h4>
<p>The <tt>$arguments</tt> 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.</p>
<p>The <tt>$error</tt> 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.</p>
<h4><a name="50.3.0">Arguments</a></h4>
<ul>
<p><tt><li><a name="51.4.1">EndOfLine</a></li></tt></p>
<p>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.</p>
<p><tt><li><a name="51.4.2">Function</a></li></tt> (required)</p>
<p>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.</p>
</ul>
</ul>
<h3><a name="51.2.0">OutputDebug</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$my_form_object-&gt;OutputDebug($message)</tt></p>
<h4>Purpose</h4>
<p>Output debugging information using the function specified by the <tt>debug</tt> variable, if set.</p>
<h4>Usage</h4>
<p>The <tt>$message</tt> argument is a message string to pass to the debugging function.</p>
</ul>
<h3><a name="52.2.0">PageHead</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$html=$my_form_object-&gt;PageHead()</tt></p>
<h4>Purpose</h4>
<p>Retrieve the HTML code that is necessary to insert in the page head section to make all the form inputs work correctly.</p>
<h4>Usage</h4>
<p>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.</p>
<p>The <tt>$html</tt> return value contains the necessary HTML tags that should be inserted in the page head section.</p>
</ul>
<h3><a name="53.2.0">PageLoad</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript=$my_form_object-&gt;PageLoad()</tt></p>
<h4>Purpose</h4>
<p>Retrieve the Javascript code that is necessary to execute when the page is loaded to make all the form inputs work correctly.</p>
<h4>Usage</h4>
<p>This function is usually called when the <tt>ONLOAD</tt> attribute of the page <tt>BODY</tt> is being defined. It is necessary to call when using certain types of inputs that need special Javascript code to load.</p>
<p>The <tt>$javascript</tt> return value contains the necessary Javascript code that should be used to define the page <tt>BODY</tt> <tt>ONLOAD</tt> tag.</p>
</ul>
<h3><a name="54.2.0">PageUnload</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$javascript=$my_form_object-&gt;PageUnload()</tt></p>
<h4>Purpose</h4>
<p>Retrieve the Javascript code that is necessary to execute when the page is unloaded to make all the form inputs work correctly.</p>
<h4>Usage</h4>
<p>This function is usually called when the <tt>ONUNLOAD</tt> attribute of the page <tt>BODY</tt> is being defined. It is necessary to call when using certain types of inputs that need special Javascript code to load.</p>
<p>The <tt>$javascript</tt> return value contains the necessary Javascript code that should be used to define the page <tt>BODY</tt> <tt>UNONLOAD</tt> tag.</p>
</ul>
<h3><a name="55.2.0">PostMessage</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;PostMessage($message)</tt></p>
<h4>Purpose</h4>
<p>Send a message to the form message queue.</p>
<h4>Usage</h4>
<p>This function is usually called by custom input classes that handle client side events.</p>
<p>The <tt>$message</tt> 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:</p>
<ul>
<li><p><tt>Event</tt></p>
<p>Name of the event associated to this message.</p>
</li><li><p><tt>From</tt></p>
<p>Identifier of the input that is posting the message.</p>
</li><li><p><tt>ReplyTo</tt></p>
<p>Identifier of the input that should handle the reply to the message.</p>
</li><li><p><tt>Target</tt></p>
<p>Identifier of the input that should handle the message. The target input should be a custom input that implements the <tt>PostMessage</tt> function. If this entry is missing, the message should be handled by the application using the <tt>GetNextMessage</tt> function.</p>
</li></ul>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="57.2.0">RemoveFunction</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;RemoveFunction($name)</tt></p>
<h4>Purpose</h4>
<p>Remove a previously added function from the form output to be generated by the <tt>Output</tt> method.</p>
<h4>Usage</h4>
<p>The <tt>$name</tt> argument is the name of the function to be removed from the form output.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="58.2.0">ReplyMessage</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;ReplyMessage($message, $processed)</tt></p>
<h4>Purpose</h4>
<p>Send a reply to the message retrieved from the form message queue.</p>
<h4>Usage</h4>
<p>This function should be called after processing a client side event message retrieved with the <tt>GetNextMessage</tt> function.</p>
<p>The <tt>$message</tt> argument is the same associative array of the message retrieved with the <tt>GetNextMessage</tt> function. It may contain new or altered entries to specify details that may trigger different actions when the message reply is processed.</p>
<p>The <tt>$processed</tt> 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 <tt>1</tt>, or the script may continue with normal form processing in case it returns <tt>0</tt>.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="59.2.0">ResetFormParts</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$my_form_object-&gt;ResetFormParts()</tt></p>
<h4>Purpose</h4>
<p>Reset the definition of the form output as it is initially when the form object is created.</p>
</ul>
<h3><a name="60.2.0">SetCheckedRadio</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$radio=$my_form_object-&gt;SetCheckedRadio($name, $value)</tt></p>
<h4>Purpose</h4>
<p>Set the current checked state of all radio inputs of a given name.</p>
<h4>Usage</h4>
<p>The <tt>$name</tt> argument defines the name of all the radio inputs to check or uncheck.</p>
<p>The <tt>$value</tt> 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.</p>
<p>The <tt>$radio</tt> 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.</p>
</ul>
<h3><a name="61.2.0">SetCheckedState</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;SetCheckedState($input,$checked)</tt></p>
<h4>Purpose</h4>
<p>Set the current checked state of a radio or checkbox input.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the input to be set.</p>
<p>The <tt>$checked</tt> argument is a boolean value that specifies whether the given input is going to be checked or unchecked.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="62.2.0">SetInputProperty</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;SetInputProperty($input, $property, $value)</tt></p>
<h4>Purpose</h4>
<p>Redefine the current value of an input field property.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the field to be set.</p>
<p>The <tt>$property</tt> argument defines the name of the property of the field to be redefined. Currently supported properties are:</p>
<ul>
<p><li><tt>ACCEPT</tt></li></p>
<p><li><tt>ALT</tt></li></p>
<p><li><tt>COLS</tt></li></p>
<p><li><tt>LABEL</tt></li></p>
<p><li><tt>MAXLENGTH</tt></li></p>
<p><tt><li>ONBLUR</li></tt></p>
<p><tt><li>ONCHANGE</li></tt></p>
<p><tt><li>ONCLICK</li></tt></p>
<p><tt><li>ONDBLCLICK</li></tt></p>
<p><tt><li>ONFOCUS</li></tt></p>
<p><tt><li>ONKEYDOWN</li></tt></p>
<p><tt><li>ONKEYPRESS</li></tt></p>
<p><tt><li>ONKEYUP</li></tt></p>
<p><tt><li>ONMOUSEDOWN</li></tt></p>
<p><tt><li>ONMOUSEMOVE</li></tt></p>
<p><tt><li>ONMOUSEOUT</li></tt></p>
<p><tt><li>ONMOUSEOVER</li></tt></p>
<p><tt><li>ONMOUSEUP</li></tt></p>
<p><tt><li>ONSELECT</li></tt></p>
<p><li><tt>ROWS</tt></li></p>
<p><li><tt>SIZE</tt></li></p>
<p><li><tt>SRC</tt></li></p>
<p><li><tt>TABINDEX</tt></li></p>
<p><li><tt>Accessible</tt></li></p>
<p><li><tt>ApplicationData</tt></li></p>
<p><li><tt>Capitalization</tt></li></p>
<p><li><tt>ClientScript</tt></li></p>
<p><li><tt>Content</tt></li></p>
<p><li><tt>DependentValidation</tt></li></p>
<p><li><tt>ReadOnlyMark</tt></li></p>
<p><li><tt>ReadOnlyMarkUnchecked</tt></li></p>
<p><li><tt>SubForm</tt></li></p>
<p><li><tt>VALUE</tt></li></p>
<p><li><tt>ValidationServerFunctionErrorMessage</tt></li></p>
<p><li><tt>STYLE</tt></li></p>
<p><li><tt>CLASS</tt></li></p>
</ul>
<p>The <tt>$value</tt> argument defines the value to be assigned to the given field property.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="64.2.0">SetInputValue</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;SetInputValue($input,$value)</tt></p>
<h4>Purpose</h4>
<p>Redefine the current value of an input field.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the field to be set.</p>
<p>The <tt>$value</tt> argument defines the value to be assigned to the given field.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="65.2.0">SetSelectOptions</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;SetSelectOptions($input, $options, $selected)</tt></p>
<h4>Purpose</h4>
<p>Set the list of options and selected values of a <tt>select</tt> type input.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument defines the identifier of the <tt>select</tt> input to be set.</p>
<p>The <tt>$options</tt> argument is an associative array that defines the list of options, like for the <tt>OPTIONS</tt> argument passed to <tt>AddInput</tt> function.</p>
<p>The <tt>$selected</tt> argument is array that defines the values of the list of options that should be selected, like for the <tt>SELECTED</tt> argument passed to <tt>AddInput</tt> function. For non <tt>MULTIPLE</tt> <tt>select</tt> inputs, it should be passed an array with a single value of the option to be selected.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="66.2.0">StartLayoutCapture</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error=$my_form_object-&gt;StartLayoutCapture()</tt></p>
<h4>Purpose</h4>
<p>Start capturing the current script output to compose the form layout.</p>
<h4>Usage</h4>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h3><a name="67.2.0">Validate</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$error_message=$my_form_object-&gt;Validate($verify,$sub_form)</tt></p>
<h4>Purpose</h4>
<p>Determine if the values set in the form input fields are valid.</p>
<p>The validation of each input is performed according to the respective definition that was passed to the <tt>AddInput</tt> function. The order of the validation types is as follows:</p>
<ul>
<p><li><tt>ValidateAsNotEmpty</tt></li></p>
<p><li><tt>ValidateAsDifferentFromText</tt></li></p>
<p><li><tt>ValidateMinimumLength</tt></li></p>
<p><li><tt>ValidateRegularExpression</tt></li></p>
<p><li><tt>ValidateAsNotRegularExpression</tt></li></p>
<p><li><tt>ValidateAsInteger</tt></li></p>
<p><li><tt>ValidateAsFloat</tt></li></p>
<p><li><tt>ValidateAsEmail</tt></li></p>
<p><li><tt>ValidateAsCreditCard</tt></li></p>
<p><li><tt>ValidateAsEqualTo</tt></li></p>
<p><li><tt>ValidateAsDifferentFrom</tt></li></p>
<p><li><tt>ValidateAsSet</tt></li></p>
<p><li><tt>ValidationServerFunction</tt></li></p>
</ul>
<p>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 <tt>ValidationClientFunction</tt> validation will be performed instead of <tt>ValidationServerFunction</tt>.</p>
<h4>Usage</h4>
<p>The <tt>$verify</tt> 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.</p>
<p>The <tt>$sub_form</tt> 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.</p>
<p>The <tt>$error_message</tt> 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.</p>
</ul>
<h3><a name="69.2.0">WasSubmitted</a></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$submitted_input=$my_form_object-&gt;WasSubmitted($input)</tt></p>
<h4>Purpose</h4>
<p>Determine if a form was submitted by a given input field.</p>
<h4>Usage</h4>
<p>The <tt>$input</tt> argument specifies the identifier of the input field that this method should verify whether it was used to submit the form.</p>
<p>The <tt>$submitted_input</tt> return value contains the identifier of the field that was used to submit the form. If the <tt>$input</tt> argument is not an empty string and the field was not used to submit the form, the method returns an empty string.</p>
<p>Usually the specified input is of type <tt>submit</tt> or <tt>image</tt>, 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 <tt>hidden</tt> that will only act as a flag to determine if the form was submitted or is meant to be displayed for the first time.</p>
<p>If the <tt>$input</tt> argument is an empty string the method tries to find whether any <tt>submit</tt> or <tt>image</tt> field was used to submit the form and returns its name. If no field was found, the method returns an empty string.</p>
<p>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.</p>
</ul>
</ul>
<h2><li><a name="70.1.3">Properties</a></li></h2>
<ul>
<h3><li><a name="71.2.1">ACTION</a></li></h3>
<p>URL of the resource (Web page script) that is meant to handle the form submission as defined for the <tt>ACTION</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p>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.</p>
<p>One simple way to define the <tt>ACTION</tt> property to make the form be handled by the same script is to set it with an empty string or with <tt>?</tt> if you want to avoid passing forward any parameters previously passed with the current page URL.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.2">ENCTYPE</a></li></h3>
<p>MIME Content type of the data that is sent when the form is submitted as defined for the <tt>ENCTYPE</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p>This property only applies when the data is submitted using the <tt>POST</tt> method. If no encoding type is specified, the browsers use the MIME type <tt>application/x-form-urlencoded</tt>. If the form includes <tt>file</tt> input fields, the class uses the MIME type <tt>multipart/form-data</tt> automatically.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.3">ID</a></li></h3>
<p>Identifier of the form document element as defined for the <tt>ID</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.4">METHOD</a></li></h3>
<p>Method that is used to submit the form as defined for the <tt>METHOD</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p>The method that is recommended to be used is <tt>POST</tt>, 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 <tt>GET</tt> may be used.</p>
<p>If the form being submitted has <tt>file</tt> inputs, the <tt>POST</tt> method is used automatically.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.5">NAME</a></li></h3>
<p>Name of the form as defined for the <tt>NAME</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag. This property must be set to non-empty string if the <tt>Output</tt> 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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.6">ONERROR</a></li></h3>
<p>Client side script commands to execute when the form is submitted but has validation errors.</p>
<p>The script may use several variables that are initialized with values related with the validation errors. The <tt>form</tt> variable is a reference to the form object. The <tt>error_message</tt> variable is a string with all the errors to be displayed. The <tt>Invalid</tt> variable is an object whose member names are the fields that failed validation rules. The member values are the respective input error messages.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.7">ONSUBMIT</a></li></h3>
<p>Client side script commands to execute when the form is submitted as defined for the <tt>ONSUBMIT</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p>Any commands specified by this property are executed before executing the client side validation code generated by the class <tt>Output</tt> method.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.8">ONSUBMITTING</a></li></h3>
<p>Client side script commands to execute when the form is submitted as defined for the <tt>ONSUBMIT</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p>Any commands specified by this property are executed after executing the client side validation code generated by the class <tt>Output</tt> method. If there are any fields with invalid values, the commands specified by this property are not executed.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.9">ONRESET</a></li></h3>
<p>Client side script commands to execute when the form is reseted as defined for the <tt>ONRESET</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p>Any commands specified by this property are executed before executing the client side validation code generated by the class <tt>Output</tt> method.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.10">TARGET</a></li></h3>
<p>Name of the Web browser frame on which the results of the form submission are meant to be displayed as defined for the <tt>ACTION</tt> attribute of the <tt>&lt;FORM&gt;</tt> HTML tag.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.11">error</a></li></h3>
<p>Some functions return an error message when they fail. This message is also stored in the <tt>error</tt> 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.</p>
<p>The class functions never reset the value of this property. Therefore its value is overwritten by the last function call that fails.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.12">Changes</a></li></h3>
<p>Associative array that enumerates the form fields that had their values changed after calling the function <tt>LoadInputValues</tt>. 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 <tt>AddInput</tt> and <tt>SetInputValue</tt> functions.</p>
<p>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 <tt>LoadInputValues</tt> function.</p>
<p>Entries for <tt>radio</tt> and <tt>checkbox</tt> are set to an empty string if their prior state was not <tt>CHECKED</tt>. Entries for <tt>MULTIPLE</tt> <tt>select</tt> fields are set to an associative array that enumerates the values that changed in the selection list. The respective values are set to <tt>0</tt> for entries that were deselected and 1 for entries that were selected.</p>
<p><b>Default value:</b> empty array</p>
<h3><li><a name="71.2.13">DisableReadOnlyInputs</a></li></h3>
<p>Boolean flag that determines if the form inputs in read-only mode should be outputted as normal inputs with the <tt>DISABLED</tt> HTML attribute, or otherwise, as formatted text that represents the the input value.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<h3><li><a name="71.2.14">ExtraAttributes</a></li></h3>
<p>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.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<h3><li><a name="71.2.15">Invalid</a></li></h3>
<p>Associative array that enumerates the form fields that have invalid values after calling the function <tt>Validate</tt>.</p>
<p>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.</p>
<p>If the <tt>Validate</tt> function is called passing a specific sub-form name, only the fields that belong to that sub-form are considered.</p>
<p>The <tt>Validate</tt> function resets the <tt>Invalid</tt> variable before it starts validating the fields. The information about any fields considered invalid in previous <tt>Validate</tt> function calls is lost.</p>
<p><b>Default value:</b> empty array</p>
<h3><li><a name="71.2.16">InvalidCLASS</a></li></h3>
<p>Name of the default CSS class used to render invalid fields.</p>
<p>When set to a non-empty string, the specified value replaces the default CSS class attribute of the invalid fields listed in the <tt>Invalid</tt> forms class variable.</p>
<p>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.</p>
<p>The value of the forms class <tt>InvalidCLASS</tt> variable can be overriden for fields defined with its own <tt>InvalidCLASS</tt> argument.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.17">InvalidSTYLE</a></li></h3>
<p>Default CSS style attributes used to render invalid fields.</p>
<p>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 <tt>Invalid</tt> forms class variable.</p>
<p>The specified CSS attributes are also used to replace invalid fields' CSS attributes, when the form is validated on the client side using Javascript.</p>
<p>The value of the forms class <tt>InvalidSTYLE</tt> variable can be overriden for fields defined with its own <tt>InvalidSTYLE</tt> argument.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="71.2.18">OptionsSeparator</a></li></h3>
<p>String that is used to separate the values of <tt>MULTIPLE</tt> select fields when the form is outputted in <tt>ReadOnly</tt> mode.</p>
<p><b>Default value:</b> <tt>&quot;\n&quot;</tt></p>
<h3><li><a name="71.2.19">OutputPasswordValues</a></li></h3>
<p>Boolean flag that determines if the form password fields values should be outputted with the respective field <tt>&lt;input&gt;</tt> tags.</p>
<p>For security reasons it is recommended to keep this flag set to <tt>0</tt>. If a page with a form with a password field set to some value is cached when this flag is set to <tt>1</tt>, somebody with access to the machine of the user browser may recover the password from the page cache file.</p>
<p>If you absolutely need to set this flag to <tt>1</tt>, make sure you use the appropriate page headers to tell the user browsers to not cache the pages.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<h3><li><a name="71.2.20">ReadOnly</a></li></h3>
<p>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 <tt>1</tt> fields are outputted as text that represents their current state and values.</p>
<p>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 <tt>Accessible</tt> property. Form output field parts added as hidden parts with the <tt>AddHiddenInputsParts</tt> function are always outputted as hidden input fields regardless of the value of the form <tt>ReadOnly</tt> flag and the input <tt>Accessible</tt> property.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<h3><li><a name="71.2.21">ResubmitConfirmMessage</a></li></h3>
<p>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.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
</ul>
<h2><li><a name="71.1.4">Options</a></li></h2>
<ul>
<p>Options are special properties that only need to be changed in particular circumstances. Their default values are appropriate for normal operation.</p>
<h3><li><a name="72.2.1">ErrorMessagePrefix</a></li></h3>
<p>Text to prepend to the error messages that are displayed or returned when invalid inputs are found.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="72.2.2">ErrorMessageSuffix</a></li></h3>
<p>Text to append to the error messages that are displayed or returned when invalid inputs are found.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="72.2.3">ShowAlertOnError</a></li></h3>
<p>Boolean flag that determines whether an alert message box should be used to display error messages when client side validation fails.</p>
<p>Set this option to <tt>0</tt> if you want to implement custom client side error message displaying overriding the default alert message box.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<h3><li><a name="72.2.4">ShowAllErrors</a></li></h3>
<p>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.</p>
<p>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 <tt>Validate</tt> function.</p>
<p>Multiple error messages are split by the end of line character sequence defined by the <tt>end_of_line</tt>.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<h3><li><a name="72.2.5">ValidateAsCreditCard</a></li></h3>
<p>Name of the client side credit card number validation function that the <tt>Output</tt> 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.</p>
<p><b>Default value:</b> <tt>&quot;ValidateCreditCard&quot;</tt></p>
<h3><li><a name="72.2.6">ValidateAsEmail</a></li></h3>
<p>Name of the client side e-mail address validation function that the <tt>Output</tt> 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.</p>
<p><b>Default value:</b> <tt>&quot;ValidateEmail&quot;</tt></p>
<h3><li><a name="72.2.7">ValidationErrorFunctionName</a></li></h3>
<p>Name of a client side validation function that the <tt>Output</tt> 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.</p>
<p><b>Default value:</b> <tt>&quot;ValidationError&quot;</tt></p>
<h3><li><a name="72.2.8">ValidationFunctionName</a></li></h3>
<p>Name of the client side validation function that the <tt>Output</tt> 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.</p>
<p><b>Default value:</b> <tt>&quot;ValidateForm&quot;</tt></p>
<h3><li><a name="72.2.9">ValidateOnlyOnServerSide</a></li></h3>
<p>Boolean option to tell the class to not generate JavaScript code to validate the package on the browser side.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<h3><li><a name="72.2.10">accessibility_tab_index</a></li></h3>
<p>Name of the global function that is called to determine the number that should be assigned to the <tt>TABINDEX</tt> attribute the corresponding form field <tt>&lt;INPUT&gt;</tt> HTML tag. If the field does not have the <tt>TABINDEX</tt> 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 <tt>TABINDEX</tt> attribute.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="72.2.11">debug</a></li></h3>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<h3><li><a name="72.2.12">decimal_regular_expression</a></li></h3>
<p>Regular expression that is used to fields set with the option <tt>ValidateAsFloat</tt> and <tt>ValidationDecimalPlaces</tt>. The word <tt>PLACES</tt> in this variable value will be replaced by the value of the <tt>ValidationDecimalPlaces</tt> option.</p>
<p><b>Default value:</b> <tt>&quot;^-?[0-9]+(\\.[0-9]{0,PLACES})?\$&quot;</tt></p>
<h3><li><a name="72.2.13">event_parameter</a></li></h3>
<p>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.</p>
<p>The value of this option is use by the <tt>GetInputEventURL</tt> function to form an event handling URL.</p>
<p><b>Default value:</b> <tt>&quot;___event&quot;</tt></p>
<h3><li><a name="72.2.14">email_regular_expression</a></li></h3>
<p>Regular expression that is used to validate an e-mail address text field.</p>
<p><b>Default value:</b> <tt>&quot;^([-!#\$%&amp;'*+./0-9=?A-Z^_`a-z{|}~])+@([-!#\$%&amp;'*+/0-9=?A-Z^_`a-z{|}~]+\\.)+[a-zA-Z]{2,6}\$&quot;</tt></p>
<h3><li><a name="72.2.15">encoding</a></li></h3>
<p>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 <tt>iso-8859-1</tt> (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 <tt>&lt;</tt>, <tt>&gt;</tt> and <tt>&quot;</tt> characters are encoded.</p>
<p><b>Default value:</b> <tt>&quot;iso-8859-1&quot;</tt></p>
<h3><li><a name="72.2.16">end_of_line</a></li></h3>
<p>Sequence of characters that will be used to break the lines of the generated Javascript code.</p>
<p><b>Default value:</b> <tt>\n</tt></p>
<h3><li><a name="72.2.17">float_regular_expression</a></li></h3>
<p>Regular expression that is used to fields set with the option <tt>ValidateAsFloat</tt> but not with the option <tt>ValidationDecimalPlaces</tt>.</p>
<p><b>Default value:</b> <tt>&quot;^-?[0-9]+(\\.[0-9]*)?([Ee][+-]?[0-9]+)?\$&quot;</tt></p>
<h3><li><a name="72.2.18">form_submitted_test_variable_name</a></li></h3>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;form_submitted_test&quot;</tt></p>
<h3><li><a name="72.2.19">form_submitted_variable_name</a></li></h3>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;form_submitted&quot;</tt></p>
<h3><li><a name="72.2.20">input_parameter</a></li></h3>
<p>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.</p>
<p>The value of this option is use by the <tt>GetInputEventURL</tt> function to form an event handling URL.</p>
<p><b>Default value:</b> <tt>&quot;___input&quot;</tt></p>
<h3><li><a name="72.2.21">sub_form_variable_name</a></li></h3>
<p>Name of the client side global variable that it is used to store the sub-form name corresponding to the <tt>submit</tt> 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.</p>
<p><b>Default value:</b> <tt>&quot;sub_form&quot;</tt></p>
<h3><li><a name="72.2.22">tolower_function</a></li></h3>
<p>Name of the function to be called to convert a text string to lower case. This function is used when the <tt>Capitalization</tt> attribute of a <tt>text</tt> field is set to <tt>lowercase</tt>. 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.</p>
<p><b>Default value:</b> <tt>&quot;strtolower&quot;</tt></p>
<h3><li><a name="72.2.23">toupper_function</a></li></h3>
<p>Name of the function to be called to convert a text string to upper case. This function is used when the <tt>Capitalization</tt> attribute of a <tt>text</tt> field is set to <tt>uppercase</tt>. 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.</p>
<p><b>Default value:</b> <tt>&quot;strtoupper&quot;</tt></p>
</ul>
<h2><li><a name="72.1.5">Functions</a></li></h2>
<ul>
<h3><li><a name="73.2.1">FormCaptureOutput</a></li></h3>
<ul>
<h4>Synopsis</h4>
<p><tt>$output=FormCaptureOutput($form,$arguments)</tt></p>
<h4>Purpose</h4>
<p>Capture the output of a form object in a result text string.</p>
<h4>Usage</h4>
<p>The <tt>$form</tt> 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.</p>
<p>The <tt>$arguments</tt> argument is an associative array that takes pairs of tag names and values as defined for the class <tt>Output</tt> method. The <tt>Function</tt> argument is overridden by a custom global function that does the output capture.</p>
<p>The <tt>$output</tt> return value contains the form HTML output if the function call succeed. Otherwise it contains an empty string.</p>
</ul>
</ul>
<h2><li><a name="74.1.6">Template processing</a></li></h2>
<ul>
<h3><li><a name="75.2.1">Separating presentation from logic</a></li></h3>
<p>To compose the layout of a form, the class needs to be called alternating HTML data definitions using <tt>AddInputPart</tt> 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.</p>
<p>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.</p>
<h3><li><a name="75.2.2">Plain HTML template files with embedded PHP code</a></li></h3>
<p>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 <tt>AddDataPart</tt> function before generating the whole form output.</p>
<p>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.</p>
<p>This class is capable of capturing the current PHP script output by calling the function <tt>StartLayoutCapture</tt>. After calling this function and until the <tt>EndLayoutCapture</tt> function is called, all the script output is captured to compose the form output.</p>
<p>Plain HTML template files can be used to define the form layout by using the PHP <tt>include</tt> 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 <tt>AddInputPart</tt> and <tt>AddLabelPart</tt>. Here follows an example:</p>
<p>File: <tt>my_form_script.php</tt></p>
<pre style="background-color: #ddddcc; ">
&lt;?php
$form=new form_class;
$form-&gt;AddInput(array(
&quot;NAME&quot;=&gt;&quot;user_name&quot;,
&quot;TYPE&quot;=&gt;&quot;text&quot;,
&quot;ValidateAsNotEmpty&quot;=&gt;1,
&quot;ValidationErrorMessage&quot;=&gt;&quot;You have not specified the user name&quot;
));
$form-&gt;AddInput(array(
&quot;NAME&quot;=&gt;&quot;password&quot;,
&quot;TYPE&quot;=&gt;&quot;text&quot;,
&quot;ValidateAsNotEmpty&quot;=&gt;1,
&quot;ValidationErrorMessage&quot;=&gt;&quot;You have not specified the password&quot;
));
$form-&gt;AddInput(array(
&quot;ID&quot;=&gt;&quot;submit&quot;,
&quot;TYPE&quot;=&gt;&quot;submit&quot;
));
$form-&gt;StartLayoutCapture();
include(&quot;my_form_template.html.php&quot;);
$form-&gt;EndLayoutCapture();
$form-&gt;DisplayOutput();
?&gt;
</pre>
<p>File: <tt>my_form_template.html.php</tt></p>
<pre style="background-color: #ddddcc; ">
&lt;table&gt;
&lt;tr&gt;
&lt;th&gt;&lt;?php
$form-&gt;AddLabelPart(array(
&quot;FOR&quot;=&gt;&quot;user_name&quot;,
&quot;LABEL&quot;=&gt;&quot;&lt;u&gt;U&lt;/u&gt;ser name&quot;,
&quot;ACCESSKEY&quot;=&gt;&quot;U&quot;
));
?&gt;:&lt;/th&gt;
&lt;td&gt;&lt;?php $form-&gt;AddInputPart(&quot;user_name&quot;); ?&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;th&gt;&lt;?php
$form-&gt;AddLabelPart(array(
&quot;FOR&quot;=&gt;&quot;password&quot;,
&quot;LABEL&quot;=&gt;&quot;&lt;u&gt;P&lt;/u&gt;assword&quot;,
&quot;ACCESSKEY&quot;=&gt;&quot;P&quot;
));
?&gt;:&lt;/th&gt;
&lt;td&gt;&lt;?php $form-&gt;AddInputPart(&quot;password&quot;); ?&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td colspan=&quot;2&quot;&gt;&lt;?php $form-&gt;AddInputPart(&quot;submit&quot;); ?&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
</pre>
<h3><li><a name="75.2.3">Smarty template engine</a></li></h3>
<p>One of the most popular template engines for PHP is <a href="http://www.smarty.net/">Smarty</a>. 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.</p>
<p>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.</p>
<h3><li><a name="75.2.4">Smarty plug-in filter for form composition</a></li></h3>
<p>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.</p>
<p>The plug-in function is provided in a PHP include file named <tt>prefilter.form.php</tt>. Currently there are two versions of the plug-in, one for Smarty 2 and another for Smarty 3.</p>
<p>There is also an example form handling script named <tt>test_smarty_form.php</tt> that uses Smarty 2 with this plug-in function. The version for Smarty 3 is named <tt>test_smarty3_form.php</tt>. These scripts use a template file named <tt>form.tpl</tt> that contains the layout of the form defined in HTML.</p>
<p>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: <tt>{input name=&quot;input&quot;}</tt>, <tt>{hiddeninput name=&quot;input&quot;}</tt> and <tt>{label for=&quot;input&quot;}</tt>. If you changed Smarty mark left and right delimiters to other characters besides <tt>{</tt> and <tt>}</tt>, the form input and label marks must use those other delimiter characters.</p>
<p>The <tt>{input}</tt> mark specifies an input to be added to the form as it would be added with the <tt>AddInputPart</tt>. The <tt>{hiddeninput}</tt> mark specifies an input to be added to the form as a hidden input as it would be added with the <tt>AddInputHiddenPart</tt>. The <tt>{label}</tt> mark specifies where a label of a specified input to be added to the form as it would be added with the <tt>AddLabelPart</tt>.</p>
<p>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 <tt>$form</tt>. Make sure your forms class object is assigned to this global variable.</p>
</ul>
<h2><li><a name="75.1.7">Enhancing forms with custom input type plug-ins</a></li></h2>
<p>The forms class provides support for using custom form input types that can implement enhanced functionality over the basic HTML form input types.</p>
<p>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.</p>
<p>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.</p>
<p>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 <a href="http://www.opensource.org/licenses/bsd-license.php">BSD</a> 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.</p>
<ul>
<h3><li><a name="76.2.1">Custom input classes</a></li></h3>
<p>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 <tt>AddInput</tt>. The main difference is that you need to specify the name of the class of the custom input using the <tt>CustomClass</tt> parameter of the <tt>AddInput</tt> function.</p>
<p>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 <tt>form_custom_class</tt>. This class is defined in the <tt>forms.php</tt> file right before the main forms class.</p>
<p>The <tt>form_custom_class</tt> 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.</p>
<ul>
<h4><li><a name="77.3.1">Basic steps for developing new custom input classes</a></li></h4>
<p>If you are interested in developing a new custom input class, here follows a list of common steps that you should take:</p>
<ul>
<h5><li><a name="78.4.1">Create a new custom input class</a></li></h5>
<p>A new custom custom input class should be created by extending the <tt>form_custom_class</tt> base class. This base class provides default behavior that reduces significantly the effort that is necessary to implement a new custom input.</p>
<h5><li><a name="78.4.2">Implement the input initialization</a></li></h5>
<p>The most important function of a custom input class is the <tt>AddInput</tt> function. It should check the parameter arguments passed to the function and initialize the class variables according to the needs.</p>
<p>If the new custom input is intended to manage a set of one or more new inputs, the <tt>AddInput</tt> function is the place where such inputs should be defined by using the main forms class <tt>AddInput</tt> function. Use the <tt>GenerateInputID</tt> function to create unique identifiers for those new inputs.</p>
<p>If the class is supposed to benefit from the automatic support for rendering from format templates, it should initialize the <tt>format</tt> and <tt>valid_marks</tt> class variables using the <tt>ParseNewInputFormat</tt> function.</p>
<p>This will let the class benefit from inheriting several functions from the base class without having to reimplement them like <tt>AddInputPart</tt>, <tt>AddHiddenInputPart</tt>, <tt>AddLabelPart</tt> and <tt>AddFunction</tt>.</p>
<h5><li><a name="78.4.3">Define the page head section or the load and unload events</a></li></h5>
<p>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 <tt>PageHead</tt> function.</p>
<p>If the custom input needs to define head tags only once, even when the form has multiple custom inputs of the same class, the <tt>ClassPageHead</tt> function should be implemented to define such tags.</p>
<p>Additionally, if it needs to execute Javascript code during the page load or unload events, it must implement the <tt>PageLoad</tt> or <tt>PageUnload</tt> functions respectively.</p>
<h5><li><a name="78.4.4">Retrieve input values</a></li></h5>
<p>If the new custom input will have an associated input value that can be set or changed by the user, implement the <tt>GetInputValue</tt> function to provide a means for the applications that use the new form custom input to retrieve its current value.</p>
<p>Also, if the new custom input will emulate the behavior of a <tt>checkbox</tt> or <tt>radio</tt>, implement the <tt>GetCheckedState</tt> function to provide a means for the applications that use the new form custom input to retrieve its checked state.</p>
<h5><li><a name="78.4.5">Setting properties</a></li></h5>
<p>If there are any properties that can be changed by the applications after the custom input is added to the form, implement the <tt>SetInputProperty</tt> function to handle property change requests, including for the main input <tt>VALUE</tt> property if supported.</p>
<p>Also, if the new custom input will emulate the behavior of a <tt>checkbox</tt> or <tt>radio</tt>, implement the <tt>SetCheckedState</tt> function to provide a means for the applications that use the new form custom input to change its checked state.</p>
<h5><li><a name="78.4.6">Validate input values</a></li></h5>
<p>If the custom input value has to be validated according to specific rules, implement the <tt>ValidateInput</tt> function to enforce such rules. Make sure it is possible to configure details of such validation rules with either the <tt>AddInput</tt> or <tt>SetInputProperty</tt> 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 <tt>server_validate</tt> variable needs to be set to <tt>1</tt>. In this case, the <tt>ValidateInput</tt> function does not need to be redefined.</p>
<p>If possible implement the <tt>GetJavascriptValidations</tt> 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 <tt>client_validate</tt> variable to <tt>1</tt>.</p>
<p>If the custom input is expected to be managed by another custom input, implement <tt>GetJavascriptInputValue</tt> 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.</p>
<h5><li><a name="78.4.7">Load submitted input values</a></li></h5>
<p>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 <tt>LoadInputValues</tt> function to define how to execute such special action.</p>
<h5><li><a name="78.4.8">Connecting inputs to trigger special actions upon client side events</a></li></h5>
<p>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.</p>
<p>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.</p>
<p>This can be achieved using the <tt>Connect</tt> function. It associates a client side event in the origin input to an action that is executed in the context of a target input.</p>
<p>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 <tt>Connect</tt> to handle new events and <tt>GetJavascriptConnectionAction</tt> to generate the necessary Javascript code that implements new actions.</p>
<h5><li><a name="78.4.9">Registering custom client side input events</a></li></h5>
<p>The base custom input class provides means to automatically register custom input events.</p>
<p>An application just calls the <tt>Connect</tt> function to trigger the execution of an action on the context of a given input when the event occurs.</p>
<p>The base class implementation of that function registers the details of the event connection. The <tt>connections</tt> class variable is updated to keep event connection information. The <tt>Connect</tt> function only accepts registrations of connections for events with an entry already initialized in the <tt>connections</tt> variable.</p>
<p>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 <tt>GetEventActions</tt> function.</p>
<p>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 <tt>events</tt> class variable.</p>
<h5><li><a name="78.4.10">Handling client side events on the server side</a></li></h5>
<p>In certain circumstances a custom input may need to execute actions on the server side to handle special user interaction events.</p>
<p>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.</p>
<p>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.</p>
<p>In either case, these interactions with custom input on the client side and the respective custom input class, can be implemented with the <tt>HandleEvent</tt> function.</p>
<p>The <tt>HandleEvent</tt> class function examines the request parameters to determine which custom input is responsible for processing the request. Then it calls the <tt>HandleEvent</tt> 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.</p>
<p>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.</p>
<h5><li><a name="78.4.11">Forward client side events to custom inputs</a></li></h5>
<p>A custom input may forward the request to handle an event received by the <tt>HandleEvent</tt> function. This may be useful to delegate the response of a client side event to a child input.</p>
<p>The class of the custom input receiving a event handling request just needs to call the <tt>PostMessage</tt> function of the main forms class, setting the message <tt>Target</tt> parameter to the identifier of the input to which the event should be forwarded. An input receiving a forwarded message must implement the <tt>PostMessage</tt> function.</p>
<h5><li><a name="78.4.12">Emulating form submit inputs</a></li></h5>
<p>A custom input may emulate form submit inputs to provide additional behaviour. In that case, an input emulating form submit inputs may implement the <tt>WasSubmitted</tt> function.</p>
</ul>
<p>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.</p>
<h4><li><a name="78.3.2">Class variables</a></li></h4>
<ul>
<h5><li><a name="79.4.1"><tt>children</tt></a></li></h5>
<p>Array that stores the names of all the children inputs that have has parent the current custom input.</p>
<p>This variable is updated by the <tt>AddChild</tt> function and should not be redefined by the custom input class.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<h5><li><a name="79.4.2"><tt>client_validate</tt></a></li></h5>
<p>Boolean flag that tells whether the custom input generates Javascript code to perform eventual client side validation that may be necessary.</p>
<p>This variable should be redefined or initialized when the <tt>AddInput</tt> 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.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<h5><li><a name="79.4.3"><tt>connections</tt></a></li></h5>
<p>Associative array that stores the actions registered to handle events supported by the custom input class.</p>
<p>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 <tt>DefaultConnect</tt> implementation of the base custom input class.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><b>Example value:</b> <tt>array(<br />
&quot;ONCOMPLETE&quot;=&gt;array(),<br />
&quot;ONTIMEOUT&quot;=&gt;array()<br />
)</tt></p>
<h5><li><a name="79.4.4"><tt>events</tt></a></li></h5>
<p>Associative array that stores the Javascript code to be executed when the supported custom events are called.</p>
<p>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.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><b>Example value:</b> <tt>array(<br />
&quot;ONTIMEOUT&quot;=&gt;&quot;alert('The communication with the server has timed out.');&quot;<br />
)</tt></p>
<h5><li><a name="79.4.5"><tt>format</tt></a></li></h5>
<p>Format of an HTML template that defines how the custom input will be rendered. This format template is used by the <tt>AddInputPart</tt> function of the custom input base class to implement the default rendering method.</p>
<p>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.</p>
<p>The special marks start and end with characters defined by the <tt>mark_start</tt> and <tt>mark_end</tt> respectively. The text value between the start and end marks defines the mark name.</p>
<p>The meaning of the mark name is defined by the <tt>valid_marks</tt> variable. Usually it specifies that the mark corresponds to one of several input fields that are managed by the custom input.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><b>Example value:</b> <tt>&quot;{day}/{month}/{year}&quot;</tt></p>
<h5><li><a name="79.4.6"><tt>focus_input</tt></a></li></h5>
<p>Identifier of the default input that is meant to get the input focus. That input may get the focus when:</p>
<ul>
<p><li>A function of type <tt>focus</tt> or <tt>select_focus</tt> defined with <tt>AddFunction</tt> function is called.</li></p>
<p><li>The user clicks on the label associated with the input field using the <tt>AddLabelPart</tt> function.</li></p>
<p><li>The input has an invalid value when the user submits the form.</li></p>
</ul>
<p>If this variable is set to an empty string, no input will get the focus.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><b>Example value:</b> <tt>&quot;date_day&quot;</tt></p>
<h5><li><a name="80.4.7"><tt>input</tt></a></li></h5>
<p>Identifier name of the current custom input. This is set by the main forms class when the custom input object is created.</p>
<p>It is assigned to the <tt>ID</tt> or <tt>NAME</tt> value specified by the current script as parameter of the <tt>AddInput</tt> function of the main forms class to add the custom input to the form definition.</p>
<p>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.</p>
<p><b>Default value:</b> set by the main forms class</p>
<h5><li><a name="80.4.8"><tt>mark_start</tt></a></li></h5>
<p>Text that identifies the beginning of a place holder mark in format templates.</p>
<p>Usually this variable does not need to be redefined by the custom input class.</p>
<p><b>Default value:</b> <tt>&quot;{&quot;</tt></p>
<h5><li><a name="80.4.9"><tt>mark_end</tt></a></li></h5>
<p>Text that identifies the end of a place holder mark in format templates.</p>
<p>Usually this variable does not need to be redefined by the custom input class.</p>
<p><b>Default value:</b> <tt>&quot;}&quot;</tt></p>
<h5><li><a name="80.4.10"><tt>server_validate</tt></a></li></h5>
<p>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.</p>
<p>This variable should be redefined or initialized when the <tt>AddInput</tt> function is called, if the custom input does not perform any server side validation.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<h5><li><a name="80.4.11"><tt>valid_marks</tt></a></li></h5>
<p>Associative array that specifies the meaning of names used in place holder marks used in the format template specified by the <tt>format</tt> variable.</p>
<p>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 <tt>AddInputPart</tt> function. Currently it supports the elements of type <tt>input</tt>, <tt>label</tt> and <tt>data</tt>.</p>
<p>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.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><b>Example value:</b></p>
<pre style="background-color: #ddddcc; ">
array(
&quot;input&quot;=&gt;array(
&quot;year&quot;=&gt;&quot;date_year&quot;,
&quot;month&quot;=&gt;&quot;date_month&quot;,
&quot;day&quot;=&gt;&quot;date_day&quot;
),
&quot;label&quot;=&gt;array(
&quot;year&quot;=&gt;&quot;date_year&quot;
),
&quot;data&quot;=&gt;array(
&quot;clock&quot;=&gt;'&lt;img src=&quot;clock.gif&quot; width=&quot;16&quot; height=&quot;16&quot; alt=&quot;Clock&quot;&gt;'
)
)
</pre>
</ul>
<h4><li><a name="80.3.3">Class functions</a></li></h4>
<ul>
<h5><a name="81.4.0">AddChild</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;AddChild($form, $name)</tt></p>
<h6>Purpose</h6>
<p>Add the information of the name of a successfully added child input of a custom input.</p>
<p>This function is called when the <tt>AddInput</tt> function of the main forms class is called by the custom input class to add a child input.</p>
<p>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 <tt>children</tt> array class variable, so it may be used whenever the class needs to iterate over the children inputs.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$name</tt> argument is the identifier name of the just added child input.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="82.4.0">AddFunction</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;AddFunction($form, $arguments)</tt></p>
<h6>Purpose</h6>
<p>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.</p>
<p>This function is called when the <tt>AddFunction</tt> function of the main forms class is called to add a function on a custom input element.</p>
<p>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 <tt>AddFunction</tt> on the input specified by the <tt>focus_input</tt> variable of the custom input object.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$arguments</tt> argument is the array passed to the main forms class <tt>AddFunction</tt> function.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="83.4.0">AddInput</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;AddInput($form, $arguments)</tt></p>
<h6>Purpose</h6>
<p>Initialize the custom input object with parameters that are meant to configure details of its behavior.</p>
<p>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.</p>
<p>This function is called when the <tt>AddInput</tt> function of the main forms class is called to add a custom input to the form.</p>
<p>This function needs to be reimplemented in the actual custom input classes.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used. Make sure you declare the <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$arguments</tt> argument is the array passed to the main forms class <tt>AddInput</tt> function.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="84.4.0">AddInputHiddenPart</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;AddInputHiddenPart($form)</tt></p>
<h6>Purpose</h6>
<p>Add the input to the output that is generated for the form as if it was a <tt>hidden</tt> field.</p>
<p>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 <tt>format</tt> and <tt>valid_marks</tt> custom input object variables.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="85.4.0">AddInputPart</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;AddInputPart($form)</tt></p>
<h6>Purpose</h6>
<p>Add the input to the output that is generated for the form.</p>
<p>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 <tt>format</tt> and <tt>valid_marks</tt> custom input object variables.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="86.4.0">AddLabelPart</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;AddLabelPart(&amp;$form, $arguments)</tt></p>
<h6>Purpose</h6>
<p>Add the label of the custom input to the output that is generated for the form with the main forms class <tt>Output</tt> method.</p>
<p>Usually this function does not need to be reimplemented in the actual custom input classes.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$arguments</tt> 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 <tt>AddLabelPart</tt> function of the main forms class.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="87.4.0">ClassPageHead</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$html=$input_object-&gt;ClassPageHead($form)</tt></p>
<h6>Purpose</h6>
<p>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.</p>
<p>This function is called once from the main forms class <tt>PageHead</tt> function for each class of the custom inputs.</p>
<p>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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$html</tt> return value contains the necessary HTML tags that should be inserted in the page head section.</p>
</ul>
<h5><a name="88.4.0">Connect</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;Connect($form, $to, $event, $action, $context)</tt></p>
<h6>Purpose</h6>
<p>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.</p>
<p>This function is called when the <tt>Connect</tt> function of the main forms class is called and the custom input is the connection target input.</p>
<p>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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$from</tt> argument is the identifier of the connection origin input on which it may occur the trigger event.</p>
<p>The <tt>$event</tt> argument is the name of event that may occur in the connection origin input in the client side (user browser).</p>
<p>The <tt>$action</tt> 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.</p>
<p>The <tt>$context</tt> argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="89.4.0">DefaultConnect</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;DefaultConnect($form, $to, $event, $action, $context)</tt></p>
<p>Provide a default implementation for the <tt>Connect</tt> function.</p>
<p>This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the <tt>Connect</tt> function to register actions to be associated to events supported by the custom input.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$from</tt> argument is the identifier of the connection origin input on which it may occur the trigger event.</p>
<p>The <tt>$event</tt> argument is the name of event that may occur in the connection origin input in the client side (user browser).</p>
<p>The <tt>$action</tt> 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.</p>
<p>The <tt>$context</tt> argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="90.4.0">DefaultJavascriptGetConnectionAction</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;DefaultJavascriptGetConnectionAction($form, $form_object, $from, $event, $action, $context, $action)</tt></p>
<h6>Purpose</h6>
<p>Provide a default implementation for the <tt>GetJavascriptConnectionAction</tt> function.</p>
<p>This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the <tt>GetJavascriptConnectionAction</tt> 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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$from</tt> argument is the identifier of the connection origin input on which it may occur the trigger event.</p>
<p>The <tt>$event</tt> argument is the name of event that may occur in the connection origin input in the client side (user browser).</p>
<p>The <tt>$action</tt> 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.</p>
<p>The <tt>$context</tt> argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.</p>
<p>The <tt>$action</tt> argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="91.4.0">DefaultHandleEvent</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;DefaultHandleEvent($form, $event, $parameters, $processed)</tt></p>
<h6>Purpose</h6>
<p>Provide a default implementation for the <tt>HandleEvent</tt> function.</p>
<p>This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the <tt>HandleEvent</tt> 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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$event</tt> argument is the name of the event that has occurred.</p>
<p>The <tt>$parameters</tt> argument is an associative array with all the parameters that were passed in the event handling request.</p>
<p>The <tt>$processed</tt> 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.</p>
<p>The <tt>$error</tt> return value contains an error message if there was an error while trying to process the specified event. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="92.4.0">DefaultPostMessage</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;DefaultPostMessage($form, $message, $processed)</tt></p>
<h6>Purpose</h6>
<p>Provide a default implementation for the <tt>PostMessage</tt> function.</p>
<p>This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the <tt>PostMessage</tt> function to handle messages that are not directly handled by the custom input class. Currently, it just sends a reply to the posted message.</p>
<h6>Usage</h6>
<p>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.</p>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$message</tt> 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 <tt>PostMessage</tt> function of the main forms class for the list of common message entries.</p>
<p>The <tt>$processed</tt> 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.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h5><a name="93.4.0">DefaultSetInputProperty</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;DefaultSetInputProperty($form, $property, $value)</tt></p>
<h6>Purpose</h6>
<p>Provide a default implementation for the <tt>SetInputProperty</tt> function.</p>
<p>This function is not meant to be reimplemented in the actual custom input classes. It is meant to be called by the <tt>SetInputProperty</tt> function to support properties that are not directly implemented by the custom input class. Currently, it only implements the following properties:</p>
<ul>
<li><tt>Accessible</tt></li><li><tt>Format</tt></li><li><tt>SubForm</tt></li></ul>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$property</tt> argument is the name of the property to be changed.</p>
<p>The <tt>$value</tt> argument is the new value of the property.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h5><a name="95.4.0">GenerateInputID</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$id=$input_object-&gt;GenerateInputID($form, $input, $kind)</tt></p>
<h6>Purpose</h6>
<p>Helper function to generate input identifier names. It is meant to create names for basic inputs that make part of composite complex custom inputs.</p>
<p>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.</p>
<p>Usually this function does not need to be reimplemented in the actual custom input classes.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$input</tt> argument is the base name of the input identifier to be generated. Usually it is the identifier name of the current custom input.</p>
<p>The <tt>$kind</tt> argument is a unique name of the kind input to which the resulting identifier will be assigned.</p>
<p>The <tt>$id</tt> return value is the generated input identifier.</p>
</ul>
<h5><a name="96.4.0">GetContainedInputs</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;GetContainedInputs($form, $kind, $contained)</tt></p>
<h6>Purpose</h6>
<p>Retrieve the list of inputs contained within the custom input.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$kind</tt> 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.</p>
<p>The <tt>$contained</tt> argument is a reference to a variable that will be assigned by this function to an array of identifier strings of the contained inputs.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h5><a name="97.4.0">GetEventActions</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$actions=$input_object-&gt;GetEventActions($form, $form_object, $event)</tt></p>
<h6>Purpose</h6>
<p>Generate the necessary Javascript code that will be used to implement the actions registered with the <tt>Connect</tt> function.</p>
<p>This function is meant to be called by custom input classes that need to generate Javascript that will be associated to a given event.</p>
<p>This function is implemented by the base custom input class and should not be reimplemented by any other custom input class.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$event</tt> argument is the name of event for which it is being generated the handling Javascript code.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the custom input belongs.</p>
<p>The <tt>$actions</tt> return value is the generated event handling Javascript code.</p>
</ul>
<h5><a name="98.4.0">GetInputValue</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$value=$input_object-&gt;GetInputValue($form)</tt></p>
<h6>Purpose</h6>
<p>Retrieve the current value of the custom input, eventually combining the current values of any of the inputs that compose the custom input.</p>
<p>This function is called when the main forms class <tt>GetInputValue</tt> is called specifying the current custom input identifier as argument.</p>
<p>This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$value</tt> 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.</p>
</ul>
<h5><a name="99.4.0">GetJavascriptCheckedState</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$javascript_value=$input_object-&gt;GetJavascriptCheckedState($form, $form_object)</tt></p>
<h6>Purpose</h6>
<p>Generate a Javascript expression that represents the checked state of a the <tt>custom</tt> input field to be used to on client side scripts in Javascript.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$javascript_value</tt> return value is a string that represents the given input field checked state in Javascript.</p>
</ul>
<h5><a name="100.4.0">GetJavascriptConnectionAction</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;GetJavascriptConnectionAction($form, $form_object, $from, $event, $action, $context, $javascript)</tt></p>
<h6>Purpose</h6>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the given input belongs.</p>
<p>The <tt>$from</tt> argument is the identifier of the connection origin input on which it may occur the trigger event.</p>
<p>The <tt>$event</tt> argument is the name of event that may occur in the connection origin input in the client side (user browser).</p>
<p>The <tt>$action</tt> 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.</p>
<p>The <tt>$context</tt> argument is a reference to an associative array that may pass additional context information to configure details of the action that will be executed.</p>
<p>The <tt>$javascript</tt> argument is a reference to a string variable that should be assigned by this function to the Javascript code for the requested action.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="101.4.0">GetJavascriptInputValue</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$javascript_value=$input_object-&gt;GetJavascriptInputValue($form, $form_object)</tt></p>
<h6>Purpose</h6>
<p>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.</p>
<p>This function is called when the main forms class <tt>GetJavascriptInputValue</tt> is called specifying the current custom input identifier as argument.</p>
<p>This function needs to be reimplemented in the actual custom input classes if the input is supposed to carry a value.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the custom input belongs.</p>
<p>The <tt>$javascript_value</tt> return value is a string that represents the custom input field value in Javascript.</p>
</ul>
<h5><a name="102.4.0">GetJavascriptSetCheckedState</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$javascript=$my_form_object-&gt;GetJavascriptSetCheckedState($form, $form_object, $checked)</tt></p>
<h6>Purpose</h6>
<p>Generate a Javascript expression to set the checked state of the custom input field.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the custom input belongs.</p>
<p>The <tt>$checked</tt> argument is a string that specifies the Javascript expression to set the given input checked state.</p>
<p>The <tt>$javascript</tt> return value is a string with Javascript statements to set the custom input checked state.</p>
</ul>
<h5><a name="103.4.0">GetJavascriptSetInputProperty</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$javascript=$input_object-&gt;GetJavascriptSetInputProperty($form, $form_object, $property, $value)</tt></p>
<h6>Purpose</h6>
<p>Generate Javascript commands to assign the value of a property of the custom input field.</p>
<p>This function is called when the main forms class <tt>GetJavascriptSetInputProperty</tt> function is called specifying the current custom input identifier as argument.</p>
<p>This function needs to be reimplemented in the actual custom input classes if it supports changing any input properties from Javascript.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the custom input belongs.</p>
<p>The <tt>$property</tt> argument is a string that specifies the name of the input property to be assigned. It should be <tt>VALUE</tt> for assigning the main input value.</p>
<p>The <tt>$value</tt> argument is a string that specifies the Javascript expression to assign to the given input property.</p>
<p>The <tt>$javascript</tt> return value is a string with Javascript statements to assign the given input property.</p>
</ul>
<h5><a name="104.4.0">GetJavascriptValidations</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;GetJavascriptValidations($form, $form_object, $validations)</tt></p>
<h6>Purpose</h6>
<p>Retrieve a list of validation tests that are meant to be performed on the client side using Javascript.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$form_object</tt> argument is a string that represents the Javascript object of the form to which the custom input belongs.</p>
<p>The <tt>$validations</tt> argument is a reference to an array that will be initialized with entries that define details of each client side validation test.</p>
<p>Each entry of the <tt>$validations</tt> array is set to an associative array that specifies parameters of an individual test. Here follows the list of currently supported parameters:</p>
<ul>
<p><li><tt>Commands</tt></li></p>
<p>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.</p>
<p>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.</p>
<p><li><tt>Condition</tt></li></p>
<p>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.</p>
<p>If the condition string is empty, no validation condition is evaluated.</p>
<p><li><tt>ErrorMessage</tt></li></p>
<p>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.</p>
<p><li><tt>Focus</tt></li></p>
<p>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.</p>
<p>This parameter is optional. If it is missing, the custom input class variable <tt>focus_input</tt> 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 <tt>focus_input</tt> variable.</p>
</ul>
<p>If you reimplement this function in custom input class, make sure you declare the <tt>$validations</tt> argument to be passed by reference.</p>
<p>Here follows an example of defined a special validation test that checks whether the day of a given month and year is valid:</p>
<pre style="background-color: #ddddcc; ">
$day=$form-&gt;GetJavascriptInputValue($form_object,$this-&gt;day);
$month=$form-&gt;GetJavascriptInputValue($form_object,$this-&gt;month);
$year=$form-&gt;GetJavascriptInputValue($form_object,$this-&gt;year);
$validations=array(
array(
&quot;Commands&quot;=&gt;array(
&quot;month=&quot;.$month,
&quot;if(month=='04'&quot;,
&quot;|| month=='06'&quot;,
&quot;|| month=='09'&quot;,
&quot;|| month=='11')&quot;,
&quot; month_days=30&quot;,
&quot;else&quot;,
&quot;{&quot;,
&quot; if(month=='02')&quot;,
&quot; {&quot;,
&quot; year=parseInt(&quot;.$year.&quot;)&quot;,
&quot; if((year % 4)==0&quot;,
&quot; &amp;&amp; ((year % 100)!=0&quot;,
&quot; || (year % 400)==0))&quot;,
&quot; month_days=29&quot;,
&quot; else&quot;,
&quot; month_days=28&quot;,
&quot; }&quot;,
&quot; else&quot;,
&quot; month_days=31&quot;,
&quot;}&quot;,
&quot;date_day=&quot;.$day
),
&quot;Condition&quot;=&gt;&quot;month_days&lt;parseInt(date_day)&quot;,
&quot;ErrorMessage&quot;=&gt;$this-&gt;invalid_day_error_message,
&quot;Focus&quot;=&gt;$this-&gt;day
)
);
</pre>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="106.4.0">HandleEvent</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;HandleEvent($form, $event, $parameters, $processed)</tt></p>
<h6>Purpose</h6>
<p>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.</p>
<p>This function is called by the forms class function also named <tt>HandleEvent</tt> when it determines that a given event handling request should be routed to this custom input object class.</p>
<p>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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$event</tt> argument is the name of the event that has occurred.</p>
<p>The <tt>$parameters</tt> argument is an associative array with all the parameters that were passed in the event handling request.</p>
<p>The <tt>$processed</tt> 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.</p>
<p>The <tt>$error</tt> return value contains an error message if there was an error while trying to process the specified event. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="107.4.0">LoadInputValues</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error = $input_object-&gt;LoadInputValues($form, $submitted)</tt></p>
<h6>Purpose</h6>
<p>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.</p>
<p>This function is called for all custom inputs from the main forms class <tt>LoadInputValues</tt> 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 <tt>GetInputValue</tt>.</p>
<p>Usually this function does not need to be reimplemented in the actual custom input classes.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$submitted</tt> argument has the same value that is passed to the main forms class <tt>LoadInputValues</tt>.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="108.4.0">PageHead</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$html=$input_object-&gt;PageHead($form)</tt></p>
<h6>Purpose</h6>
<p>Retrieve the HTML code that is necessary to insert in the page head section to make the custom input work correctly.</p>
<p>This function is called for all custom inputs from the main forms class <tt>PageHead</tt> function.</p>
<p>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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$html</tt> return value contains the necessary HTML tags that should be inserted in the page head section.</p>
</ul>
<h5><a name="109.4.0">PageLoad</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$javascript=$input_object-&gt;PageLoad($form)</tt></p>
<h6>Purpose</h6>
<p>Retrieve the Javascript code that is necessary to execute when the page is loaded to make the custom input work correctly.</p>
<p>This function is called for all custom inputs from the main forms class <tt>PageLoad</tt> function.</p>
<p>This function needs to be reimplemented in the custom input classes that need to execute special Javascript code when the page body is loaded.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$javascript</tt> return value contains the necessary Javascript code that should be used to define the page <tt>BODY</tt> <tt>ONLOAD</tt> tag.</p>
</ul>
<h5><a name="110.4.0">PageUnload</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$javascript=$input_object-&gt;PageUnload($form)</tt></p>
<h6>Purpose</h6>
<p>Retrieve the Javascript code that is necessary to execute when the page is unloaded to make the custom input work correctly.</p>
<p>This function is called for all custom inputs from the main forms class <tt>PageUnload</tt> function.</p>
<p>This function needs to be reimplemented in the custom input classes that need to execute special Javascript code when the page body is unloaded.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$javascript</tt> return value contains the necessary Javascript code that should be used to define the page <tt>BODY</tt> <tt>ONUNLOAD</tt> tag.</p>
</ul>
<h5><a name="111.4.0">ParseNewInputFormat</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;ParseNewInputFormat()</tt></p>
<h6>Purpose</h6>
<p>Validate and process the current input display format template.</p>
<p>It parses the format template defined by the <tt>format</tt> variable and validates it to verify whether it complies with definition of place holders specified by the <tt>valid_marks</tt> variable.</p>
<p>This function is used by the custom input base class when it renders the input with the <tt>AddInputPart</tt> function. It may also be used to validate a new format template defined from the parameters of the <tt>AddInput</tt> or <tt>SetInputProperty</tt> functions.</p>
<p>Usually this function should not be reimplemented in the actual custom input classes.</p>
<h6>Usage</h6>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="112.4.0">PostMessage</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;PostMessage($form, $message, $processed)</tt></p>
<h6>Purpose</h6>
<p>Handle a message targetted to the input.</p>
<h6>Usage</h6>
<p>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.</p>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$message</tt> 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 <tt>PostMessage</tt> function of the main forms class for the list of common message entries.</p>
<p>The <tt>$processed</tt> 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.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h5><a name="113.4.0">ReplyMessage</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;ReplyMessage($form, $message, $processed)</tt></p>
<h6>Purpose</h6>
<p>Handle a message sent in reply to a previously posted event message.</p>
<p>Usually this function should be reimplemented in the actual custom input classes that post event handling messages.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$message</tt> argument is the same associative array of the message sent with the <tt>PostMessage</tt> function. It may contain new or altered entries to specify details that may trigger different actions when the message reply is processed.</p>
<p>The <tt>$processed</tt> 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 <tt>1</tt>, or the script may continue with normal form processing in case it returns <tt>0</tt>.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="114.4.0">SetInputProperty</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;SetInputProperty($form, $property, $value)</tt></p>
<h6>Purpose</h6>
<p>Change the value of a specific property of the custom input.</p>
<p>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 <tt>AddInput</tt> function.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$property</tt> argument is the name of the property to be changed.</p>
<p>The <tt>$value</tt> argument is the new value of the property.</p>
<p>The <tt>$error</tt> 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.</p>
</ul>
<h5><a name="115.4.0">SetSelectOptions</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error=$input_object-&gt;SetSelectOptions($form, $options, $selected)</tt></p>
<h6>Purpose</h6>
<p>Set the list of options and selected values of a custom input that implements a behavior similar to a <tt>select</tt> input type.</p>
<p>This function is called when the <tt>SetSelectInput</tt> function of the main forms class is called for a custom input class.</p>
<p>This function needs to be reimplemented in the actual custom input classes that implement inputs similar to the <tt>select</tt> input type.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> argument is a reference to the forms class object on which this custom input is being used.</p>
<p>The <tt>$options</tt> argument is an associative array that defines the list of options, like for the <tt>OPTIONS</tt> argument passed to <tt>AddInput</tt> function.</p>
<p>The <tt>$selected</tt> argument is array that defines the values of the list of options that should be selected, like for the <tt>SELECTED</tt> argument passed to <tt>AddInput</tt> function.</p>
<p>The <tt>$error</tt> return value contains an error message if the method call did not succeed. Otherwise it contains an empty string.</p>
</ul>
<h5><a name="116.4.0">ValidateInput</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$error_message=$input_object-&gt;ValidateInput($form)</tt></p>
<h6>Purpose</h6>
<p>Validate the current value of the custom input.</p>
<p>This function is called by the main forms class <tt>Validate</tt> function after it has successfully validated all the basic type inputs. So, it is safe to retrieve from the <tt>ValidateInput</tt> function valid values of any basic inputs managed by a custom input class.</p>
<p>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.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$error_message</tt> 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.</p>
</ul>
<h5><a name="117.4.0">WasSubmitted</a></h5>
<ul>
<h6>Synopsis</h6>
<p><tt>$submitted_input=$my_form_object-&gt;WasSubmitted($form, $input)</tt></p>
<h6>Purpose</h6>
<p>Determine if a form was submitted by the custom input.</p>
<h6>Usage</h6>
<p>The <tt>$form</tt> 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 <tt>$form</tt> argument to be passed by reference.</p>
<p>The <tt>$input</tt> argument specifies the identifier of the custom input or an empty string of the class is checking which of the form fields was submitted.</p>
<p>The <tt>$submitted_input</tt> return value contains the identifier of the field that was used to submit the form. If the <tt>$input</tt> argument is not an empty string and the field was not used to submit the form, the method returns an empty string.</p>
</ul>
</ul>
</ul>
<h3><li><a name="118.2.2">Available custom input plug-ins classes</a></li></h3>
<p>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.</p>
<p>Here follows the list of available custom input classes. More will be made available later.</p>
<ul>
<h4><li><a name="119.3.1"><tt>form_ajax_submit_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>Submit a form in the background without reloading the current page.</p>
<h5>Features</h5>
<ul>
<p><li>Submits the current form using an hidden inline frame. It works with most browsers that support inline frames, including to submit forms with file upload inputs.</li></p>
<p><li>Can perform global or sub-form validation before submitting the form.</li></p>
<p><li>Can set the values of one or more inputs right before submitting the form. This can be used to trigger the form submission upon distinct browser side events, each one setting different input values. That makes possible to distinguish on the server side which browser side event triggered the form submission.</li></p>
<p><li>Can send AJAX GET requests with custom parameters. This can be used to send AJAX requests to perform interaction with the server without submitting the form.</li></p>
<p><li>Can set the feedback messages to appear in a given page element when certain browser side events happen like form submission, submission response completely sent, or server communication timeout.</li></p>
<p><li>Handles timeout events by aborting the form submission when the server does not respond within a configurable timeout period. The action that is executed when a timeout occurs is also configurable.</li></p>
<p><li>Prevents submitting a form more than once using the same inline frame.</li></p>
<p><li>Implements several types of actions defined on the server side to be executed on the browser side in response to a form submission.</li></p>
<p>Multiple actions may be defined dynamically to be executed within the same form submission. The definition of an action does not require that the developer has prior Javascript knowledge.</p>
<p>Currently supported actions include altering the HTML contents of parts of the current page, redirecting the browser to a new page, setting the value of document element, waiting for a given period, etc..</p>
<p><li>Can emit custom headers before outputting the AJAX response. It can be useful to signal the Web server that it is an AJAX response that may need special treatment, like avoiding HTTP dechunking or compression in order to reduce response delivery delays.</li></p>
<p><li>A debug console can be opened in the form page to exhibit information about the data being sent and received from the browser, as well the actions being executed in response to the AJAX request.</li></p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>CompleteFeedback</tt></li></p>
<p>HTML code to display within the page feedback element when the form submission response is completely sent to the browser by this plug-in class.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>DebugConsole</tt></li></p>
<p>Identifier of the page element within which a debug console should appear displaying information about the communication that happens during AJAX requests.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>Feedback</tt> (changeable)</li></p>
<p>Contents of the feedback page element.</p>
<p>This property can only be set while the AJAX response to a form submission is being sent. If it is set as an <tt>AddInput</tt> parameter, its value is ignored.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>FeedbackElement</tt> (changeable)</li></p>
<p>Identifier of a page element within which feedback messages may appear when certain browser side events occur. Usually, the feedback page element is a <tt>&lt;div&gt;</tt> or <tt>&lt;span&gt;</tt>, but it may be of other type. This plug-in is not responsible for generating feedback elements. It only updates the contents of the specified page feedback element when a certain event occurs.</p>
<p>Currently, the events that can make the feedback page element be updated are the form submission and server communication timeout. The messages that appear in the feedback element are defined by the <tt>SubmitFeedback</tt> and <tt>TimeoutFeedback</tt> properties respectively. It may also be set using the <tt>Feedback</tt> property while the AJAX response to a form submission is being sent.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>SubmitFeedback</tt></li></p>
<p>HTML code to display within the page feedback element when the form is submitted by this plug-in class.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>TargetInput</tt></li></p>
<p>Identifier of the input to which the form submission event messages will be forwarded. If this property is not set, the event messages will be queued for retrieval by the application.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Timeout</tt></li></p>
<p>Limit of time in seconds that a browser should wait to retrieve the form submission response from the server.</p>
<p><b>Default value:</b> <tt>60</tt></p>
<p><li><tt>TimeoutFeedback</tt></li></p>
<p>HTML code to display within the page feedback element when the communication with the server times out.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>ONCOMPLETE</tt></li></p>
<p>String with Javascript code to execute the form submission is completely sent to the browser.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>ONTIMEOUT</tt></li></p>
<p>String with Javascript code to execute the form submission takes more time to return its response than the configured timeout value.</p>
<p><b>Default value:</b> <tt>&quot;alert('The communication with the server has timed out.');&quot;</tt></p>
<p><li><tt>ONSUBMITTED</tt></li></p>
<p>String with Javascript code to execute after an AJAX form submission is sent.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>ResponseHeader</tt></li></p>
<p>Custom HTTP response header that may be sent before outputting the AJAX response. An empty string, means no custom header is outputted.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><b>Example:</b> <tt>&quot;X-no-gzip-compress: yes&quot;</tt></p>
</ul>
<h5>Event connection actions</h5>
<ul>
<p>This custom input implements two types of action that can be triggered on the browser side: <tt>Submit</tt> and <tt>Load</tt>.</p>
<p>The <tt>Submit</tt> action is used to trigger the AJAX POST form submission. The <tt>Submit</tt> action supports the context arguments <tt>SetInputValue</tt>, <tt>SubForm</tt> and <tt>Validate</tt>.</p>
<p>The <tt>SetInputValue</tt> argument can be used to specify a list of inputs that should be set right before submitting the form. The argument value must be an associative array. The indexes of the array are the input names. The array values are the respective values of there inputs to set.</p>
<p>The <tt>SubForm</tt> argument can be used to restrict the validation that is performed before the form is submitted to a sub-form with the specified name.</p>
<p>The <tt>Validate</tt> argument is a boolean flag that indicates whether the form should be validated before submitting it via AJAX. By default the form is always validated.</p>
<p>The <tt>Load</tt> action is used to submit an AJAX GET request with custom parameters, thus without having to submit the form. The <tt>Submit</tt> action supports two context arguments named <tt>Parameters</tt> and <tt>RandomParameter</tt>.</p>
<p>The <tt>Parameters</tt> argument should be an associative array that defines the names and values of the parameters to send with the AJAX GET request.</p>
<p>The <tt>RandomParameter</tt> argument should be the name special parameter that will be initialized with a random value with the purpose to avoid eventual browser caching of the GET response.</p>
</ul>
<h5>Messages</h5>
<ul>
<p>When an AJAX submit custom input captures an AJAX form submission, it can post messages to the form message queue to let an application process the AJAX request and define how it should be responded to execute the desired actions on the browser page from which the form was submitted.</p>
<p><li><tt>submit</tt></li></p>
<p>Currently, the AJAX submit input only posts <tt>submit</tt> type messages.</p>
<h6>Message parameters</h6>
<ul>
<p><li><tt>Immediate</tt></li></p>
<p><tt>Immediate</tt> is a boolean parameter preset to <tt>0</tt>. Applications should set it to <tt>1</tt> before replying to a message to instruct the AJAX submit input immediately send the response defined by the <tt>Actions</tt> response parameter, even if the response is not finished.</p>
<p><li><tt>More</tt></li></p>
<p><tt>More</tt> is a boolean parameter preset to <tt>0</tt>. Applications should set it to <tt>1</tt> before replying to a message, to instruct the AJAX submit input send the response defined by the <tt>Actions</tt> response parameter, but the response is not finished.</p>
<p>When the AJAX submit input receives a message response with this parameter set to <tt>1</tt>, it posts the <tt>submit</tt> message again.</p>
<p><li><tt>Window</tt></li></p>
<p><tt>Window</tt> is a string parameter set to an expression that evaluates to the main browser Javascript Window object. It can be used to generate Javascript expressions that need to access to that object.</p>
<p><li><tt>Document</tt></li></p>
<p><tt>Document</tt> is a string parameter set to an expression that evaluates to the main browser Javascript Document object. It can be used to generate Javascript expressions that need to access to that object.</p>
<p><li><tt>Form</tt></li></p>
<p><tt>Form</tt> is a string parameter set to an expression that evaluates to the current Javascript Form object. It can be used to generate Javascript expressions that need to access to that object.</p>
<p><li><tt>SubForm</tt></li></p>
<p><tt>SubForm</tt> is a string parameter that may be set to the name of the sub-form associated to the form submission. This parameter is only set if the <tt>submit</tt> action context also specifies a sub-form parameter.</p>
</ul>
<h6>Response parameters</h6>
<ul>
<p><li><tt>Actions</tt></li></p>
<p><tt>Actions</tt> is an array response parameter that should contain one or more entries to define which actions must be executed when the AJAX request response is sent to the browser.</p>
<p>Each action entry is defined by an associative array that defines the detail parameters of the action.</p>
<p>Common action parameters</p>
<ul>
<p><li><tt>Action</tt></li></p>
<p><tt>Action</tt> is the name of the type action. Currently supported actions are:</p>
<ul>
<p><li><tt>AppendContent</tt></li></p>
<p>Append HTML to a given document element.</p>
<p><li><tt>Command</tt></li></p>
<p>Execute an arbitrary Javascript code.</p>
<p><li><tt>Connect</tt></li></p>
<p>Execute Javascript associated to an action executed in the context of another input.</p>
<p><li><tt>PrependContent</tt></li></p>
<p>Prepend HTML to a given document element.</p>
<p><li><tt>Redirect</tt></li></p>
<p>Instruct the browser to redirect to a new page URL.</p>
<p><li><tt>ReplaceContent</tt></li></p>
<p>Replace a given document element with new HTML content.</p>
<p><li><tt>SetInputProperty</tt></li></p>
<p>Change a property of a given input.</p>
<p><li><tt>SetInputValue</tt></li></p>
<p>Change the value of a given input.</p>
<p><li><tt>SetValue</tt></li></p>
<p>Change the value of a given document element property.</p>
<p><li><tt>Wait</tt></li></p>
<p>Wait for a given period of time.</p>
</ul>
</ul>
<p>Action specific parameters</p>
<p><tt>AppendContent</tt><br />
<tt>PrependContent</tt><br />
<tt>ReplaceContent</tt></p>
<ul>
<p><li><tt>Container</tt></li></p>
<p>Identifier of the document element that will be altered.</p>
<p><li><tt>Content</tt></li></p>
<p>HTML data that defines the content alteration.</p>
</ul>
<p><tt>Command</tt></p>
<ul>
<p><li><tt>Command</tt></li></p>
<p>Javascript code to execute.</p>
<p><li><tt>Content</tt></li></p>
<p>HTML data that defines the content alteration.</p>
</ul>
<p><tt>Connect</tt></p>
<ul>
<p><li><tt>To</tt></li></p>
<p>Identifier of the input which will execute the connection action.</p>
<p><li><tt>ConnectionAction</tt></li></p>
<p>Name of the action to execute.</p>
<p><li><tt>Context</tt></li></p>
<p>Array with context data to pass when executing the action.</p>
</ul>
<p><tt>Redirect</tt></p>
<ul>
<p><li><tt>URL</tt></li></p>
<p>URL of the new page to redirect.</p>
</ul>
<p><tt>SetInputProperty</tt></p>
<ul>
<p><li><tt>Input</tt></li></p>
<p>Identifier of the input.</p>
<p><li><tt>Property</tt></li></p>
<p>Name of the input property to set.</p>
<p><li><tt>Value</tt></li></p>
<p>Expression that defines the value to set the input property.</p>
</ul>
<p><tt>SetInputValue</tt></p>
<ul>
<p><li><tt>Input</tt></li></p>
<p>Identifier of the input.</p>
<p><li><tt>Value</tt></li></p>
<p>Expression that defines the value to set the input.</p>
</ul>
<p><tt>SetValue</tt></p>
<ul>
<p><li><tt>Element</tt></li></p>
<p>Identifier of the document element.</p>
<p><li><tt>Property</tt></li></p>
<p>Identifier of the document element property to set. If the property is a variable of the document element object, you can use . to specify which object is it.</p>
<p><li><tt>Value</tt></li></p>
<p>Value to set the document element property.</p>
<p><li>(Optional) <tt>Type</tt></li></p>
<p>Type of the value to set. Currently supported data types are: <tt>string</tt>, <tt>number</tt>, <tt>float</tt>, <tt>integer</tt>, <tt>boolean</tt>, <tt>undefined</tt>, <tt>null</tt>, <tt>opaque</tt>. <tt>opaque</tt> should be used for a value defined by an expression of an arbitrary type.</p>
<p>Default: <tt>&quot;string&quot;</tt></p>
</ul>
<p><tt>Wait</tt></p>
<ul>
<p><li><tt>Time</tt></li></p>
<p>Period of time to wait in seconds. It must not be zero. It may be an integer or a floating point number to specify decimal periods of time.</p>
</ul>
</ul>
</ul>
<h5>Example</h5>
<pre style="background-color: #ddddcc; ">
/*
* Create a form object.
*/
$form = new form_class;
$form-&gt;NAME = 'some_form_name';
/*
* The form submission method must be POST.
*/
$form-&gt;METHOD = 'POST';
/*
* Make the form be submitted to the current script.
*/
$form-&gt;ACTION = '';
/*
* Add some fields.
*/
$form-&gt;AddInput(array(
'TYPE' =&gt; 'text',
'NAME' =&gt; 'login',
'ID' =&gt; 'login',
'LABEL' =&gt; '&lt;u&gt;L&lt;/u&gt;ogin',
'ACCESSKEY' =&gt; 'L'
));
$form-&gt;AddInput(array(
'TYPE' =&gt; 'text',
'NAME' =&gt; 'password',
'ID' =&gt; 'password',
'LABEL' =&gt; '&lt;u&gt;P&lt;/u&gt;assword',
'ACCESSKEY' =&gt; 'P'
));
$form-&gt;AddInput(array(
'TYPE' =&gt; 'submit',
'NAME' =&gt; 'doit',
'ID' =&gt; 'doit',
'VALUE' =&gt; 'Submit'
));
/*
* Add the AJAX form submit custom input.
*/
$form-&gt;AddInput(array(
'TYPE' =&gt; 'custom',
'NAME' =&gt; 'sender',
'ID' =&gt; 'sender',
'CustomClass' =&gt; 'form_ajax_submit_class',
'Timeout' =&gt; 60,
'ONTIMEOUT' =&gt; '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-&gt;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-&gt;HandleEvent($processed);
if($processed)
exit;
/*
* Was the form submitted via AJAX?
* Check whether the AJAX form submit input posted a message.
*/
if($form-&gt;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-&gt;LoadInputValues();
$error_message = $form-&gt;Validate($verify);
/*
* If the form fields are valid, make any other
* server side only validations
*/
if(strlen($error_message)==0)
{
$error_message = ValidateLoginAndPassword(
$form-&gt;GetInputValue('login'),
$form-&gt;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 &lt;div id=&quot;feedback&quot;&gt;&lt;/div&gt;
* with a validation error message.
*
* Make sure the message is correctly encoded in HTML using
* HTMLSpecialChars function.
*/
$message['Actions'] = array(
array(
'Action' =&gt; 'ReplaceContent',
'Container' =&gt; 'feedback',
'Content' =&gt; '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' =&gt; 'ReplaceContent',
'Container' =&gt; 'feedback',
'Content' =&gt; 'The form was submitted and processed successfully!'
);
/*
* Wait a few seconds before redirecting
* the browser to a new page.
*/
$message['Actions'][] = array(
'Action' =&gt; 'Wait',
'Time' =&gt; 3
);
/*
* Redirect the browser to a new page.
*/
$new_page = GetEnv('REQUEST_URI');
$message['Actions'][] = array(
'Action' =&gt; 'Redirect',
'URL' =&gt; '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-&gt;ReplyMessage($message, $processed)))
exit;
}
/*
* Loop until there are no more event messages
* or the processing was finished
*/
while(!$processed
&amp;&amp; $form-&gt;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
*/
</pre>
</ul>
<h4><li><a name="136.3.2"><tt>form_animation_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>Manage visual effects to be applied to elements of a form page.</p>
<h5>Features</h5>
<ul>
<p><li>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.</li></p>
<p><li>The animations can be defined to run when events on other form page elements occur.</li></p>
<p><li>Different animations can be configured to run in debugging mode. On this mode, error messages are displayed when animation setup errors are detected.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><tt>Javascript animation class</tt></li></p>
<p>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 <tt>animation.js</tt>.</p>
<p>This PHP class generates the necessary HTML <tt>script</tt> tags to include the Javascript class file in the HTML page <tt>head</tt> section. Applications should use the main forms class <tt>PageHead</tt> function to retrieve the page <tt>head</tt> section tags that include the animation Javascript class file.</p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>JavascriptPath</tt></li></p>
<p>Directory of the URI of the Javascript class file <tt>animation.js</tt>. If the directory of the URI of the current script if the same of the <tt>animation.js</tt> file, just leave this property set to an empty string.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
</ul>
<h5>Event connection actions</h5>
<ul>
<p>This plug-in class implements only one action that can be triggered on the browser side. That action is named <tt>AddAnimation</tt>. It is used to a given animation to the list of running animation.</p>
<p>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:</p>
<ul>
<p><li><tt>Debug</tt></li></p>
<p>Integer value that defines the level of the debug mode. <tt>0</tt> means that debugging is disabled. <tt>1</tt> 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.</p>
<p><li><tt>Effects</tt> (Required)</li></p>
<p>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:</p>
<ul>
<p><tt>Animation</tt></p>
<p>Name of the animated associated to the effect. It is required by the <tt>CancelAnimation</tt> effect.</p>
<p><tt>Content</tt></p>
<p>HTML tags of the content to use by the effect. It is required by the <tt>AppendContent</tt>, <tt>PrependContent</tt> and <tt>ReplaceContent</tt> effects.</p>
<p><tt>Duration</tt></p>
<p>Duration of the effect in seconds. It is required by the <tt>FadeIn</tt>, <tt>FadeOut</tt> and <tt>Wait</tt> effects.</p>
<p><tt>DynamicElement</tt></p>
<p>Javascript expression that defines dynamically the identifier of the page element to apply the effect. It is required in alternative to the <tt>Element</tt> property.</p>
<p><tt>Element</tt></p>
<p>Identifier of the page element to apply the effect. It is required by the <tt>AppendContent</tt>, <tt>FadeIn</tt>, <tt>FadeIn</tt>, <tt>Hide</tt>, <tt>PrependContent</tt> and <tt>ReplaceContent</tt> and <tt>Show</tt> effects.</p>
<p><tt>Type</tt> (Required)</p>
<p>Name of the type of effect. Currently it supports the following effect types:</p>
<ul>
<p><tt>AppendContent</tt></p>
<p>Insert more HTML tags at the end of the content of a given page element.</p>
<p><tt>CancelAnimation</tt></p>
<p>Stop and remove an animation given its name.</p>
<p><tt>FadeIn</tt></p>
<p>Make a given hidden page element appear smoothly until it becomes completely visible.</p>
<p><tt>FadeOut</tt></p>
<p>Make a given page element disappear smoothly until it becomes completely invisible.</p>
<p><tt>Hide</tt></p>
<p>Turn a given page element invisible.</p>
<p><tt>PrependContent</tt></p>
<p>Insert more HTML tags at the beginning of the content of a given page element.</p>
<p><tt>ReplaceContent</tt></p>
<p>Replace the HTML tags contained within a given page element.</p>
<p><tt>Show</tt></p>
<p>Turn a given page element visible.</p>
<p><tt>Wait</tt></p>
<p>Wait a given period of time.</p>
</ul>
<p><tt>Visibility</tt></p>
<p>Defines the CSS property that will be used to control the visibility of an element for the effects: <tt>FadeIn</tt>, <tt>FadeIn</tt>, <tt>Hide</tt>, and <tt>Show</tt>. It may be set to either <tt>visibility</tt> or <tt>display</tt>. The default is <tt>visibility</tt>.</p>
</ul>
<p><li><tt>Name</tt></li></p>
<p>Name to associate to the animation being defined.</p>
<p><li><tt>Window</tt></li></p>
<p>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.</p>
</ul>
</ul>
</ul>
<h4><li><a name="144.3.3"><tt>form_auto_complete_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>A menu is displayed below the text input with the list of possible completion words.</li></p>
<p><li>The text completion is case insensitive.</li></p>
<p><li>The completion values can be retrieved on demand from the server using AJAX, or loaded all at once within the form page.</li></p>
<p><li>The completion words can be rendered in the menu with arbitrary HTML formatting.</li></p>
<p><li>The completion words menu can be browsed using the up or down cursor keys. The enter and escape keys close the menu.</li></p>
<p><li>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.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><b>AJAX form submit class</b></li></p>
<p>In dynamic mode, this class needs the custom input plug-in class <tt>form_ajax_submit_class</tt> to retrieve the completion values on demand from the server.</p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>CompleteDelay</tt></li></p>
<p>Delay in seconds that the input should wait after the last keystroke before it attempts to complete the text typed by the user.</p>
<p><b>Default value:</b> <tt>0.5</tt></p>
<p><li><tt>CompleteInput</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>CompleteMinimumLength</tt></li></p>
<p>Minimum number of characters that the user must have typed before the class attempts to complete the text.</p>
<p><b>Default value:</b> <tt>3</tt></p>
<p><li><tt>CompleteFeedback</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>CompleteValues</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Dynamic</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>FeedbackElement</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>ItemClass</tt></li></p>
<p>Name of the presentation style class with which the menu items should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>ItemStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the menu items should be rendered.</p>
<p><b>Default value:</b> <tt>&quot;padding: 1px; color: #000000;&quot;</tt></p>
<p><li><tt>MenuClass</tt></li></p>
<p>Name of the presentation style class with which the menu should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>MenuStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the menu should be rendered.</p>
<p><b>Default value:</b> <tt>&quot;background-color: #ffffff; border-width: 1px; border-color: #000000; border-style: solid; padding: 1px;&quot;</tt></p>
<p><li><tt>SelectedItemClass</tt></li></p>
<p>Name of the presentation style class with which the menu items should be rendered when they are selected.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>SelectedItemStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the menu items should be rendered when they are selected.</p>
<p><b>Default value:</b> <tt>&quot;padding: 1px; color: #ffffff; background-color: #000080;&quot;</tt></p>
<p><li><tt>ShowButton</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>SubmitFeedback</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>Timeout</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>60</tt></p>
<p><li><tt>TimeoutFeedback</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
</ul>
</ul>
<h4><a name="form_captcha_class"></a><li><a name="148.3.4"><tt>form_captcha_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p><a href="http://en.wikipedia.org/wiki/Captcha">CAPTCHA</a> is a designation that means: a <i>Completely Automated Public Turing test to tell Computers and Humans Apart</i>.</p>
<p>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.</p>
<p>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.</p>
<p>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).</p>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>It generates a text input with a validation image of customizable size with a text displayed in a random position of the image.</li></p>
<p><li> The image can be obfuscated with an optional noise image that is drawn over the text also in a random position.</li></p>
<p><li>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.</li></p>
<p><li>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.</li></p>
<p><li>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.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><b>The GD image library extension</b></li></p>
<p>The class requires the PHP is configured to use the <a href="http://www.php.net/manual/en/ref.image.php">GD image library extension</a>. Certain versions of the GD library do not support GIF images. In this case, the PNG or JPEG formats must be used.</p>
<p><li><b>The mcrypt library extension</b></li></p>
<p>The class requires the PHP is configured to use the <a href="http://www.php.net/manual/en/ref.mcrypt.php">mcrypt library extension</a> to be able to encrypt the validation text.</p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>BackgroundColor</tt> (changeable)</li></p>
<p>Color to be used to clear the background of the verification image. It must be in the hexadecimal RGB format: <tt>#RRGGBB</tt>. 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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>ExpiryTime</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>ExpiryTimeValidationErrorMessage</tt></li></p>
<p>Error message to return when the input value is not valid because the validation time expired. This property is required if the <tt>ExpiryTime</tt> property is set.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Font</tt> (changeable)</li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>2</tt></p>
<p><li><tt>Format</tt> (changeable)</li></p>
<p>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: <tt>image</tt>, <tt>text</tt>, <tt>redraw</tt> and <tt>validation</tt>.</p>
<p><b>Default value:</b> <tt>&quot;{image} {text} {redraw}{validation}&quot;</tt></p>
<p><li><tt>ImageAlign</tt> (changeable)</li></p>
<p>Specify the type of vertical alignment of the verification image, like with the <tt>ALIGN</tt> attribute of the HTML <tt>IMG</tt> tag.</p>
<p><b>Default value:</b> <tt>&quot;top&quot;</tt></p>
<p><li><tt>ImageFormat</tt> (changeable)</li></p>
<p>Specify the type of format that the verification image will be generated. The supported formats are: <tt>gif</tt>, <tt>jpeg</tt>, <tt>png</tt>.</p>
<p><b>Default value:</b> <tt>&quot;gif&quot;</tt></p>
<p><li><tt>ImageHeight</tt> (changeable)</li></p>
<p>Specify the height with which the verification image will be generated.</p>
<p><b>Default value:</b> <tt>20</tt></p>
<p><li><tt>ImageWidth</tt> (changeable)</li></p>
<p>Specify the width with which the verification image will be generated.</p>
<p><b>Default value:</b> <tt>80</tt></p>
<p><li><tt>InputClass</tt></li></p>
<p>Name of the presentation style class with which the text input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>InputExtraAttributes</tt></li></p>
<p>List of extra attributes that should be added to the text input HTML tag when the form output is generated.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>InputStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the text input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>InputTabIndex</tt></li></p>
<p>Order of navigation of the text input field when using the tab key, as defined by the HTML <tt>TABINDEX</tt> attribute.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Key</tt> (required)</li></p>
<p>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.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>NoiseFromGIFImage</tt> (changeable)</li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>NoiseFromPNGImage</tt> (changeable)</li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>RedrawClass</tt></li></p>
<p>Name of the presentation style class with which the redraw submit input should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>RedrawStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the redraw submit input should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>RedrawSubform</tt> (changeable)</li></p>
<p>Text to be used in the redraw submit button.</p>
<p><b>Default value:</b> <tt>&quot;Redraw&quot;</tt></p>
<p><li><tt>RedrawText</tt> (changeable)</li></p>
<p>Text to be used in the redraw submit button.</p>
<p><b>Default value:</b> <tt>&quot;Redraw&quot;</tt></p>
<p><li><tt>ResetIncorrectText</tt> (changeable)</li></p>
<p>Boolean flag that determines whether the verification text should be changed to a new value when the user enters an incorrect text.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>TextColor</tt> (changeable)</li></p>
<p>Color to be used to draw the validation text. It must be in the hexadecimal RGB format: <tt>#RRGGBB</tt>.</p>
<p><b>Default value:</b> <tt>&quot;#000000&quot;</tt></p>
<p><li><tt>TextLength</tt> (changeable)</li></p>
<p>Number of characters that will have the validation text.</p>
<p><b>Default value:</b> <tt>4</tt></p>
<p><li><tt>ValidationErrorMessage</tt> (required)</li></p>
<p>Error message to return when the input value does not match the validation text presented in the image.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>VALUE</tt></li></p>
<p>Text string for validation. By default it is set to a random text by this plug-in but it may be set initially to a specific value.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>VerificationClass</tt> (changeable)</li></p>
<p>Name of the presentation style class with which the verification image should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>VerificationStyle</tt> (changeable)</li></p>
<p>Definition of the presentation style attributes with which the verification image should be rendered.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="152.3.5"><tt>form_crud_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type can be used to simplify the creation of user interfaces and processing of events when using the <tt><a href="#form_scaffolding_class">form_scaffolding_class</a></tt> custom input to manipulate records of entries stored in databases or other forms of storage.</p>
<p>It should be used together with another custom input of type <tt>form_scaffolding_class</tt>. That other custom input must have set the <tt><a href="#form_scaffolding_class-Property-TargetInput">TargetInput</a></tt> property set to the identifier of the <tt>form_crud_class</tt> input.</p>
<h5>Features</h5>
<ul>
<p><li>It can automatically handle all the events generated by a <tt>form_scaffolding_class</tt> custom input.</li></p>
<p><li>It calls a data source object of a given class to do all the accesses to store and retrieve record entries to be edited or displayed.</li></p>
<p><li>It defines a base class that should be extended to implement new data source classes with minimal effort.</li></p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>DataSourceClass</tt> (required)</li></p>
<p>Name of the data source class that will be used to access the record entries data. That class should extend the base class <tt>form_crud_data_source_class</tt>.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>ScaffoldingInput</tt> (required)</li></p>
<p>Identifier of the <tt>form_scaffolding_class</tt> custom input with which this input will be integrated.</p>
<p><b>Default value:</b> not set</p>
</ul>
<h5><li><a name="155.4.1"><tt>form_crud_data_source_class</tt></a></li></h5>
<ul>
<h6>Purpose</h6>
<p>The <tt>form_crud_data_source_class</tt> is a class defined together with the <tt>form_crud_class</tt> class with the purpose of defining base functions to implement custom data source classes.</p>
<p>Data source classes serve as adapters to store and retrieve data from any type of data container. That data is displayed or edited using the <tt>form_crud_class</tt> and the <tt>form_scaffolding_class</tt> input classes together.</p>
<p>Applications need to create sub-classes that extend the <tt>form_crud_data_source_class</tt> and redefine just the functions that are necessary to customize the access to the data that will be stored or retrieved to be displayed or edited.</p>
<p>The base class can also generate the presentation of entries to be displayed by defining some base class variables to configure the presentation templates.</p>
<h6><li>Class variables</li></h6>
<ul>
<p><li><tt>entry_template</tt></li></p>
<p>HTML string of the template that defines how an entry should be displayed.</p>
<p>Set this variable to an HTML template before the <tt>ViewEntry</tt> function of the base data source class is called.</p>
<p>The template should include place holder marks that will be replaced by the values of the entry fields. For instance the <tt>{age}</tt> place holder will be replaced by the value of the entry field named <tt>age</tt>.</p>
<p>Templates may also have conditional sections which will only be displayed if the respective value is defined. For instance a template with a conditional section like this <tt>{age-section}Age: {age}{/age-section}</tt> will only be displayed if the value <tt>age-section</tt> is defined.</p>
<p><b>Default value:</b> <tt>'the entry template was not defined'</tt></p>
<p><li><tt>entry_template_properties</tt></li></p>
<p>Associative array that defines properties of place holder value used in the template defined by the <tt>entry_template</tt> variable.</p>
<p>The keys of the array are the place holder names. The array values are also associative arrays with the list of the properties. Currently the following properties are supported:</p>
<ul>
<p><li><tt>ConditionalSection</tt></li></p>
<p>Boolean property value that defines whether the current place holder defines a conditional section.</p>
<p>If a conditional section place holder value named <tt>section</tt> is defined, the base data source class function <tt>ViewEntry</tt> will replace a section in the template defined as <tt>{section}some section data{/section}</tt> by just <tt>some section data</tt>. If the place holder value is not defined the whole section is removed from the template.</p>
<p><li><tt>HTML</tt></li></p>
<p>Boolean property value that defines whether the current place holder value should be encoded as HTML before it is replaced in the template.</p>
</ul>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>placeholder_start</tt></li></p>
<p>Text string that defines the beginning of place holder marks in the template.</p>
<p><b>Default value:</b> <tt>'{'</tt></p>
<p><li><tt>placeholder_end</tt></li></p>
<p>Text string that defines the end of place holder marks in the template.</p>
<p><b>Default value:</b> <tt>'}'</tt></p>
<p><li><tt>placeholder_section_end</tt></li></p>
<p>Text string that defines the beginning of place holder marks that define the end of sections in the template.</p>
<p><b>Default value:</b> <tt>'{/'</tt></p>
</ul>
<h6>Functions</h6>
<p>Here follows the list of functions of the <tt>form_crud_data_source_class</tt> class that custom data source classes may redefine.</p>
<ul>
<p>Initialize</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;Initialize($form, $arguments)</tt></p>
<p>Purpose</p>
<p>Initialize the internal state of the data source object. It is called after the data source object is created during the call to the <tt>AddInput</tt> function.</p>
<p>Implement this function if you need to take values from the <tt>AddInput</tt> arguments.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$arguments</tt> argument is an associative array with the arguments passed to the <tt>AddInput</tt> function.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
<p>Finalize</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;Finalize($form)</tt></p>
<p>Purpose</p>
<p>Free any resources allocated during the life time of the data source object.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
<p>GetListing</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;GetListing($form, $listing)</tt></p>
<p>Purpose</p>
<p>Retrieve information that will be used to display the current page of listing entries.</p>
<p>Implement this function if the scaffolding input will display a listing of entries.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$listing</tt> argument is a reference to an associative array with values of properties of the <tt>form_scaffolding_class</tt> input. The <tt>Page</tt> entry contains the number of the listing page that is currently being displayed. The values set in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: <tt>Rows</tt>, <tt>IDColumn</tt>, <tt>Columns</tt>, <tt>TotalEntries</tt>, <tt>PageEntries</tt>, <tt>Page</tt>, <tt>ListingMessage</tt>.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
<p>InitializeEntry</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;InitializeEntry($form, $entry, $invalid, $values)</tt></p>
<p>Purpose</p>
<p>Validate whether it is acceptable to create an entry in the current circumstances and eventually preset the values of some fields.</p>
<p>Usually it is not necessary to redefine this function. It may be needed for instance when there are parameters defined in the URL or the current user session that alter the circumstances to the point the application may disallow the creation of new entries.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$entry</tt> argument is a reference to an associative array that may be set with values of properties of the <tt>form_scaffolding_class</tt> input. The values set in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: <tt>CreateCanceledMessage</tt>, <tt>CreateMessage</tt>.</p>
<p>The <tt>$invalid</tt> argument is a reference to an a boolean variable that should be set by the function to <tt>1</tt> if creating a new entry should be disallowed.</p>
<p>The <tt>$values</tt> argument is a reference to an associative array that may be set with values to initialize form inputs. The values in this array will be assigned to the respective form inputs after the function returns. <tt>checkbox</tt>, <tt>radio</tt> or other types of custom checkable inputs will have the <tt>CHECKED</tt> property set according to the assigned value which must be a boolean value.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
<p>GetEntry</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;GetEntry($form, $entry, $invalid, $values)</tt></p>
<p>Purpose</p>
<p>Retrieve the values of a given entry, if it is valid.</p>
<p>Implement this function if the scaffolding input will be viewing, updating or deleting individual entries.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$entry</tt> argument is a reference to an associative array that may be set by this function with values of properties of the <tt>form_scaffolding_class</tt> input. The array is passed to the function with an entry named <tt>ID</tt> set to the identifier of the entry to be retrieved. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties:</p>
<p>When viewing an entry: <tt>ViewingMessage</tt>, <tt>EntryOutput</tt>.</p>
<p>When updating an entry: <tt>UpdateCanceledMessage</tt>, <tt>UpdateMessage</tt>, <tt>UpdatedMessage</tt>.</p>
<p>When deleting an entry: <tt>DeleteMessage</tt>, <tt>DeleteCanceledMessage</tt>, <tt>DeletedMessage</tt>.</p>
<p>The <tt>$invalid</tt> argument is a reference to an a boolean variable that should be set by the function to <tt>1</tt> if the requested entry cannot be accessed for some reason.</p>
<p>The <tt>$values</tt> argument is a reference to an associative array that may be set by the function with values to assign to form inputs when an entry is being updated. The values in this array will be assigned to the respective form inputs after the function returns. <tt>checkbox</tt>, <tt>radio</tt> or other types of custom checkable inputs will have the <tt>CHECKED</tt> property set according to the assigned value which must be a boolean value.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
<p>SaveEntry</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;SaveEntry($form, $creating, $entry, $values)</tt></p>
<p>Purpose</p>
<p>Save the values of new or existing entries.</p>
<p>Implement this function if the scaffolding input will be used to create new entries or update existing entries.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$creating</tt> argument is boolean value that determines whether the entry is being created. Otherwise the function is being called to update an existing entry.</p>
<p>The <tt>$entry</tt> argument is a reference to an associative array that may be set by this function with values of properties of the <tt>form_scaffolding_class</tt> input. The array is passed to the function with an entry named <tt>ID</tt> set to the identifier of the entry to be saved when it is updating an existing entry. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties:</p>
<p>When creating an entry: <tt>CreatedMessage</tt>.</p>
<p>When updating an entry: <tt>UpdatedMessage</tt>.</p>
<p>The <tt>$values</tt> argument is a reference to an associative array with values with form inputs to create or update the entry. The values of <tt>checkbox</tt>, <tt>radio</tt> or other types of custom checkable inputs are boolean values that have the current state of the <tt>CHECKED</tt> state property.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
<p>ViewEntry</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;ViewEntry($form, $entry, $values)</tt></p>
<p>Purpose</p>
<p>Generate the output to display an entry.</p>
<p>Implement this function if you want to customize the presentation of an entry and the scaffolding input will be displaying a stored entry or previewing an entry with new values without saving.</p>
<p>Alternatively your data source class may simply inherit the base class behavior and automatically generate the presentation of entries by defining the variables <tt>entry_template</tt> and <tt>entry_template_properties</tt>.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$entry</tt> argument is a reference to an associative array that may be set by this function with values of properties of the <tt>form_scaffolding_class</tt> input. The array is passed to the function with an entry named <tt>ID</tt> set to the identifier of the entry to be displayed. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: <tt>ViewingMessage</tt>, <tt>EntryOutput</tt>.</p>
<p>The <tt>$values</tt> argument is a reference to an associative array with values of the entry fields. The values of <tt>checkbox</tt>, <tt>radio</tt> or other types of custom checkable inputs are boolean values that have the current state of the <tt>CHECKED</tt> state property.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
<p>DeleteEntry</p>
<ul>
<p>Synopsis</p>
<p><tt>$error = $data_source-&gt;DeleteEntry($form, $entry)</tt></p>
<p>Purpose</p>
<p>Delete a given entry.</p>
<p>Implement this function if the scaffolding input will be deleting specified entries.</p>
<p>Usage</p>
<p>The <tt>$form</tt> argument is a reference to the current forms class object. It may be used by the data source object to access the forms class for any purpose it may be necessary.</p>
<p>The <tt>$entry</tt> argument is a reference to an associative array that may be set by this function with values of properties of the <tt>form_scaffolding_class</tt> input. The array is passed to the function with an entry named <tt>ID</tt> set to the identifier of the entry to be deleted. The values set by the function in this array will be assigned to the scaffolding input properties right after the function returns. Currently it supports the following properties: <tt>DeletedMessage</tt>.</p>
<p>The <tt>$error</tt> return value should contain an error message if this function call did not succeed for some reason. Otherwise it should contain an empty string.</p>
</ul>
</ul>
</ul>
</ul>
<h4><li><a name="167.3.6"><tt>form_date_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>Let the user specify a date of the calendar with year, month and day.</p>
<h5>Features</h5>
<ul>
<p><li>It generates select inputs for the day and month and a text input for the year.</li></p>
<p><li>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.</li></p>
<p><li>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.</li></p>
<p><li>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.</li></p>
<p><li>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.</li></p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>Accessible</tt></li></p>
<p>The same as the <tt>Accessible</tt> property for basic inputs.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>AskAge</tt></li></p>
<p>Boolean flag that indicates the plug-in class to ask the user for an age relative to today's date.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>ChoiceDefaultValue</tt></li></p>
<p>Default value to be used when the <tt>ChooseControl</tt> option is set whether checkbox that appears should be initially set.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>Choose</tt></li></p>
<p>Boolean flag that indicates when the <tt>ChooseControl</tt> option is set whether checkbox that appears should be initially set.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>ChooseControl</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>DayClass</tt></li></p>
<p>Name of the presentation style class with which the day input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>DayStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the day input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>FixedDay</tt></li></p>
<p>Set the date day to a fixed value that cannot be changed by the user.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Format</tt> (changeable)</li></p>
<p>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: <tt>year</tt>, <tt>month</tt> and <tt>day</tt>.</p>
<p><b>Default value:</b> <tt>&quot;{year}-{month}-{day}&quot;</tt> or <tt>&quot;{year}-{month}&quot;</tt> when <tt>HideDay</tt> parameter is set to <tt>1</tt></p>
<p><li><tt>HideDay</tt></li></p>
<p>Hide the day field so it is not displayed to the user. This parameter may only be set to <tt>1</tt> if the <tt>FixedDay</tt> parameter is also set.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>MonthClass</tt></li></p>
<p>Name of the presentation style class with which the month input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>MonthStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the month input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Months</tt></li></p>
<p>Associative array that defines the text for each of the 12 months of the year. The array entry indexes go from <tt>&quot;01&quot;</tt> to <tt>&quot;12&quot;</tt>.</p>
<p><b>Default value:</b> array with all entry values set to the entry indexes</p>
<p><li><tt>Optional</tt></li></p>
<p>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 <tt>GetInputValue</tt> function returns an empty string.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>SelectYears</tt></li></p>
<p>Integer value that is used to determine whether year input will be displayed as input of type <tt>text</tt> or <tt>select</tt>.</p>
<p>If the <tt>ValidationStartDate</tt> and <tt>ValidationEndDate</tt> arguments are defined and the number of years between the two dates is less than the value of the <tt>SelectYears</tt> argument, the year is presented as a <tt>select</tt> type input with the given range of years as option values.</p>
<p><b>Default value:</b> <tt>10</tt></p>
<p><li><tt>TABINDEX</tt></li></p>
<p>Order of navigation of the input fields when using the tab key, as defined by the HTML <tt>TABINDEX</tt> attribute. When not set, all fields will have the same <tt>TABINDEX</tt> property value.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>VALUE</tt> (changeable)</li></p>
<p>Current value of the date. An empty string means, date not set. It may also be set to <tt>&quot;now&quot;</tt> as an alias to the current day date.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>ValidationDateErrorMessage</tt></li></p>
<p>Validation error message for when the user specifies a date that does not exist on the calendar.</p>
<p><b>Default value:</b> &quot;It was not specified a valid date.&quot;</p>
<p><li><tt>ValidationDayErrorMessage</tt></li></p>
<p>Validation error message for when the user specifies an invalid day.</p>
<p><b>Default value:</b> &quot;It was not specified a valid day.&quot;</p>
<p><li><tt>ValidationErrorMessage</tt></li></p>
<p>Default validation error message.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>ValidationEndDate</tt></li></p>
<p>Day of the end of the range of allowed dates. It may be set to <tt>&quot;now&quot;</tt> as an alias to the current day date.</p>
<p><b>Default value:</b> <tt>&quot;9999-12-31&quot;</tt></p>
<p><li><tt>ValidationEndDateErrorMessage</tt></li></p>
<p>Validation error message to present when the current date is set to a day after the end date.</p>
<p><b>Default value:</b> default validation error message</p>
<p><li><tt>ValidationMonthErrorMessage</tt></li></p>
<p>Validation error message for when the user specifies an invalid month.</p>
<p><b>Default value:</b> &quot;It was not specified a valid month.&quot;</p>
<p><li><tt>ValidationStartDate</tt></li></p>
<p>Day of the start of the range of allowed dates. It may be set to <tt>&quot;now&quot;</tt> as an alias to the current day date.</p>
<p><b>Default value:</b> <tt>&quot;0001-01-01&quot;</tt></p>
<p><li><tt>ValidationStartDateErrorMessage</tt></li></p>
<p>Validation error message to present when the current date is set to a day before the start date.</p>
<p><b>Default value:</b> default validation error message</p>
<p><li><tt>ValidationYearErrorMessage</tt></li></p>
<p>Validation error message for when the user specifies an invalid month.</p>
<p><b>Default value:</b> &quot;It was not specified a valid year.&quot;</p>
<p><li><tt>YearClass</tt></li></p>
<p>Name of the presentation style class with which the year input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>YearStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the year input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="170.3.7"><tt>form_html_editor_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>Let the user edit an HTML document visually.</p>
<h5>Features</h5>
<ul>
<p><li>The user can enter text and format it using toolbar buttons.</li></p>
<p><li>Is based on a JavaScript library that works with the most important browsers.</li></p>
<p><li>Fallback to a simple textarea in case JavaScript support is disabled in the browser.</li></p>
<p><li>Can insert custom template marks that presented with configurable preview HTML.</li></p>
<p><li>Can expand implicitly custom template marks in the HTML despite they may not be visible.</li></p>
<p><li>Can use a custom CSS stylesheet for the HTML document.</li></p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>CLASS</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>COLS</tt></li></p>
<p>Number of rows of the editor as defined for the <tt>COLS</tt> attribute of the <tt>&lt;TEXTAREA&gt;</tt> HTML tag.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>ExternalCSS</tt></li></p>
<p>URI of the CSS file that defines styles for use in the editor frame.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>JavascripPath</tt></li></p>
<p>Directory of the URI of the Javascript class file <tt>html_editor.js</tt>. If the directory of the URI of the current script if the same of the <tt>html_editor.js</tt> file, just leave this property set to an empty string.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>Mode</tt></li></p>
<p>Name of the editing mode. Valid modes are <tt>visual</tt> for the visual editor and <tt>html</tt> for the HTML editor.</p>
<p><b>Default value:</b> <tt>&quot;visual&quot;</tt></p>
<p><li><tt>ROWS</tt></li></p>
<p>Number of columns of the editor as defined for the <tt>COLS</tt> attribute of the <tt>&lt;TEXTAREA&gt;</tt> HTML tag.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>ShowToolbars</tt></li></p>
<p>Boolean flag that determines whether the editor toolbars are displayed.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>STYLE</tt></li></p>
<p>Definition of the presentation style attributes with which the editor container should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>TemplateVariables</tt></li></p>
<p>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:</p>
<ul>
<p><li><tt>Alternatives</tt></li></p>
<p>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 <tt>Preview</tt> and <tt>Title</tt> are supported. They have the same meaning as for the main template variable properties.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Inline</tt></li></p>
<p>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 <tt>Value</tt> property.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Preview</tt></li></p>
<p>HTML to be used when displaying the template variable preview in the visual editor.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Title</tt></li></p>
<p>Text to be used for the template variable in the insert template menu.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Value</tt></li></p>
<p>HTML value to expand the template variable when the <tt>Inline</tt> variable is not set.</p>
<p><b>Default value:</b> not set</p>
</ul>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="174.3.8"><tt>form_layout_paged_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>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.</li></p>
<p><li>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. Tabs may be hidden.</li></p>
<p><li>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.</li></p>
<p>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.</p>
<p><li>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.</li></p>
<p>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.</p>
<p>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.</p>
<p><li>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.</li></p>
<p>The presentation of the each page may also be customized using a sub-class of the <tt>form_layout_paged_class</tt> with a function named <tt>AddPagePart</tt>. This function takes just one parameter, which is the identifier of the current page to be rendered.</p>
<p><li>A page may appear with a fade-in effect when the user clicks on the respective tab button.</li></p>
<p><li>When a validation error occurs, the page with the first invalid field is switched automatically.</li></p>
<p><li>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.</li></p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>AutoAdjustSize</tt></li></p>
<p>Boolean flag that indicates whether the size of the container of the pages should be adjusted automatically to fit all pages.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>CurrentPage</tt> (changeable)</li></p>
<p>Identifier of the page that appears selected initially.</p>
<p><b>Default value:</b> first page</p>
<p><li><tt>FadePagesTime</tt></li></p>
<p>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 <tt>0</tt> to disable the page fade effect.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>JavascriptPath</tt></li></p>
<p>Directory of the URI of the Javascript class files necessary to implement animation effects.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>PageClass</tt></li></p>
<p><li><tt>TabClass</tt></li></p>
<p><li><tt>GapClass</tt></li></p>
<p><li><tt>PageButtonClass</tt></li></p>
<p><li><tt>TabButtonClass</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>&quot;&quot;</tt></p>
<p><li><tt>Pages</tt></li></p>
<p>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.</p>
<ul>
<p>Here follows the list of currently supported parameters:</p>
<p><li><tt>Name</tt> (required)</li></p>
<p>Name to display in the respective page tab.</p>
<p><b>Default value:</b> the same as the page identifier</p>
<p><li><tt>Caption</tt></li></p>
<p>Text to display in each page as a caption to explain the purpose of the page fields.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Break</tt></li></p>
<p>Name of the option to specify whether the respective page tab button should break the row of tab buttons on which it is displayed.</p>
<p>This option may be either <tt>&quot;before&quot;</tt> or <tt>&quot;after&quot;</tt> depending on whether the row of buttons should be split before or after the current page tab button.</p>
<p><b>Default value:</b> none</p>
</ul>
<p><li><tt>ShowTabs</tt></li></p>
<p>Boolean flag that indicates whether the tabs should be displayed or hidden.</p>
<p><b>Default value:</b> <tt>1</tt></p>
</ul>
<h5>Event connection actions</h5>
<ul>
<p>This custom input implements one types of action that can be triggered on the browser side: <tt>SwitchPage</tt>.</p>
<p>The <tt>SwitchPage</tt> action is used to switch the currently selected page. It supports the context arguments <tt>Page</tt>, <tt>PageValue</tt> and <tt>InputsPage</tt>.</p>
<p>The <tt>Page</tt> argument can be used to specify the identifier of a page to be switched.</p>
<p>Alternatively, the <tt>PageValue</tt> can be used to specify a JavaScript string variable or expression that will be used to dynamically set the identifier of the page to be switched.</p>
<p>The <tt>InputsPage</tt> 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.</p>
</ul>
</ul>
<h4><li><a name="179.3.9"><tt>form_layout_vertical_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type can be used to automatically compose the layout of a group of inputs that should appear vertically align.</p>
<h5>Features</h5>
<ul>
<p><li>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.</li></p>
<p><li>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.</li></p>
<p><li>This input can check the list of inputs considered invalid on the last call to the <tt>Validate</tt> function and render them with a special invalid input mark.</li></p>
<p><li>The default templates for the input rows can be customized for all inputs or only for specific inputs.</li></p>
<p><li>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.</li></p>
<p><li>Can display inputs in multiple side-by-side columns.</li></p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>Columns</tt></li></p>
<p>Bidimensional array that lists groups of identifiers of all the inputs to be included in the layout in side-by-side columns.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Data</tt></li></p>
<p>Associative array that specifies which of the inputs listed by the <tt>Inputs</tt> 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.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>DefaultMark</tt></li></p>
<p>HTML text string that defines how to render the input special mark for inputs that are not flagged as invalid.</p>
<p><b>Default value:</b> empty string</p>
<p><li><tt>Footer</tt></li></p>
<p>HTML text string that defines what should be rendered after the sequence of input rows.</p>
<p><b>Default value:</b> <tt> &lt;/table&gt; </tt></p>
<p><li><tt>Header</tt></li></p>
<p>HTML text string that defines what should be rendered before the sequence of input rows.</p>
<p><b>Default value:</b> <tt> &lt;table&gt; </tt></p>
<p><li><tt>InputFormat</tt></li></p>
<p>HTML template that defines how each input row should be rendered. It must have marks named <tt>{input}</tt>, <tt>{label}</tt> and <tt>{mark}</tt> to denote where the input, label and a special input mark respectively should appear in the input row.</p>
<p><b>Default value:</b> <tt> &lt;tr&gt;&lt;td valign=&quot;top&quot;&gt;{label}:&lt;/td&gt;&lt;td valign=&quot;top&quot;&gt;{input}&amp;nbsp;&lt;span id=&quot;mark_{id}&quot;&gt;{mark}&lt;/span&gt;&lt;/td&gt;&lt;/tr&gt; </tt></p>
<p><li><tt>Inputs</tt></li></p>
<p>Array that lists the identifiers of all the inputs to be included in the layout.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>InvalidMark</tt></li></p>
<p>HTML text string that defines how to render the input special mark for inputs that are flagged as invalid.</p>
<p><b>Default value:</b> empty string</p>
<p><li><tt>NoLabelInputFormat</tt></li></p>
<p>HTML template that defines how each input row should be rendered for inputs that do not have an associated label.</p>
<p><b>Default value:</b> <tt> &lt;tr&gt;&lt;td colspan=&quot;2&quot; align=&quot;center&quot;&gt;{input}&lt;/td&gt;&lt;/tr&gt; </tt></p>
<p><li><a name="form_layout_vertical_class-Properties"></a><tt>Properties</tt></li></p>
<p>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.</p>
<ul>
<p>Here follows the list of currently supported properties:</p>
<p><li><tt>CenteredPair</tt></li></p>
<p>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 <tt>left</tt>, <tt>middle</tt> or <tt>right</tt>, the respective input appears respectively on the left, middle or right of the centered group of inputs. Multiple inputs may be in the middle.</p>
<p>Currently, only inputs without labels can be presented as centered pairs.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>DefaultMark</tt></li></p>
<p>HTML text string that overrides the <tt>DefaultMark</tt> property value.</p>
<p><li><tt>Hidden</tt></li></p>
<p>Boolean flag that determines whether the input row should not appear visible in the form but should be added to the output as hidden input . If this property is <tt>0</tt>, the respective input row is ommited from the form output.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>InputFormat</tt></li></p>
<p>HTML template that overrides the <tt>InputFormat</tt> property value.</p>
<p><li><tt>InvalidMark</tt></li></p>
<p>HTML text string that overrides the <tt>InvalidMark</tt> property value.</p>
<p><li><tt>ReadOnly</tt></li></p>
<p>Boolean flag that determines whether the input should be rendered in read-only mode. If this property is <tt>1</tt>, the respective input cannot be edited.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>SwitchedPosition</tt></li></p>
<p>Boolean flag that determines whether the input row should present the input and the label in switched positions. If this property is <tt>1</tt>, the respective input appears in the place of the label and vice-versa.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>Visible</tt></li></p>
<p>Boolean flag that determines whether the input row should appear in the form output. If this property is <tt>0</tt>, the respective input row is ommited from the form output.</p>
<p><b>Default value:</b> <tt>1</tt></p>
</ul>
<p><li><tt>CenteredPairLeftInputFormat</tt></li></p>
<p>HTML template that defines how each input row should be rendered for inputs that have the <tt>CenteredPair</tt> property set to <tt>left</tt>.</p>
<p><b>Default value:</b> <tt> &lt;tr&gt;&lt;td colspan=&quot;2&quot; align=&quot;center&quot;&gt;{input}&amp;nbsp; </tt></p>
<p><li><tt>CenteredPairRightInputFormat</tt></li></p>
<p>HTML template that defines how each input row should be rendered for inputs that have the <tt>CenteredPair</tt> property set to <tt>right</tt>.</p>
<p><b>Default value:</b> <tt> {input}&lt;/td&gt;&lt;/tr&gt; </tt></p>
<p><li><tt>SwitchedPositionInputFormat</tt></li></p>
<p>HTML template that defines how each input row should be rendered for inputs that have the <tt>SwitchedPosition</tt> property set.</p>
<p><b>Default value:</b> <tt> &lt;tr&gt;&lt;td align=&quot;right&quot;&gt;{input}&lt;/td&gt;&lt;td&gt;{label}&amp;nbsp;&lt;span id=&quot;mark_{id}&quot;&gt;{mark}&lt;/span&gt;&lt;/td&gt;&lt;/tr&gt; </tt></p>
</ul>
</ul>
<h4><li><a name="183.3.10"><tt>form_linked_select_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type implements a <tt>select</tt> input that can let the user choose one or more options from multiple groups of options.</p>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>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.</li></p>
<p><li>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.</li></p>
<p><li>It supports select inputs of single or multiple selected options.</li></p>
</ul>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>select</tt> input type.</p>
<ul>
<p><li><tt>Groups</tt></li></p>
<p>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 <tt>OPTIONS</tt> attribute of the base <tt>select</tt> type input.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>LinkedInput</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Dynamic</tt></li></p>
<p>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 <tt>1</tt>, 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.</p>
<p>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.</p>
<p><b>Default value:</b> 0</p>
<p><li><tt>AutoWidthLimit</tt></li></p>
<p>Limit number of columns of width that this input will have initially. If this property is set and the <tt>Dynamic</tt> 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 <tt>0</tt> the class sets the initial display width of the <tt>select</tt> input to the length of the longest option in <tt>em</tt> units. If this property is more than <tt>0</tt>, the initial display width is set to no more columns than the value of this property.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>AutoHeightLimit</tt></li></p>
<p>Limit number of rows of height that this input will have. If this property is set and the <tt>Dynamic</tt> 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 <tt>0</tt> the class sets the number of rows of the <tt>select</tt> input the count of options of the longest group. If this property is more than <tt>0</tt>, the number of rows is set to no more than the value of this property.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="186.3.11"><tt>form_list_select_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type implements an emulation of a <tt>select</tt> input that allows to configure the presentation of the options as rows of a table with customizable HTML content.</p>
<h5>Features</h5>
<ul>
<p><li>It works in a compatible way with the regular <tt>select</tt> input.</li></p>
<p><li>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.</li></p>
<p><li>The options table can be displayed in a container with limited height that may scroll.</li></p>
<p><li>It uses <tt>radio</tt> inputs for single select lists and <tt>checkbox</tt> for multiple select inputs. An additional <tt>checkbox</tt> input is displayed to toggle the selection of all options of multiple select lists.</li></p>
</ul>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>select</tt> input type.</p>
<ul>
<p><li><tt>Accessible</tt></li></p>
<p>Boolean option to tell whether the input is accessible when the form is in read only mode, or not accessible otherwise.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>CLASS</tt></li></p>
<p>CSS style used to render the list select container.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Columns</tt></li></p>
<p>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:</p>
<ul>
<p><li><tt>Header</tt></li></p>
<p>HTML that will be displayed in the column header row.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Row</tt></li></p>
<p>Name of the entry of the array passed by the <tt>Rows</tt> parameter from which it will be displayed the data for the current column.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Type</tt></li></p>
<p>String that defines the type of the column. If the type is <tt>Input</tt>, the column will display a radio input to select the respective option. If the type is <tt>Data</tt>, the column will display data from the array passed by the <tt>Rows</tt> input parameter. If the type is <tt>Option</tt>, the column will display data from the respective option value.</p>
<p><b>Default value:</b> <tt>Data</tt></p>
</ul>
<p><b>Default value:</b> <tt>array(<br />
array(<br />
'Type'=&gt;'Input',<br />
),<br />
array(<br />
'Type'=&gt;'Option',<br />
),<br />
)</tt></p>
<p><li><tt>MULTIPLE</tt></li></p>
<p>Boolean option to tell whether the list will be a single or multiple select list.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>ONCHANGE</tt></li></p>
<p>Javascript code to be executed when the selected input changes.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>OptionReadOnlyMark</tt></li></p>
<p>HTML that defines what should be displayed in the place of each option input if the input is displayed as not accessible.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>OPTIONS</tt></li></p>
<p>Associative array that defines the values and text of a select field as defined for the <tt>OPTION</tt> HTML tag.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>ReadOnlyMark</tt></li></p>
<p>HTML that defines what should be displayed if the input is displayed as not accessible.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Rows</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>SELECTED</tt></li></p>
<p>Array of values of selected options when in <tt>multiple</tt> mode.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>SIZE</tt></li></p>
<p>Number of rows that occupies container of the list select table. The size of the container is defined in <tt>em</tt> units, so it may not match exactly the number of list select table rows that will be made visible.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>STYLE</tt></li></p>
<p>CSS style definition that will be used to render the list select container.</p>
<p><b>Default value:</b> <tt>border-style: solid; border-color: #808080 #ffffff #ffffff #808080; border-width: 1px</tt></p>
<p><li><tt>VALUE</tt></li></p>
<p>Value of the selected option.</p>
<p><b>Default value:</b> none</p>
</ul>
</ul>
<h4><li><a name="190.3.12"><tt>form_map_location_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>The <a href="http://www.google.com/apis/maps/">Google Maps API</a> is used to render and browse the maps.</li></p>
<p><li>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.</li></p>
<p><li>The currently selected location is denoted by a marker icon. Initially, the selected locations appears on the center of the map.</li></p>
<p><li>The text inputs of the coordinates of the selected may be rendered according to a configurable presentation template. These inputs may also be hidden.</li></p>
<p><li>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.</li></p>
<p><li>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.</li></p>
<p><li>The <tt>GetJavascriptSetInputProperty</tt> function can be used to generate Javascript commands to change the <tt>Latitude</tt> and <tt>Longitude</tt> properties from Javascript.</li></p>
<p><li>The maps can show advertising from Google AdSense to credit a given publisher.</li></p>
<p><li>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.</li></p>
<p><li>Can cluster one or more groups of custom markers in case they overlap in the same region.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><b>Google Maps API key</b></li></p>
<p>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 <a href="http://www.google.com/apis/maps/signup.html">Google Maps API signup page</a>.</p>
<p><li><b>Page head, load and unload</b></li></p>
<p>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 <tt>PageHead</tt> function to retrieve the necessary HTML tags to be inserted within the page head section.</p>
<p>This kind of input must be initialized from the page body load event. Use the main forms class <tt>PageLoad</tt> function to retrieve the necessary Javascript code to assign to the <tt>ONLOAD</tt> attribute of the page <tt>BODY</tt> HTML tag.</p>
<p>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 <tt>PageUnload</tt> function to retrieve the necessary Javascript code to assign to the <tt>ONUNLOAD</tt> attribute of the page <tt>BODY</tt> HTML tag.</p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>Accessible</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>AdsManager</tt></li></p>
<p>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.</p>
<ul>
<p><li><tt>Channel</tt></li></p>
<p>Identifier of the publisher account channel to be associated with advertising that is displayed.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>MaxAdsOnMap</tt></li></p>
<p>Limit number of advertising units that can be displayed in the map.</p>
<p><b>Default value:</b> 2</p>
<p><li><tt>Publisher</tt></li></p>
<p>Identifier of the AdSense publisher account. Usually starts with <tt>ca-pub-</tt>.</p>
<p><b>Default value:</b> none</p>
</ul>
<p><b>Default value:</b> none</p>
<p><li><tt>BoundsOffset</tt></li></p>
<p>Value to adjust the coordinates bounding box to set the zoom level automatically when the <tt>ZoomMarkers</tt> property is specified. A positive value makes the bounding box expand.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>CLASS</tt></li></p>
<p>CSS stylesheet used to render the <tt>&lt;div&gt;</tt> tag on which the map will appear.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Clusters</tt></li></p>
<p>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:</p>
<ul>
<p><li><tt>Manager</tt></li></p>
<p>Name of the type of cluster that will aggregate the markers. Currently only the <tt>MarkerClusterer</tt> marker manager is supported.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Path</tt></li></p>
<p>Path URL of the script that defines the marker manager Javascript class. For <tt>MarkerClusterer</tt> marker manager the default path is <tt>markerclusterer.js</tt>.</p>
<p><b>Default value:</b> none</p>
</ul>
<p><li><tt>Controls</tt></li></p>
<p>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: <tt>&quot;SmallMap&quot;</tt>, <tt>&quot;LargeMap&quot;</tt>, <tt>&quot;SmallZoom&quot;</tt>, <tt>&quot;Scale&quot;</tt>, <tt>&quot;MapOverview&quot;</tt> and <tt>&quot;MapType&quot;</tt>. Currently no control properties are supported.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Coordinates</tt></li></p>
<p>Boolean flag that determines whether the coordinate values should be displayed along with the map.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>HideMarker</tt></li></p>
<p>Boolean flag that determines whether the location marker should not be displayed.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>Icons</tt></li></p>
<p>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: <tt>image</tt>, <tt>shadow</tt>, <tt>printImage</tt>, <tt>mozPrintImage</tt>, <tt>transparent</tt>, <tt>dragCrossImage</tt>, <tt>iconSize</tt>, <tt>shadowSize</tt>, <tt>dragCrossSize</tt>, <tt>iconAnchor</tt>, <tt>infoWindowAnchor</tt>, <tt>dragCrossAnchor</tt>, <tt>maxHeight</tt> and <tt>imageMap</tt>.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Key</tt></li></p>
<p>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 <a href="http://www.google.com/apis/maps/signup.html">Google Maps API signup page</a>.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Format</tt></li></p>
<p>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: <tt>map</tt>, <tt>latitude</tt>, <tt>latitudelabel</tt>, <tt>longitude</tt>, <tt>longitudelabel</tt>, <tt>zoom</tt> and <tt>maptype</tt>.</p>
<p><b>Default value:</b> <tt> &quot;{map}\n&lt;br /&gt;\n&lt;div&gt;{latitudelabel} {latitude} {longitudelabel} {longitude}&lt;/div&gt;\n{zoom}\n{maptype}&quot; </tt></p>
<p><li><tt>Latitude</tt> (changeable)</li></p>
<p>Initial latitude coordinate value of the selected map location.</p>
<p><b>Default value:</b> <tt>0.0</tt></p>
<p><li><tt>LatitudeClass</tt></li></p>
<p>CSS stylesheet used to render the latitude text input.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>LatitudeLabel</tt></li></p>
<p>Label for the latitude text input.</p>
<p><b>Default value:</b> <tt>&quot;Latitude:&quot;</tt></p>
<p><li><tt>LatitudeStyle</tt></li></p>
<p>CSS style definition used to render the latitude text input.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Longitude</tt> (changeable)</li></p>
<p>Initial longitude coordinate value of the selected map location.</p>
<p><b>Default value:</b> <tt>0.0</tt></p>
<p><li><tt>LongitudeClass</tt></li></p>
<p>CSS stylesheet used to render the longitude text input.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>LongitudeLabel</tt></li></p>
<p>Label for the longitude text input.</p>
<p><b>Default value:</b> <tt>&quot;Longitude:&quot;</tt></p>
<p><li><tt>LongitudeStyle</tt></li></p>
<p>CSS style definition used to render the longitude text input.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>MapType</tt></li></p>
<p>Type of rendering used to display the map. There are three types of map rendering: <tt>Normal</tt> for rendering maps as colored polygons, <tt>Satellite</tt> for display satellite photographs, and <tt>Hybrid</tt> for rendering roads as polygons over satellite photographs.</p>
<p><b>Default value:</b> <tt>&quot;Normal&quot;</tt></p>
<p><li><tt>MarkerIcon</tt></li></p>
<p>Name of a custom icon to be used as the marker.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Markers</tt></li></p>
<p>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:</p>
<ul>
<p><li><tt>Cluster</tt></li></p>
<p>Name of the cluster that will aggregate the markers that overlap in the current zoom level for being in the same region.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Information</tt></li></p>
<p>HTML string that defines the contents of the marker information window. This window opens when the mouse is over the marker.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Icon</tt></li></p>
<p>Name of a custom icon to be used as the marker.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Latitude</tt></li></p>
<p>Latitude coordinate value of the marker location.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Link</tt></li></p>
<p>URL of the page to be opened when the user clicks on the marker icon.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Longitude</tt></li></p>
<p>Longitude coordinate value of the marker location.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Title</tt></li></p>
<p>Title text to associate to the marker. Usually it appears as a tooltip when the mouse is over the marker, like with the HTML <tt>TITLE</tt> tag.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Target</tt></li></p>
<p>Name of the window or frame on which the page specified the <tt>Link</tt> marker property will be opened. If this marker property is not specified, the page will be opened on the same browser window.</p>
<p><b>Default value:</b> none</p>
</ul>
<p><b>Default value:</b> none</p>
<p><li><tt>NoCoordinatesFormat</tt></li></p>
<p>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: <tt>map</tt>, <tt>latitude</tt>, <tt>longitude</tt>, <tt>zoom</tt> and <tt>maptype</tt>.</p>
<p><b>Default value:</b> <tt> &quot;{map}\n{latitude}\n{longitude}\n{zoom}\n{maptype}&quot; </tt></p>
<p><li><tt>STYLE</tt></li></p>
<p>CSS style definition used to render the <tt>&lt;div&gt;</tt> tag on which the map will appear.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>ValidationErrorMessage</tt></li></p>
<p>Error message to display when the user enters invalid coordinate values.</p>
<p><b>Default value:</b> <tt>&quot;It was not specified a valid location.&quot;</tt></p>
<p><li><tt>ZoomBounds</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>ZoomMarkers</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>ZoomLevel</tt></li></p>
<p>Level of zoom to display the map. <tt>0</tt> 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.</p>
<p><b>Default value:</b> <tt>0</tt></p>
</ul>
<h5>Event connection actions</h5>
<ul>
<p>This custom input implements one type of action that can be triggered on the browser side: <tt>LocateAddress</tt>.</p>
<p>The <tt>LocateAddress</tt> 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.</p>
<p>The <tt>LocateAddress</tt> action supports the context arguments <tt>Address</tt>, <tt>Country</tt> and <tt>CountryValue</tt>.</p>
<p>The <tt>Address</tt> argument can be used to specify the input from which the address to be located will be taken.</p>
<p>The <tt>Country</tt> 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.</p>
<p>The <tt>CountryValue</tt> 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 <tt>Country</tt> option. It can be either <tt>Value</tt> to use the current input value, or <tt>SelectedOption</tt> to use the text value of the current option of the country input.</p>
</ul>
</ul>
<h4><li><a name="198.3.13"><tt>form_mdb2_auto_complete_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type extends the <tt>form_auto_complete_class</tt>. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.</p>
<p>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.</p>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>form_auto_complete_class</tt> custom input type but the context of some properties has changed.</p>
<ul>
<p><li><tt>CompleteValues</tt></li></p>
<p>No longer applies.</p>
<p><li><tt>Connection</tt></li></p>
<p>Database connection object as returned by the function <tt>MDB2::connect</tt>. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>CompleteValuesQuery</tt></li></p>
<p>SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark <tt>{BEGINSWITH}</tt> to specify where it will be inserted the SQL <tt>LIKE</tt> pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>CompleteValuesLimit</tt></li></p>
<p>Maximum number of result entries that will be displayed in the auto-complete menu.</p>
<p><b>Default value:</b> 10</p>
</ul>
</ul>
<h4><li><a name="200.3.14"><tt>form_mdb2_linked_select_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type extends the <tt>form_linked_select_class</tt>. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.</p>
<p>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.</p>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>form_linked_select_class</tt> custom input type but the context of some properties has changed.</p>
<ul>
<p><li><tt>Groups</tt></li></p>
<p>No longer applies.</p>
<p><li><tt>Dynamic</tt></li></p>
<p>Same meaning but the default value has changed.</p>
<p><b>Default value:</b> 1</p>
<p><li><tt>Connection</tt></li></p>
<p>Database connection object as returned by the function <tt>MDB2::connect</tt>. Keep in mind that this object must be passed by reference under PHP 4 to prevent inadverted object copies.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>OptionsQuery</tt></li></p>
<p>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 <tt>?</tt> to specify where the group identifier value should be used.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>DefaultOption</tt></li></p>
<p>Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>DefaultOptionValue</tt></li></p>
<p>Text value associated to the option specified by the <tt>DefaultOption</tt> parameter.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>GroupsQuery</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="202.3.15"><tt>form_metabase_auto_complete_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type extends the <tt>form_auto_complete_class</tt>. It provides the same functionality but retrieves the list of auto-complete texts from a database rather than from static arrays.</p>
<p>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.</p>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>form_auto_complete_class</tt> custom input type but the context of some properties has changed.</p>
<ul>
<p><li><tt>CompleteValues</tt></li></p>
<p>No longer applies.</p>
<p><li><tt>Connection</tt></li></p>
<p>Database connection setup handle as returned by the function <tt>MetabaseSetupDatabase</tt>.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>CompleteValuesQuery</tt></li></p>
<p>SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark <tt>{BEGINSWITH}</tt> to specify where it will be inserted the SQL <tt>LIKE</tt> pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>CompleteValuesLimit</tt></li></p>
<p>Maximum number of result entries that will be displayed in the auto-complete menu.</p>
<p><b>Default value:</b> 10</p>
</ul>
</ul>
<h4><li><a name="204.3.16"><tt>form_metabase_linked_select_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type extends the <tt>form_linked_select_class</tt>. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.</p>
<p>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.</p>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>form_linked_select_class</tt> custom input type but the context of some properties has changed.</p>
<ul>
<p><li><tt>Groups</tt></li></p>
<p>No longer applies.</p>
<p><li><tt>Dynamic</tt></li></p>
<p>Same meaning but the default value has changed.</p>
<p><b>Default value:</b> 1</p>
<p><li><tt>Connection</tt></li></p>
<p>Database connection setup handle as returned by the function <tt>MetabaseSetupDatabase</tt>.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>OptionsQuery</tt></li></p>
<p>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 <tt>?</tt> to specify where the group identifier value should be used.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>DefaultOption</tt></li></p>
<p>Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>DefaultOptionValue</tt></li></p>
<p>Text value associated to the option specified by the <tt>DefaultOption</tt> parameter.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>GroupsQuery</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="206.3.17"><tt>form_mysql_auto_complete_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type extends the <tt>form_auto_complete_class</tt>. It provides the same functionality but retrieves the list of auto-complete texts from a MySQL database rather than from static arrays.</p>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>form_auto_complete_class</tt> custom input type but the context of some properties has changed.</p>
<ul>
<p><li><tt>CompleteValues</tt></li></p>
<p>No longer applies.</p>
<p><li><tt>Connection</tt></li></p>
<p>Database connection handle as returned by the functions <tt>mysql_connect</tt> or <tt>mysql_pconnect</tt>.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>CompleteValuesQuery</tt></li></p>
<p>SQL query string that should be executed to retrieve the auto-complete texts. This query must have the mark <tt>{BEGINSWITH}</tt> to specify where it will be inserted the SQL <tt>LIKE</tt> pattern matching operator to search for the texts that completes the first few letters that the user typed in the text input.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>CompleteValuesLimit</tt></li></p>
<p>Maximum number of result entries that will be displayed in the auto-complete menu.</p>
<p><b>Default value:</b> 10</p>
</ul>
</ul>
<h4><li><a name="208.3.18"><tt>form_mysql_linked_select_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input type extends the <tt>form_linked_select_class</tt>. It provides the same functionality but retrieves the alternative groups of objects from a database rather than from static arrays.</p>
<p>It uses the PHP MySQL functions directly to execute the SQL queries that retrieve groups of options.</p>
<h5>Properties</h5>
<p>This custom input type supports most of the properties of base <tt>form_linked_select_class</tt> custom input type but the context of some properties has changed.</p>
<ul>
<p><li><tt>Groups</tt></li></p>
<p>No longer applies.</p>
<p><li><tt>Dynamic</tt></li></p>
<p>Same meaning but the default value has changed.</p>
<p><b>Default value:</b> 1</p>
<p><li><tt>Connection</tt></li></p>
<p>Database connection setup handle as returned by the functions <tt>mysql_connect</tt> or <tt>mysql_pconnect</tt>.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>OptionsQuery</tt></li></p>
<p>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 <tt>{GROUP}</tt> to specify where the group identifier value should be used.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>DefaultOption</tt></li></p>
<p>Additional option that should be added to the list of options retrieved from the database and should be the initially selected option.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>DefaultOptionValue</tt></li></p>
<p>Text value associated to the option specified by the <tt>DefaultOption</tt> parameter.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>GroupsQuery</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="210.3.19"><tt>form_recaptcha_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This custom input provides an alternative to the <tt><a href="#form_captcha_class">form_captcha_class</a></tt> plug-in to perform <a href="http://en.wikipedia.org/wiki/Captcha">CAPTCHA</a> validation based on <a href="http://www.google.com/recaptcha">Google Recaptcha</a> Web service.</p>
<h5>Features</h5>
<ul>
<p><li>It generates a text input and JavaScript to show an image with the validation text generated by the Recaptcha service.</li></p>
<p><li>It shows a link to let the users request that the image be redrawn with a new validation text that may be less difficult to read.</li></p>
<p><li>It also shows a link to switch to play the validation text as audio for visually impaired users.</li></p>
<p><li>The layout of the image, text input and links is configurable using a template.</li></p>
<p><li>The validation of the entered text is done by sending HTTP requests to the Recaptcha Web services API.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><b>The HTTP client class</b></li></p>
<p>The <a href="http://www.phpclasses.org/httpclient">HTTP client class</a> is necessary to send HTTP requests to the Recaptcha Web services API.</p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>Format</tt> (changeable)</li></p>
<p>Format of the template that defines how the text input, the image and the control links will be presented. There are seven supported place holders for defining how the input layout will be presented:</p>
<p><tt>image</tt> - the validation image</p>
<p> <tt>instructions_visual</tt> - the label for the text input in image validation mode</p>
<p> <tt>instructions_audio</tt> - the label for the text input in audio validation mode</p>
<p> <tt>refresh_btn</tt> - the reload image or replay audio link</p>
<p> <tt>audio_challenge</tt> - the link to switch to the audio validation mode</p>
<p> <tt>visual_challenge</tt> - the link to switch to the text validation mode</p>
<p> <tt>help_btn</tt> - the help link</p>
<p><b>Default value:</b> <tt>&quot;&lt;div&gt;{image}&lt;/div&gt; &lt;div&gt;{instructions_visual}{instructions_audio} {input}&lt;/div&gt; &lt;div&gt;{refresh_btn} {visual_challenge}{audio_challenge} {help_btn}&lt;/div&gt;&quot;</tt></p>
<p><li><tt>InputClass</tt></li></p>
<p>Name of the presentation style class with which the text input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>InputExtraAttributes</tt></li></p>
<p>List of extra attributes that should be added to the text input HTML tag when the form output is generated.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>InputStyle</tt></li></p>
<p>Definition of the presentation style attributes with which the text input field should be rendered.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>InputTabIndex</tt></li></p>
<p>Order of navigation of the text input field when using the tab key, as defined by the HTML <tt>TABINDEX</tt> attribute.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Key</tt> (required)</li></p>
<p>Public key text used to generate the challenge text for validation. It should be obtained from the <a href="https://www.google.com/recaptcha/admin/create">Google Recaptcha</a> site.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>PrivateKey</tt> (required)</li></p>
<p>Private key text used to send the text validation request to the Google Recaptcha API. It should be obtained from the <a href="https://www.google.com/recaptcha/admin/create">Google Recaptcha</a> site.</p>
<p><b>Default value:</b> not set</p>
<p><li><tt>Text</tt> (required)</li></p>
<p>Associative array for the text messages displayed by this custom input.</p>
<p>Here follow the current default text messages:</p>
<p><tt>instructions_visual</tt> - 'Enter the words above'</p>
<p> <tt>instructions_audio</tt> - 'Enter the numbers you hear'</p>
<p> <tt>visual_challenge</tt> - 'Enter text in an image instead'</p>
<p> <tt>audio_challenge</tt> - 'Enter numbers you hear instead'</p>
<p> <tt>refresh_btn</tt> - 'Try another'</p>
<p> <tt>help_btn</tt> - 'Help'</p>
<p> <tt>play_again</tt> - 'Play the sound again'</p>
<p> <tt>cant_hear_this</tt> - 'Download the sound as a MP3 file'</p>
<p> <tt>image_alt_text</tt> - 'Image with text to enter'</p>
<p><li><tt>ValidationErrorMessage</tt> (required)</li></p>
<p>Error message to return when the input value does not match the validation text.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="form_scaffolding_class"></a><a name="214.3.20"><tt>form_scaffolding_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>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 <i>CRUD</i> actions: Create, Read, Update and Delete.</p>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>The create, read, update and delete actions can be enabled or disabled as needed by the application.</li></p>
<p><li>Initially, a listing of entries is presented as a table with columns that display the values of different entry properties.</li></p>
<p><li>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.</li></p>
<p><li>Optional pagination links may be displayed to let the user browse long listings of entries split over multiple pages.</li></p>
<p><li>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.</li></p>
<p><li>Listings entries may also be defined by custom templates that may be made of arbitrary HTML, or even custom inputs or labels, so the listing can be used for bulk editing a list of data records.</li></p>
<p><li>The create, update and delete actions present a form with a configurable list of inputs to let the user set the entry properties.</li></p>
<p><li>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.</li></p>
<p><li>The texts of all feedback messages are configurable.</li></p>
<p><li>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.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><b>form_ajax_submit_class</b></li></p>
<p>This plug-in class is necessary to interact with the server without page reloading.</p>
<p><li><b>form_layout_vertical_class</b></li></p>
<p>This plug-in class is necessary to automatically layout the inputs of the forms for editing or deleting entries.</p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>AppendMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed appended to the status message that reports the result of the current operation.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>CancelLabel</tt></li></p>
<p>Text for the cancel submit button.</p>
<p><b>Default value:</b> <tt>Cancel</tt></p>
<p><li><tt>Create</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>CreateCanceledMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when the new entry creation form was canceled.</p>
<p><b>Default value:</b> <tt>Creating a new entry was canceled.</tt></p>
<p><li><tt>CreatedMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when a new entry is created successfully.</p>
<p><b>Default value:</b> <tt>A new entry was created successfully.</tt></p>
<p><li><tt>CreateMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed initially along with the new entry creation form.</p>
<p><b>Default value:</b> <tt>Create a new entry</tt></p>
<p><li><tt>CreatePreviewMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when showing a preview of a new entry in the creation form.</p>
<p><b>Default value:</b> <tt>New entry preview</tt></p>
<p><li><tt>Columns</tt> (changeable)</li></p>
<p>Array with entries that define the way each column in the entries listing should be displayed.</p>
<p>Each entry in this array should be set to an associative array that defines the respective column properties.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<h6>Column properties</h6>
<ul>
<p><tt>Class</tt></p>
<p>CSS class used to display values of the column.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><tt>Delete</tt></p>
<p>Boolean option to tell whether the column should display a link to start the delete form for the respective row entry.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><tt>Format</tt></p>
<p>HTML template that may define how the column values are displayed.</p>
<p><b>Default value:</b> use the value directly</p>
<p><tt>FormatMap</tt></p>
<p>Associative array that contains alternative HTML templates that may define how the column values are displayed.</p>
<p>If the current listing value is one the keys of the format map array, the respective array entry is used as template.</p>
<p><b>Default value:</b> use the value directly</p>
<p><tt>FormatParameters</tt></p>
<p>Associative array that defines how each template placeholder should be replaced.</p>
<p>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.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p>Template placeholder properties</p>
<ul>
<p><tt>Column</tt></p>
<p>Number of the column from which the default template placeholder value should be retrieved.</p>
<p><b>Default value:</b> current column number</p>
<p><tt>HTML</tt></p>
<p>Boolean option to tell that the value should be encoded as HTML before displaying.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><tt>InputColumn</tt></p>
<p>Name of a column that will contain the identifier of a previously added input to be displayed in the current placeholder position. If the current listing row does not have set the column defined by this parameter value, the placeholder position will not show any input. Other parameters will display to what will appear in the current placeholder position.</p>
<p><b>Default value:</b> none</p>
<p><tt>LabelColumn</tt></p>
<p>Name of a column that will contain the identifier of a previously added input whose label should be displayed in the current placeholder position. If the current listing row does not have set the column defined by this parameter value, the placeholder position will not show any label. Other parameters will display to what will appear in the current placeholder position.</p>
<p><b>Default value:</b> none</p>
<p><tt>Map</tt></p>
<p>Associative array that determines how values should be mapped to alternative HTML representations.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><tt>MapNull</tt></p>
<p>Value to use when the column value is undefined.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><tt>Replace</tt></p>
<p>Associative array that defines a list of regular expressions that will be used to find and replace column values.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
</ul>
<p><tt>Header</tt></p>
<p>HTML to display in the header row of the column.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><tt>HTML</tt></p>
<p>Boolean option to tell that the column value should be encoded as HTML before displaying.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><tt>ID</tt></p>
<p>Boolean option to tell whether the column values have the respective entry identifiers.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><tt>InputColumn</tt></p>
<p>Name of a listing column that will contain the identifier of a previously added input to be displayed in the current column for the current listing row. If the current listing row does not have set the column defined by this parameter value, the current listing entry will not show any input. Other parameters will display to what will appear in the current listing entry.</p>
<p><b>Default value:</b> none</p>
<p><tt>LabelColumn</tt></p>
<p>Name of a listing column that will contain the identifier of a previously added input whose label should be displayed in the current column for the current listing row. If the current listing row does not have set the column defined by this parameter value, the current listing entry will not show any label. Other parameters will display to what will appear in the current listing entry.</p>
<p><b>Default value:</b> none</p>
<p><tt>Map</tt></p>
<p>Associative array that determines how values should be mapped to alternative HTML representations.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><tt>MapNull</tt></p>
<p>Value to use when the column value is undefined.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><tt>Replace</tt></p>
<p>Associative array that defines a list of regular expressions that will be used to find and replace column values.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><tt>Style</tt></p>
<p>CSS style used to display values of the column.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><tt>Update</tt></p>
<p>Boolean option to tell whether the column should display a link to start the update form for the respective row entry.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><tt>View</tt></p>
<p>Boolean option to tell whether the column should display a link to display an entry.</p>
<p><b>Default value:</b> <tt>0</tt></p>
</ul>
<p><li><tt>CustomParameters</tt></li></p>
<p>Associative array with custom parameters and values that applications need to pass to each page to keep context.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>Delete</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>DeleteCanceledMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when an existing entry delete form was canceled.</p>
<p><b>Default value:</b> <tt>Deleting the entry was canceled.</tt></p>
<p><li><tt>DeletedMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when an existing entry is deleted successfully.</p>
<p><b>Default value:</b> <tt>The entry was deleted successfully.</tt></p>
<p><li><tt>DeleteFields</tt></li></p>
<p>Array with the definitions of each input that will be used in the forms to delete entries.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>DeleteLabel</tt></li></p>
<p>Text for the delete links and submit button.</p>
<p><b>Default value:</b> <tt>Delete</tt></p>
<p><li><tt>DeleteMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed along with the entry delete form.</p>
<p><b>Default value:</b> <tt>Are you sure you want to delete this entry?</tt></p>
<p><li><tt>Editing</tt> (get only)</li></p>
<p>Boolean flag that tells whether the user is creating, updating or deleting an entry.</p>
<p><li><tt>Entry</tt> (changeable)</li></p>
<p>Identifier of the entry to be updated or deleted.</p>
<p><b>Default value:</b> not defined</p>
<p><li><tt>EntryFields</tt></li></p>
<p>Array with the definitions of each input that will be used in the forms to create or update entries.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>EntryFieldNames</tt> (get only)</li></p>
<p>Array with the names of the entry fields added to the create or update forms.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>ErrorMessageFormat</tt></li></p>
<p>HTML template used to display validation errors. The placeholder <tt>{errormessage}</tt> should be used to define where the actual validation error message should appear.</p>
<p><b>Default value:</b> <tt> &lt;div style=&quot;text-align: center; font-weight: bold&quot;&gt;{errormessage}&lt;/div&gt; </tt></p>
<p><li><tt>EvenRowListingClass</tt></li></p>
<p>Name of the CSS class to display the even rows of the entries listing table.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>EvenRowListingColor</tt></li></p>
<p>Background of the even rows of the entries listing table.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>ExternalParameters</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>FieldLayoutProperties</tt> (changeable)</li></p>
<p>Associative array with layout properties for each of the entry fields. The array entry indexes are the identifiers of the fields. The array entry values are also associative arrays with properties for each field as defined for the <tt><a href="#form_layout_vertical_class-Properties">form_layout_vertical_class Properties attribute</a></tt> plug-in.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>FormFooter</tt> (changeable)</li></p>
<p>HTML template used to append to the section with the layout of the forms to create, update and delete entries.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>FormHeader</tt> (changeable)</li></p>
<p>HTML template used to prepend to the section with the layout of the forms to create, update and delete entries.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>IDColumn</tt> (changeable)</li></p>
<p>Number of the column in the array passed to the <tt>Rows</tt> property that contains the value of the identifier of each entry to be listed.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>InvalidMark</tt></li></p>
<p>HTML to mark invalid form fields.</p>
<p><b>Default value:</b> <tt>[X]</tt></p>
<p><li><tt>ListingClass</tt></li></p>
<p>Name of the CSS class to use for the table that presents the entries listing.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>ListingMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed while displaying the entries listing.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>ListingPadding</tt></li></p>
<p>Padding of cells of the entries listing table.</p>
<p><b>Default value:</b> <tt>2</tt></p>
<p><li><tt>ListingSpacing</tt></li></p>
<p>Spacing for the entries listing table.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>ListingStyle</tt></li></p>
<p>CSS styles to use for the table that presents the entries listing.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>Loaded</tt></li></p>
<p>Boolean value that sets the loaded state of scaffolding input. The loaded state is changed to <tt>1</tt> during the call to the <tt>LoadInputValues</tt> function. If it is necessary to load the input values again, set this property to <tt>0</tt> before calling the <tt>LoadInputValues</tt> function.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>NoEntriesMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when there are no listing entries to display.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>OddRowListingClass</tt></li></p>
<p>Name of the CSS class to display the odd rows of the entries listing table.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>OddRowListingColor</tt></li></p>
<p>Background of the odd rows of the entries listing table.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>Page</tt> (changeable)</li></p>
<p>Number of the current page of the entries listing to display starting from <tt>1</tt>.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>PageEntries</tt> (changeable)</li></p>
<p>Limit number of entries to display on each page of the entries listing. If set to <tt>0</tt> or there are no more entries in the listing than the page entries value, no pagination navigation is displayed.</p>
<p><b>Default value:</b> <tt>10</tt></p>
<p><li><tt>Preview</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>PreviewLabel</tt></li></p>
<p>Text for the preview submit button.</p>
<p><b>Default value:</b> <tt>Preview</tt></p>
<p><li><tt>EntryOutput</tt> (changeable)</li></p>
<p>HTML to display an entry being viewed or the preview of the entry being created or updated.</p>
<p><b>Default value:</b> <tt></tt></p>
<p><li><tt>Read</tt></li></p>
<p>Boolean option to determine whether the plug-in will present the listing of existing entries to be eventually edited or deleted.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>Rows</tt> (changeable)</li></p>
<p>Bidimensional array with data to display in the entries listing.</p>
<p><b>Default value:</b> <tt>array()</tt></p>
<p><li><tt>RowStyleClass</tt> (changeable)</li></p>
<p>Name of a listing column that will contain the name of CSS class that should be used for the respective listing table rows. If the listing column defined by this parameter entry is not defined for the current row, the current row CSS class is not changed.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>RowStyleColumn</tt> (changeable)</li></p>
<p>Name of a listing column that will contain a string with CSS styles definitions that should be used for the respective listing table rows. If the listing column defined by this parameter entry is not defined for the current row, the current row CSS styles are not changed.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>Save</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>SaveLabel</tt></li></p>
<p>Text for the save submit button.</p>
<p><b>Default value:</b> <tt>Save</tt></p>
<p><li><tt>State</tt></li></p>
<p>Initial state of the user interface. Currently it supports the following states:</p>
<ul>
<p><li>create_canceled</li></p>
<p>The form to create a new entry was canceled.</p>
<p><li>create_previewing</li></p>
<p>A preview of the entry being created is displayed.</p>
<p><li>created</li></p>
<p>The form to create a new entry was submitted.</p>
<p><li>creating</li></p>
<p>The form to create a new entry is being displayed.</p>
<p><li>delete_canceled</li></p>
<p>The form to delete an existing entry was canceled.</p>
<p><li>deleted</li></p>
<p>The form to delete an existing entry was submitted.</p>
<p><li>deleting</li></p>
<p>The form to delete an existing entry is being displayed.</p>
<p><li>listing</li></p>
<p>The listing of entries is being displayed.</p>
<p><li>update_canceled</li></p>
<p>The form to update an existing entry was canceled.</p>
<p><li>update_previewing</li></p>
<p>A preview of the entry being updated is displayed.</p>
<p><li>updated</li></p>
<p>The form to update an existing entry was submitted.</p>
<p><li>updating</li></p>
<p>The form to update an existing entry is being displayed.</p>
<p><li>viewing</li></p>
<p>A view of a stored entry is displayed.</p>
</ul>
<p><b>Default value:</b> <tt>listing</tt></p>
<p><li><tt>SubmitLabel</tt></li></p>
<p>Text for the main submit button.</p>
<p><b>Default value:</b> <tt>Submit</tt></p>
<p><a name="form_scaffolding_class-Property-TargetInput"></a><li><tt>TargetInput</tt> (changeable)</li></p>
<p>Identifier of the input to which the event messages will be forwarded. If this property is not set, the event messages will be queued for retrieval by the application.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>TotalEntries</tt> (changeable)</li></p>
<p>Total number of the entries that can be displayed.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>Update</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>1</tt></p>
<p><li><tt>UpdateCanceledMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when an existing entry update form was canceled.</p>
<p><b>Default value:</b> <tt>Updating an entry was canceled.</tt></p>
<p><li><tt>UpdateInput</tt></li></p>
<p>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</p>
<p><b>Default value:</b> none</p>
<p><li><tt>UpdatedMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when an existing entry is updated successfully.</p>
<p><b>Default value:</b> <tt>The entry was updated successfully.</tt></p>
<p><li><tt>UpdateLabel</tt></li></p>
<p>Text for the update links and submit button.</p>
<p><b>Default value:</b> <tt>Update</tt></p>
<p><li><tt>UpdateMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed along with the entry update form.</p>
<p><b>Default value:</b> <tt>Update this entry</tt></p>
<p><li><tt>UpdatePreviewMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed when showing a preview of an existing entry in the update form.</p>
<p><b>Default value:</b> <tt>Updated entry preview</tt></p>
<p><li><tt>View</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>ViewLabel</tt></li></p>
<p>Text for the view links.</p>
<p><b>Default value:</b> <tt>View</tt></p>
<p><li><tt>ViewingMessage</tt> (changeable)</li></p>
<p>HTML of the message that should be displayed along with the view of an entry.</p>
<p><b>Default value:</b> <tt>Viewing entry</tt></p>
</ul>
<h5>Messages</h5>
<ul>
<p>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.</p>
<p>When the form is submitted, it posts messages to the application during the call to the <tt>LoadInputValues</tt> 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.</p>
<p>The posted messages need to be retrieved using the <tt>GetNextMessage</tt> function, and replied with <tt>ReplyMessage</tt> function, so the plug-in can generate the appropriate HTML and Javascript to respond to the form submission requests.</p>
<p>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.</p>
<p>Currently, it post the following types of messages that correspond to all the possible states of the input:</p>
<p><li><tt>create_canceled</tt></li></p>
<p>This type of message is posted when the user clicked on the cancel button while the new entry form was being displayed.</p>
<p>Usually, applications do not need to do anything before replying to this type of message.</p>
<p><li><tt>create_previewing</tt></li></p>
<p>This type of message is posted when the user clicked on the preview button while the new entry form is being displayed.</p>
<p>Applications should call the <tt>LoadInputValues</tt> and the <tt>Validate</tt> 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 <tt>EntryOutput</tt> property.</p>
<p><li><tt>created</tt></li></p>
<p>This type of message is posted when the user submitted the form to create a new entry.</p>
<p>Applications should call the <tt>LoadInputValues</tt> and the <tt>Validate</tt> like with a regular form submission. If the form is valid the application should create the new entry.</p>
<p>The message <tt>Entry</tt> entry should be set to identifier of the newly created entry before replying to the message.</p>
<p><li><tt>creating</tt></li></p>
<p>This type of message is posted when user is editing a new entry, eventually because he clicked on the new entry creation link.</p>
<p>Usually, applications do not need to do anything before replying to this type of message.</p>
<p><li><tt>delete_canceled</tt></li></p>
<p>This type of message is posted when the user clicked on the cancel button while the delete entry form was being displayed.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry to be deleted.</p>
<p>Usually, applications do not need to do anything before replying to this type of message.</p>
<p><li><tt>deleted</tt></li></p>
<p>This type of message is posted when the user submitted the form to delete an existing entry.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry to be deleted.</p>
<p>Applications should call the <tt>LoadInputValues</tt> and the <tt>Validate</tt> 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.</p>
<p><li><tt>deleting</tt></li></p>
<p>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.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry to be deleted.</p>
<p>Usually, applications do not need to do anything before replying to this type of message.</p>
<p><li><tt>listing</tt></li></p>
<p>This type of message is posted when the entries listing needs to be displayed. The application must set the properties <tt>TotalEntries</tt>, <tt>PageEntries</tt>, <tt>Rows</tt> to let the plug-in determine what it should list.</p>
<p>Applications may also set the <tt>IDColumn</tt> and <tt>Columns</tt> properties to define the how the listing should be presented, if those properties were not previously defined when the custom input was added.</p>
<p>The message has the <tt>Page</tt> entry set to the page of the entries listing should be displayed starting from <tt>1</tt>.</p>
<p>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 <tt>Page</tt> property.</p>
<p><li><tt>update_canceled</tt></li></p>
<p>This type of message is posted when the user clicked on the cancel button while the update entry form was being displayed.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry being edited.</p>
<p>Usually, applications do not need to do anything before replying to this type of message.</p>
<p><li><tt>update_previewing</tt></li></p>
<p>This type of message is posted when the user clicked on the preview button while the update entry form is being displayed.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry being edited.</p>
<p>Usually applications should do the same when processing <tt>create_previewing</tt> messages.</p>
<p><li><tt>updated</tt></li></p>
<p>This type of message is posted when the user submitted the form to update an existing entry.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry being edited.</p>
<p>Applications should call the <tt>LoadInputValues</tt> and the <tt>Validate</tt> like with a regular form submission. If the form is valid the application should update the entry records.</p>
<p><li><tt>updating</tt></li></p>
<p>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.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry being edited.</p>
<p>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.</p>
<p><li><tt>viewing</tt></li></p>
<p>This type of message is posted when the user clicked on a link to view an entry.</p>
<p>The message <tt>Entry</tt> entry is set to the identifier of the entry to be displayed.</p>
<p>Usually applications should do the same when processing <tt>update_previewing</tt> messages, but display the stored entry values instead.</p>
<h6>Message parameters</h6>
<p>All the types of posted messages contain certain common entries. These common entries should not be changed by the application.</p>
<p>The <tt>Event</tt> entry is set to the type of message. The <tt>From</tt> and <tt>ReplyTo</tt> entries define the identifier of the custom input that posted the message. The <tt>AJAX</tt> entry is set when the form was submitted via AJAX.</p>
<p>Besides the types of entries that applications should set when replying to each type of message, applications may also set the <tt>Cancel</tt> entry to <tt>1</tt> 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.</p>
<p>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.</p>
</ul>
</ul>
<h4><li><a name="222.3.21"><tt>form_secure_submit_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>This input is used to prevent <a href="http://en.wikipedia.org/wiki/Csrf">Cross-Site Request Forgery</a> (CSRF) security attacks.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>It adds a <tt>submit</tt> or <tt>image</tt> input and an <tt>hidden</tt> 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</li></p>
<p><li>The validation value expires after a given period of time. Applications may retrieve the <tt>Expired</tt> 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.</li></p>
<p><li>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.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><b>The mcrypt library extension</b></li></p>
<p>The class requires the PHP is configured to use the <a href="http://www.php.net/manual/en/ref.mcrypt.php">mcrypt library extension</a> to be able to encrypt the validation value.</p>
</ul>
<h5>Properties</h5>
<p>This custom input plug-in class takes the same properties as the inputs of type <tt>submit</tt> and <tt>image</tt>. Additionally, the class also supports the properties below.</p>
<p>If you specify the <tt>SRC</tt> property, an <tt>image</tt> input will be added. Otherwise, it will be added an input of type <tt>submit</tt>.</p>
<ul>
<p><li><tt>ExpiryTime</tt></li></p>
<p>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.</p>
<p><b>Default value:</b> <tt>300</tt></p>
<p><li><tt>Expired</tt> (read-only)</li></p>
<p>Boolean flag that tells whether the validation value has expired after calling the main forms class <tt>WasSubmitted</tt> function.</p>
<p><b>Default value:</b> <tt>0</tt></p>
<p><li><tt>Key</tt> (required)</li></p>
<p>Private key that is used to encrypt the validation value.</p>
<p><b>Default value:</b> not set</p>
</ul>
</ul>
<h4><li><a name="226.3.22"><tt>form_upload_progress_class</tt></a></li></h4>
<ul>
<h5>Purpose</h5>
<p>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.</p>
<h5>Features</h5>
<ul>
<p><li>A progress bar may be displayed in a specified position of the form page. The format of the bar can be customized.</li></p>
<p><li>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.</li></p>
<p><li>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.</li></p>
</ul>
<h5>Requirements</h5>
<ul>
<p><li><b>PHP version with upload monitor support</b></li></p>
<p>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.</p>
<p><li><b>PHP upload progress extension</b></li></p>
<p>The class also requires that the current PHP installation has the upload progress extension available. Currently that extension can be obtained from the <a href="http://pecl.php.net/package/uploadprogress">PECL repository</a>.</p>
<p><li><b>Form AJAX submit plug-in</b></li></p>
<p>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.</p>
</ul>
<h5>Properties</h5>
<ul>
<p><li><tt>FeedbackElement</tt></li></p>
<p>Identifier of the page element within which the progress bar and other upload statistic details will appear.</p>
<p><b>Default value:</b> none</p>
<p><li><tt>FeedbackFormat</tt></li></p>
<p>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 <tt>FeedbackElement</tt> with the resulting HTML data. Here follows the supported template marks:</p>
<ul>
<p><li><tt>{ACCURATE_PROGRESS}</tt></li></p>
<p>Percentage of the amount of data uploaded so far. This value is represented as a decimal value.</p>
<p><li><tt>{AVERAGE_SPEED}</tt></li></p>
<p>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.</p>
<p><li><tt>{CURRENT_SPEED}</tt></li></p>
<p>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.</p>
<p><li><tt>{PROGRESS}</tt></li></p>
<p>Percentage of the amount of data uploaded so far. This value is represented as a rounded integer value.</p>
<p><li><tt>{REMAINING}</tt></li></p>
<p>Expected time remaining till the end of the upload. This value may appear with <tt>:</tt> within the values of remaining seconds, minutes and hours.</p>
<p><li><tt>{TOTAL}</tt></li></p>
<p>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.</p>
<p><li><tt>{UPLOADED}</tt></li></p>
<p>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.</p>
</ul>
<p><b>Default value:</b> <tt>{PROGRESS}%</tt></p>
<p><b>Example value:</b> <tt> &lt;table style=&quot;width: 200px&quot; border=&quot;1&quot;&gt;&lt;tr&gt; &lt;td style=&quot;width: {ACCURATE_PROGRESS}%; border-style: none; background-color: #0000ff; background-image: url(progress.gif); text-align: center;&quot;&gt;{PROGRESS}%&lt;/td&gt; &lt;td style=&quot;border-style: none;&quot;&gt;&lt;/td&gt; &lt;/tr&gt;&lt;/table&gt; </tt></p>
</ul>
</ul>
</ul>
</ul>
</ul>
<hr />
<address>Manuel Lemos (<a href="mailto:mlemos-at-acm.org">mlemos-at-acm.org</a>)</address>
</body>
</html>
Copy permalink