The purpose of this document is to provide a reference guide for users to access while incorporating this project into their development.
Before getting started, you will need to download the latest version of this project, unzip formbuilder.zip, and install the php-form-builder-class directory in a publicly accessible location on your web server. After you've done this, you're ready to get started creating your first form using this project.
Let's begin by looking at the code snippet of our "Hello World" form seen below...
<?php
include("php-form-builder-class/class.form.php");
$form = new form("HelloWorld");
$form->setAttributes(array(
"width" => 400
));
$form->addTextbox("My Textbox:", "MyTextbox", "Hello World");
$form->addButton();
$form->render();
?>
The first thing you'll notice is that class.form.php is included with...
<?php
include("php-form-builder-class/class.form.php");
?>
This file can be found within the php-form-builder-class directory, and must be included in each script that makes use of this project.
Next, a new form object is created with...
<?php
$form = new form("HelloWorld");
?>
An identifier, "HelloWorld" in this case, is included. If this identifier is not provided, "myform" will be used; however, it is recommended that you include an identifier with each form you create. This becomes increasingly important when multiple forms are rendered on the same webpage.
Once the form object is created, the setAttributes() function is invoked...
<?php
$form->setAttributes(array(
"width" => 400
));
?>
The setAttributes() function accepts an associative array of key/value pairs, and is used to assign various attributes to the form. Chances are, you will be calling this function in most all of the forms you create. In this "Hello World" example, the form's width is set to 400 pixels.
Now, we're ready to add our form elements. In our "Hello World" example, there's only one element - a textbox.
<?php
$form->addTextbox("My Textbox:", "MyTextbox", "Hello World");
?>
More information on how to work with textboxes and all the other form elements can be found in the Form Elements section. This textbox has a label assigned as "My Textbox:", a name set to "MyTextbox", and a default value of "Hello World".
A button is attached to the form with...
<?php
$form->addButton();
?>
The addButton() function has optional parameters for customizing the appearance and behavior of your buttons. With no paramaters provided, it will render a submit button titled "Submit".
The final function called is render()...
<?php
$form->render();
?>
The render() function is responsible for a variety of tasks including building the form's html markup, including the appropriate javascript/css include files, and applying javascript validation if applicable.
Congratulations! You have just created your first form using the PHP Form Builder Class. If you're like me, and like learning about a new piece of software by jumping right in and using it, you should check out the other included examples, which provide a more in depth look at the various functionality included in this project. If you're not like me, and like learning about a new piece of software by reading the manual first, then you should continue reading this document.
The latest release of this project - version 1.1.3 - contains support for 26 form element types. These include button, captcha, checkbox, checksort, ckeditor, colorpicker, country, date, daterange, email, expdate, file, hidden, html, htmlexternal, latlng, password, radio, select, sort, state, textarea, textbox, truefalse, webeditor, and yesno. Let's take a closer look at how each of these form element types can be used in your development.
I chose to begin with textboxes because they're arguably the most frequently used form element on the web. Chances are, the first form you build with this project will contain a textbox - so, let's get started. Textboxes are added to your forms through the addTextbox function. See the code snippet provided below.
<?php
/* addTextbox Function Declaration
public function addTextbox($label, $name, $value="", $additionalParams="") {}
*/
$form->addTextbox("My Textbox", "Textbox");
$form->addTextbox("My Prefilled Textbox", "Textbox", "This is my default value.");
$form->addTextbox("My Required Textbox", "Textbox", "", array("required" => 1));
?>
This function has four available parameters: label, name, value, and additionalParams. Many of the functions responsible for adding form elements follow this same pattern. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the textbox. |
| name | Corresponds to the name attribute of the <input> tag. |
| value | Optional - Corresponds to the value attribute of the <input> tag. This can be used to set the textbox's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the textbox. The third example seen above demonstrates how this parameter can be used to apply the required setting. See the additionalParams section for all available settings that can be passed in this array. |
Selectboxes are added to your forms via the addSelect function. This function is very similar to addTextbox; however, there is one additional parameter - options - that is used to populate the selectbox's <option> tags. This parameter can be passed as either a one dimensional array or as an associative array of key/value pairs. The first and second examples provided below illustrate how the options paramter affects the value and displayed text of each <option> tag.
<?php
/* addSelect Function Declaration
public function addSelect($label, $name, $value="", $options="", $additionalParams="") {}
*/
$form->addSelect("My Selectbox", "Selectbox", "", array("Option #1", "Option #2", "Option #3"));
/*
<option value="Option #1">Option #1</option>
<option value="Option #2">Option #2</option>
<option value="Option #3">Option #3</option>
*/
$form->addSelect("My Selectbox", "Selectbox", "", array("1" => "Option #1", "2" => "Option #2", "3" => "Option #3"));
/*
<option value="1">Option #1</option>
<option value="2">Option #2</option>
<option value="3">Option #3</option>
*/
$form->addSelect("My Prefilled Selectbox", "Selectbox", "Option #2", array("Option #1", "Option #2", "Option #3"));
$form->addSelect("My Prefilled Selectbox", "Selectbox", "1", array("1" => "Option #1", "2" => "Option #2", "3" => "Option #3"));
$form->addSelect("My Multiple Selectbox", "Selectbox", "", array("Option #1", "Option #2", "Option #3"), array("multiple" => "multiple"));
$form->addSelect("My Prefilled/Multiple Selectbox", "Selectbox",
array("Option #1", "Option #2"),
array("Option #1", "Option #2", "Option #3"),
array("multiple" => "multiple")
);
?>
This function has five available parameters: label, name, value, options, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the selectbox. |
| name | Corresponds to the name attribute of the <select> tag. If you are using the multiple setting and do not append "[]" to the end this parameter, it will by appended for you automatically. |
| value | Corresponds to the value attribute of an <option> tag. This can be used to set the selectbox's default value. If the options parameter contains an associative array, the value will need to correspond with a key of that array. This parameter can also contain an array of vales if the multiple setting is also being used. See the third, fourth, and sixth examples above for reference. |
| options | Used to populate the selectbox's options. This parameter can either by passed as a one dimensional array, or as an associative array. If a one dimensional array supplied, each option's value and displayed text will be set to the appropriate array's value. If an associative array is supplied, the array's keys will be used for the option's values and the array's values will be used for the option's displayed text. See the first and second examples above for reference. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the selectbox. The fifth example seen above demonstrates how this parameter can be used to apply the multiple setting. See the additionalParams section for all available settings that can be passed in this array. |
Checkboxes are added to your forms via the addCheckbox function. This function is used to generate a group of checkboxes, not just one. Similar to the addSelect function, there is an options parameter that is used to populate each checkbox's value and displayed text. This parameter can be passed as either a one dimensional array or as an associative array of key/value pairs. The first and second examples provided below illustrate how the options paramter affects each checkbox in the group.
<?php
/* addCheckbox Function Declaration
public function addCheckbox($label, $name, $value="", $options="", $additionalParams="") {}
*/
$form->addCheckbox("My Checkboxes", "Checkbox", "", array("Option #1", "Option #2", "Option #3"));
/*
<input type="checkbox" name="Checkbox[]" id="Checkbox-0" value="Option #1"/><label for="Checkbox-0">Option #1</label>
<input type="checkbox" name="Checkbox[]" id="Checkbox-1" value="Option #2"/><label for="Checkbox-1">Option #2</label>
<input type="checkbox" name="Checkbox[]" id="Checkbox-2" value="Option #3"/><label for="Checkbox-2">Option #3</label>
*/
$form->addCheckbox("My Checkboxes", "Checkbox", "", array("1" => "Option #1", "2" => "Option #2", "3" => "Option #3"));
/*
<input type="checkbox" name="Checkbox[]" id="Checkbox-0" value="1"/><label for="Checkbox-0">Option #1</label>
<input type="checkbox" name="Checkbox[]" id="Checkbox-1" value="2"/><label for="Checkbox-0">Option #2</label>
<input type="checkbox" name="Checkbox[]" id="Checkbox-2" value="3"/><label for="Checkbox-0">Option #3</label>
*/
$form->addCheckbox("My Selected Checkboxes", "Checkbox", "Option #2", array("Option #1", "Option #2", "Option #3"));
$form->addCheckbox("My Selected Checkboxes", "Checkbox", "1", array("1" => "Option #1", "2" => "Option #2", "3" => "Option #3"));
$form->addCheckbox("My Selected Checkboxes", "Checkbox", array("1", "3"), array("1" => "Option #1", "2" => "Option #2", "3" => "Option #3"));
?>
This function has five available parameters: label, name, value, options, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the group of checkboxes. |
| name | Corresponds to the name attribute for each <input> tag in the checkbox group. If you do not append "[]" to the end this parameter, it will by appended for you automatically. |
| value | Corresponds to the value attribute of each <input> tag in the checkbox group. This can be used to check one or more of the checkboxes by default. If the options parameter contains an associative array, the value will need to correspond with a key of that array. This parameter can be a single value or an array of values. See the third, fourth, and fifth examples above for reference. |
| options | Used to generate each <input> tag in the checkbox group. This parameter can either by passed as a one dimensional array, or as an associative array. If a one dimensional array supplied, each checkbox's value and displayed text will be set to the appropriate array's value. If an associative array is supplied, the array's keys will be used for the checkbox's values and the array's values will be used for its displayed text. See the first and second examples above for reference. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the checkbox group. See the additionalParams section for all available settings that can be passed in this array. |
Radio buttons are added to your forms via the addRadio function. This function is used to generate a group of radio buttons, not just one. There is an options parameter that is used to populate each radio button's value and displayed text. This parameter can be passed as either a one dimensional array or as an associative array of key/value pairs. The first and second examples provided below illustrate how the options paramter affects each radio button in the group.
<?php
/* addRadio Function Declaration
public function addRadio($label, $name, $value="", $options="", $additionalParams="") {}
*/
$form->addRadio("My Radio Buttons", "Radio", "", array("Option #1", "Option #2", "Option #3"));
/*
<input type="radio" name="Radio" id="Radio-0" value="Option #1"/><label for="Radio-0">Option #1</label>
<input type="radio" name="Radio" id="Radio-1" value="Option #2"/><label for="Radio-1">Option #2</label>
<input type="radio" name="Radio" id="Radio-2" value="Option #3"/><label for="Radio-2">Option #3</label>
*/
$form->addRadio("My Radio Buttons", "Radio", "", array("1" => "Option #1", "2" => "Option #2", "3" => "Option #3"));
/*
<input type="radio" name="Radio" id="Radio-0" value="1"/><label for="Radio-0">Option #1</label>
<input type="radio" name="Radio" id="Radio-1" value="2"/><label for="Radio-0">Option #2</label>
<input type="radio" name="Radio" id="Radio-2" value="3"/><label for="Radio-0">Option #3</label>
*/
$form->addRadio("My Selected Radio Buttons", "Radio", "Option #2", array("Option #1", "Option #2", "Option #3"));
$form->addRadio("My Selected Radio Buttons", "Radio", "1", array("1" => "Option #1", "2" => "Option #2", "3" => "Option #3"));
?>
This function has five available parameters: label, name, value, options, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the group of radio buttons. |
| name | Corresponds to the name attribute for each <input> tag in the radio button group. |
| value | Corresponds to the value attribute of each <input> tag in the radio group. This can be used to check one radio button by default. If the options parameter contains an associative array, the value will need to correspond with a key of that array. See the third and fourth examples above for reference. |
| options | Used to generate each <input> tag in the radio button group. This parameter can either by passed as a one dimensional array, or as an associative array. If a one dimensional array supplied, each radio button's value and displayed text will be set to the appropriate array's value. If an associative array is supplied, the array's keys will be used for the radio button's values and the array's values will be used for its displayed text. See the first and second examples above for reference. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the radio button group. See the additionalParams section for all available settings that can be passed in this array. |
Textboxes are added to forms by invoking the addTextarea function, which is nearly identical to the addTextbox function.
<?php
/* addTextarea Function Declaration
public function addTextarea($label, $name, $value="", $additionalParams="") {}
*/
$form->addTextarea("My Textarea", "Textarea");
$form->addTextarea("My Prefilled Textarea", "Textarea", "This is my default value.");
?>
This function has four available parameters: label, name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the textarea. |
| name | Corresponds to the name attribute of the <textarea> tag. |
| value | Optional - Corresponds to the content between the opening and closing <textarea> tags. This can be used to set the textarea's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the textarea. See the additionalParams section for all available settings that can be passed in this array. |
Hidden inputs are added to forms by invoking the addHidden function. The label parameter is not included in this function because hidden inputs do not make use of labels.
<?php
/* addHidden Function Declaration
public function addHidden($name, $value="", $additionalParams="") {}
*/
$form->addHidden("Hidden", "MyHiddenValue");
?>
This function has three available parameters: name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| name | Corresponds to the name attribute of the <input> tag. |
| value | Optional - Corresponds to the value attribute of the <input> tag. This can be used to set the hidden input's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the hidden input. See the additionalParams section for all available settings that can be passed in this array. |
File inputs are added to forms by invoking the addFile function. The <form> tag's enctype attribute will be automatically set to "multipart/form-data" if this function is used on a form to attach a file element type. There is no need for the value parameter, so it is omitted from the function's declaration.
<?php
/* addFile Function Declaration
public function addFile($label, $name, $additionalParams="") {}
*/
$form->addFile("My File", "File");
?>
This function has three available parameters: label, name, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the file input. |
| name | Corresponds to the name attribute of the <input> tag. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the file input. See the additionalParams section for all available settings that can be passed in this array. |
The state element type is a shortcut for adding a selectbox with options for each of the 50 U.S. states, 13 Canadian provinces/territories, and 7 U.S. territories. The values for these options are set to their appropriate two character code. Because the options are pre-determined, the options parameter is omitted from the function's declaration.
<?php
/* addState Function Declaration
public function addState($label, $name, $value="", $additionalParams="") {}
*/
$form->addState("My State", "State");
?>
This function has four available parameters: label, name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the selectbox. |
| name | Corresponds to the name attribute of the <select> tag. If you are using the multiple setting and do not append "[]" to the end this parameter, it will by appended for you automatically. |
| value | Corresponds to the value attribute of an <option> tag. This can be used to set the selectbox's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the selectbox. See the additionalParams section for all available settings that can be passed in this array. |
Like the state element type, the addCountry function is a shortcut for adding a selectbox with options for countries throughout the world. The values for these options are set to their appropriate two character code. Because the options are pre-determined, the options parameter is omitted from the function's declaration.
<?php
/* addCountry Function Declaration
public function addCountry($label, $name, $value="", $additionalParams="") {}
*/
$form->addCountry("My Country", "Country");
?>
This function has four available parameters: label, name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the selectbox. |
| name | Corresponds to the name attribute of the <select> tag. If you are using the multiple setting and do not append "[]" to the end this parameter, it will by appended for you automatically. |
| value | Corresponds to the value attribute of an <option> tag. This can be used to set the selectbox's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the selectbox. See the additionalParams section for all available settings that can be passed in this array. |
The addYesNo function is a shortcut for adding a radio button group with options for "Yes" and "No". The values for these options are set to "1" and "0" respectively. Because the options are pre-determined, the options parameter is omitted from the function's declaration.
<?php
/* addYesNo Function Declaration
public function addYesNo($label, $name, $value="", $additionalParams="") {}
*/
$form->addYesNo("My Yes/No", "YesNo");
?>
This function has four available parameters: label, name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the radio button group. |
| name | Corresponds to the name attribute of each radio button's <input> tag in the group. |
| value | Corresponds to the value attribute of each radio button's <input> tag in the group. This can be used to set the elements default value - "1" for "Yes", "0" for "No". |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the element. See the additionalParams section for all available settings that can be passed in this array. |
The addTrueFalse function is a shortcut for adding a radio button group with options for "True" and "False". The values for these options are set to "1" and "0" respectively. Because the options are pre-determined, the options parameter is omitted from the function's declaration.
<?php
/* addTrueFalse Function Declaration
public function addTrueFalse($label, $name, $value="", $additionalParams="") {}
*/
$form->addTrueFalse("My True/False", "TrueFalse");
?>
This function has four available parameters: label, name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the radio button group. |
| name | Corresponds to the name attribute of each radio button's <input> tag in the group. |
| value | Corresponds to the value attribute of each radio button's <input> tag in the group. This can be used to set the elements default value - "1" for "True", "0" for "False". |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the element. See the additionalParams section for all available settings that can be passed in this array. |
The email element type is essentially a textbox with built-in javascript/php email validation. Javascript validation is triggered in the form's pre-defined onsubmit function. If the element's value is not empty, an AJAX call is made to validate the element's content. If the textbox does not contain a valid email address, an appropriate error message will be dispalyed. PHP validation is triggered by making use of the validate function after the form's data has been submitted. Both javascript and php validation make use of an open source project found at http://code.google.com/p/php-email-address-validation/. See the Email Validation example file for reference.
<?php
/* addEmail Function Declaration
public function addEmail($label, $name, $value="", $additionalParams="") {}
*/
$form->addEmail("My Textbox w/Email Validation", "Email");
?>
This function has four available parameters: label, name, value, and additionalParams. Many of the functions responsible for adding form elements follow this same pattern. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the textbox. |
| name | Corresponds to the name attribute of the <input> tag. |
| value | Optional - Corresponds to the value attribute of the <input> tag. This can be used to set the textbox's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the textbox. The third example seen above demonstrates how this parameter can be used to apply the required setting. See the additionalParams section for all available settings that can be passed in this array. |
The date element type makes use of jQueryUI's datepicker functionality to allow a single date to be selected from a calendar. The calendar is triggered from a pre-defined onclick javascript event. By default, this element will have a hint set to "Click to Select Date..."; however, this can be modified by applying the hint element attribute as seen in the third example provided below.
The formatting of the date returned from the calendar will be set to "MM d, yy" by default, which is equivalent to "F j, Y" using php's date function. If you want to modify this formatting, you can include the "dateFormat" option in the jqueryOption element attribute. The fourth example below shows how to change the date's formatting to a MySQL friendly format. Use http://docs.jquery.com/UI/Datepicker/formatDate for a guide to using jQuery's date formatting options.
When setting this element's default value via the function's value parameter, remember that the string passed to the function must match the date format that is being used. See the second example below for reference.
jQueryUI's datepicker has many options you can use to tailor the functionality to fit to your specific needs. To apply these options, make use of the jqueryOptions element attribute. We've already seen how this attribute can be used to change the formatting of the date returned. Now, let's look at example five below and see how we can display multiple months on the calendar as well as restrict the date range to plus or minus 30 days. See http://jqueryui.com/demos/datepicker/ for more information on jQueryUI's datepicker plugin and all the available options that can be applied via the jqueryOptions element attribute. Keep in mind that if you are setting a jQuery option to a piece of javascript code via the jqueryOptions attribute, you will need to prepend your string with "js:" for it to be handled correctly.
<?php
/* addDate Function Declaration
public function addDate($label, $name, $value="", $additionalParams="") {}
*/
$form->addDate("My Date", "Date");
$form->addDate("My Prefilled Date", "Date", date("F j, Y"));
$form->addDate("My Date w/Custom Hint", "Date", "", array("hint" => "To select a date, click here..."));
$form->addDate("My Date w/MySQL Formatting", "Date", "", array("jqueryOptions" => array(
"dateFormat" => "yy-mm-dd"
)));
$form->addDate("My Date w/Multiple Months & Restricted Range", "Date", "", array("jqueryOptions" => array(
"numberOfMonths" => 2,
"minDate" => "-30",
"maxDate" => "+30"
?>
This function has four available parameters: label, name, value, and additionalParams. Many of the functions responsible for adding form elements follow this same pattern. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the textbox. |
| name | Corresponds to the name attribute of the <input> tag. |
| value | Optional - Corresponds to the value attribute of the <input> tag. This can be used to set the textbox's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the textbox. The third example seen above demonstrates how this parameter can be used to apply the required setting. See the additionalParams section for all available settings that can be passed in this array. |
Like the date element, the addDateRange function makes use of jQueryUI's datepicker functionality; however, it allows a date range or single date to be selected from pre-defined list or a calendar - not just a single date. To facilitate this, a jQuery plugin developed by filament group is used. More information about this plugin can be found at http://www.filamentgroup.com/lab/date_range_picker_using_jquery_ui_16_and_jquery_ui_css_framework/. The list/calendar is triggered from a onclick javascript event which is automatically applied to the textbox. By default, this element will have a hint set to "Click to Select Date Range..."; however, this can be modified by applying the hint element attribute as seen in the third example provided below.
The formatting of the dates returned from the calendar will be set to "MM d, yy" by default, which is equivalent to "F j, Y" using php's date function. If you want to modify this formatting, you can include the "dateFormat" option in the jqueryOption element attribute. The fourth example below shows how to change the date's formatting to a MySQL friendly format. Use http://docs.jquery.com/UI/Datepicker/formatDate for a guide to using jQuery's date formatting options.
When setting this element's default value via the function's value parameter, remember that the string passed to the function must match the date format that is being used. See the second example below for reference.
jQueryUI's datepicker has many options you can use to tailor the functionality to fit to your specific needs. To apply these options, make use of the jqueryOptions element attribute. We've already seen how this attribute can be used to change the formatting of the date returned. Now, let's look at example five below and see how we can restrict the date range to plus or minus 60 days. The same jQuery options that can can be applied to the date element type can also by applied in the addDateRange function. See http://jqueryui.com/demos/datepicker/ for more information on jQueryUI's datepicker plugin and all the available options that can be applied via the jqueryOptions element attribute. Keep in mind that if you are setting a jQuery option to a piece of javascript code via the jqueryOptions attribute, you will need to prepend your string with "js:" for it to be handled correctly.
<?php
/* addDateRange Function Declaration
public function addDateRange($label, $name, $value="", $additionalParams="") {}
*/
$form->addDateRange("My Date Range", "DateRange");
$form->addDateRange("My Prefilled Date Range", "DateRange", date("F j, Y", strtotime("-1 month")) . " - " . date("F j, Y"));
$form->addDateRange("My Date Range w/Custom Hint", "DateRange", "", array("hint" => "To select a date range, click here..."));
$form->addDateRange("My Date Range w/MySQL Formatting", "DateRange", "", array("jqueryOptions" => array(
"dateFormat" => "yy-mm-dd"
)));
$form->addDateRange("My Date Range w/Multiple Months & Restricted Range", "DateRange", "", array("jqueryOptions" => array(
"minDate" => "-60",
"maxDate" => "+60"
?>
This function has four available parameters: label, name, value, and additionalParams. Many of the functions responsible for adding form elements follow this same pattern. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the textbox. |
| name | Corresponds to the name attribute of the <input> tag. |
| value | Optional - Corresponds to the value attribute of the <input> tag. This can be used to set the textbox's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the textbox. The third example seen above demonstrates how this parameter can be used to apply the required setting. See the additionalParams section for all available settings that can be passed in this array. |
TinyMCE's javascript WYSIWYG editor can be added with the addWebEditor function. For more information on TinyMCE, see http://tinymce.moxiecode.com/. Like the CKEditor web editor, a simplified toolbar can be triggered by including the basic element attribute.
<?php
/* addWebEditor Function Declaration
public function addWebEditor($label, $name, $value="", $additionalParams="") {}
*/
$form->addWebEditor("My TinyMCE Web Editor", "TinyMCE");
$form->addWebEditor("My Prefilled TinyMCE Editor", "TinyMCE", "This is my default value.");
$form->addWebEditor("My Basic TinyMCE Editor", "TinyMCE", "", array("basic" => 1));
?>
This function has four available parameters: label, name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the textarea. |
| name | Corresponds to the name attribute of the <textarea> tag. |
| value | Optional - Corresponds to the content between the opening and closing <textarea> tags. This can be used to set the textarea's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the textarea. See the additionalParams section for all available settings that can be passed in this array. |
CKEditor's WYSIWYG editor can be added with the addCKEditor function. For more information on CKEditor, see http://ckeditor.com/. Like the TinyMCE web editor, a simplified toolbar can be triggered by including the basic element attribute.
<?php
/* addCKEditor Function Declaration
public function addCKEditor($label, $name, $value="", $additionalParams="") {}
*/
$form->addCKEditor("My TinyMCE Web Editor", "TinyMCE");
$form->addCKEditor("My Prefilled TinyMCE Editor", "TinyMCE", "This is my default value.");
$form->addCKEditor("My Basic TinyMCE Editor", "TinyMCE", "", array("basic" => 1));
?>
This function has four available parameters: label, name, value, and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Controls the content rendered inside <label> tags before the textarea. |
| name | Corresponds to the name attribute of the <textarea> tag. |
| value | Optional - Corresponds to the content between the opening and closing <textarea> tags. This can be used to set the textarea's default value. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the textarea. See the additionalParams section for all available settings that can be passed in this array. |
This project leverages reCAPTCHA's anti-bot services to help prevent non-human activity by requiring the end-user to interpret and solve a challenge phrase. See http://www.google.com/recaptcha for more information about reCAPTCHA. The captcha form element is different in several ways from the other elements included in this project.
<?php
/* addCaptcha Function Declaration
public function addCaptcha($label="", $additionalParams="") {}
*/
$form->addCaptcha();
$form->addCaptcha("My Captcha");
$form->addCKEditor("My Required Captcha", array("required" => 1));
?>
This function has two available parameters: label and additionalParams. The table provided below describes each of these parameters.
| Parameter | Description |
| label | Optional - Controls the content rendered inside <label> tags before the captcha. |
| additionalParams | Optional - Associative array of key/value pairs allowing a variety of settings to be applied to the captcha. See the additionalParams section for all available settings that can be passed in this array. |
Nearly all the functions for adding form elements have an optional, last parameter called additionalParams that can be used to apply various settings to form elements through an associative array of key/value pairs. An example is provided below to demonstrate how this can be done.
<?php
$form->addTextbox("My Textbox w/additionalParams", "MyTextbox", "", array(
"required" => 1,
"class" => "myclass",
"onkeyup" => "filterTextbox(this.value);"
));
?>
Many of the available settings that can be passed to the additionalParams parameter directly correspond with html attributes, like "class" and "onkeyup" as seen in the code snippet above. If you're unfamiliar with these supported html attributes, use this page from w3schools.com as a reference. Others available settings are custom functionality built into this project, like "required" - which triggers javascript validation. All of these custom settings that can be passed to the additionalParams paramter are provided below for your reference.
| Parameter | Applicable Element Functions | Description |
| alphanumeric | addTextbox | Limits the characters that can be typed into textboxes to letters and/or numbers.
One important thing to note is that copy-and-paste is allowed, which provides the opportunity
for invalid characters to make their way into the textbox's value. Because of this, textboxes
with the alphanumeric attribute will be validated by an onsubmit javascript function. PHP validation
can also be applied by invoking the validate function after the form's data has been submitted.
|
| basic | addCKEditor, addWebEditor | Triggers web editor's simplified control panel. Both of the web editors integrated into this project - TinyMCE and CKEditor - have two
control panels that can be used. By default, the web editor will be displayed with a fully-featured set of controls; however, you can use the basic option
to display a reduced set of controls including only bold, italics, ordered/unordered lists, and a few others. Both control panels can be seen in the Web Editors example.
|
| height | addLatLng, addSlider | Controls the height of the Google Map and jQuery slider (when orientation has been set to vertical). When using the addLatLng function, the height of the container housing the
Google Map will be set to 200px by default; however, you can override this setting by making use of the height setting. When using the addSlider function, the height setting
can be used in combination with the orientation jqueryOption to control the slider's height. In both functions, numbers passed with no suffix - "px", "%", etc - will be
interpreted in pixels.
|
| hint | addTextbox, addTextarea, addDate, addDateRange, addColorPicker, addLatLng, addEmail | Prefills elements with a temporary value that is cleared with an onclick javascript function when engaged. Several functions including addDate, addDateRange, addColorPicker, and addLatLng
have this option set by default. For instance, the addDate function has a hint set to "Click to Select Date...". Hints are ignored for required fields during javascript validation. Also, the form's
built in onsubmit javascript function will remove hints before the data is submitted.
|
| hideDisplay | addSlider | Prevents the selected value from being displayed below the slider element.
|
| hideJump | addLatLng | Prevents the location jump textbox from being rendered below the Google Map.
|
| integer | addTextbox | Limits the characters that can be typed into textboxes to numbers.
One important thing to note is that copy-and-paste is allowed, which provides the opportunity
for invalid characters to make their way into the textbox's value. Because of this, textboxes
with the integer attribute will be validated by an onsubmit javascript function. PHP validation
can also be applied by invoking the validate function after the form's data has been submitted.
|
| jqueryOptions | addDate, addDateRange, addSlider | Allows jQuery options to be applied to various form elements that leverage jQuery plugins/UI. This option needs to be passed as an associative array of key/value pairs where the key corresponds to the jQuery option's
name. If the jQuery option's value is javascript code, "js:" will need to prepended in order to distinguish itself from a string. Use the example below for reference.
|
| labelPaddingRight | All execpt addButton and addHTMLExternal | Controls the amount of padding applied to the right side of the label when both the labelWidth and labelRightAlign form/element attributes are being used to render the label and the form element side-by-side.
This setting, as well as the labelWidth and labelRightAlign attributes, can be applied either in the form's setAttributes function or in an individual add element function. If these settings are applied in the
form's setAttributes function, they will affect each element in the form. The labelPaddingRight attribute is set to "4px" by default. Numbers passed with no suffix - "px", "%", etc - will be interpreted in pixels.
See the 4th form in the Layout example file for reference.
|
| labelRightAlign | All execpt addButton and addHTMLExternal | Forces the element's label to be right aligned when both the labelWidth form/element attribute is being used to render the label and the form element side-by-side.
This setting, as well as the labelWidth attribute, can be applied either in the form's setAttributes function or in an individual add element function. If these settings are applied in the
form's setAttributes function, they will affect each element in the form. See the 4th form in the Layout example file for reference.
|
| labelWidth | All execpt addButton and addHTMLExternal | Forces the label to be displayed side-by-side with the form element. This feature overrides the default behavior that displays labels above form elements.
This setting can be applied either in the form's setAttributes function or in an individual add element function. If this setting is applied in the
form's setAttributes function, it will affect each element in the form. See the 2nd, 3rd, and 4th form in the Layout example file for reference.
|
| noBreak | addCheckbox, addRadio, addYesNo, addTrueFalse, addCheckSort | Displays the radio buttons or checkboxes in a horizontal list. This setting will be automatically set for the yesno and truefalse form elements. The other elements - checkbox, radio, and checksort -
will be listed vertically by default.
|
| prefix | addSlider | Prepends the slider's selected value with a specified prefix. See the 3rd slider in the jQuery example file for reference.
|
| preHTML | All execpt addButton and addHTMLExternal | Used to display text or html content before an element's label. The addHTMLExternal function can also be used to insert text/html between form elements.
|
| postHTML | All execpt addButton and addHTMLExternal | Used to display text or html content after an element. See the Conditional Scenarios example file for reference. The addHTMLExternal function can also be used to insert text/html between form elements.
|
| required | All execpt addButton, addHTMLExternal, addHTML, and addSort | Activates javascript validation to ensure the element has been filled out. This attribute will also trigger php validation when the validate function is invoked after the form's data has been submitted.
See the Javascript Validation and PHP Validation example files for reference.
|
| suffix | addSlider | Appends the slider's selected value with a specified suffix. See the 2nd slider in the jQuery example file for reference.
|
| tooltip | All execpt addButton, addHTML, and addHTMLExternal | Actives tooltip icon beside the element's label, which displays text/html when hovered over. Tooltips within this project leverage a jQuery plugin called Poshy Tip. See the Tooltip example file for reference.
|
| zoom | addLatLng | Controls the zoom level of the Google Map. This setting can range from 0 to 21, with 0 representing the farthest zoom level where the entire world can be seen on one map, and 21 being the closest zoom level where individual buildings can be seen.
This attribute will be set to 9 by default. See the Google Maps file for reference.
|