Main functions
General
construct
$form = new Form($form_ID, $layout = 'horizontal', $attr = '', $framework = 'bs4');
/**
* Defines the layout (horizontal | vertical | inline).
* Default is 'horizontal'
* Clears values from session if self::clear has been called before
* Catches posted errors
* Adds hidden field with form ID
* Sets elements wrappers
*
* @param string $form_ID The ID of the form
* @param string $layout (Optional) Can be 'horizontal', 'vertical' or 'inline'
* @param string $attr (Optional) Can be any HTML input attribute or js event EXCEPT class
* (class is defined in layout param).
* attributes must be listed separated with commas.
* Example : novalidate,onclick=alert(\'clicked\');
* @param string $framework (Optional) bs3 | bs4 | material | foundation
* (Bootstrap 3, Bootstrap 4, Material design, Foundation >= 6.4)
* @return $this
*/
options
Call setOptions() only if you change defaults options
Go to Options for more details
$form->setOptions($options);
/**
* Sets form layout options to match your framework
* @param array $user_options (Optional) An associative array containing the
* options names as keys and values as data.
*/
Mode (production vs. development)
Default mode is production.
$form->setMode($mode);
/**
* set the form mode to 'development' or 'production'
* in production mode, all the plugins dependencies are combined and compressed in a single css or js file.
* the css | js files are saved in plugins/min/css and plugins/min/js folders.
* these 2 folders have to be wrirable (chmod 0755+)
* @param string $mode 'development' | 'production'
* @return $this
*/
Detailed explanations available here: Optimization (CSS & JS dependencies)
Method
Default method is POST.
Call setMethod() only if you change default method
$form->setMethod($method);
/**
* set sending method
* @param string $method POST|GET
*/
Action
Default action is htmlspecialchars($_SERVER["PHP_SELF"]).
htmlspecialchars prevents attackers from exploiting the code by injecting HTML or Javascript code (Cross-site Scripting attacks) in forms (recommended on http://www.w3schools.com/php/php_form_validation.asp)
Call setAction() only if you change default action
$form->setAction($url, [$add_get_vars = true]);
/**
* Redefines form action
*
* @param boolean $add_get_vars (Optional) if $add_get_vars is set to false,
* url vars will be removed from destination page.
* Example: www.myUrl.php?var=value => www.myUrl.php
*/
Start Fieldset
Start your fieldset with optional legend.
Don't forget to call endFieldset to end your fieldset.
You can add several fieldsets on the same form.
$form->startFieldset('legend', $fieldset_attr = '', $legend_attr = '');
/**
* Starts a fieldset tag.
* @param string $legend (Optional) Legend of the fieldset.
* @param string $fieldset_attr (Optional) Fieldset attributes.
* @param string $legend_attr (Optional) Legend attributes.
*/
End Fieldset
$form->endFieldset();
/**
* Ends a fieldset tag.
*/
startDependentFields
Start a dependent fields block.
dependent fields block is hidden and will be shown if $parent_field changes to one of $show_values.
Don't forget to call endDependentFields to end your Dependent Fields block.
if $inverse is true, dependent fields will be shown if any other value than $show_values is selected
Each Dependent fields block can include one or several dependent fields blocks.
Dependent fields MUST NOT START with the same fieldname as their parent field.
$form->startDependentFields($parent_field, $show_values[, $inverse = false]);
/**
* Start a hidden block
* which can contain any element and html
* Hiden block will be shown on $parent_field change
* if $parent_field value matches one of $show_values
* @param string $parent_field name of the field which will trigger show/hide
* @param string $show_values single value or comma separated values which will trigger show.
* @param boolean $inverse if true, dependent fields will be shown if any other value than $show_values is selected.
* @return void
*/
Live examples with code are available here: jquery-plugins.php#dependent-fields-example
endDependentFields
$form->endDependentFields();
/**
* Ends Dependent Fields block.
*/
$attr argument
Several element functions use a $attr argument.
The $attr argument accepts any html attribute or javascript event.
Use comma separated values (see examples below).
Examples
$form->addInput('text', 'name', '', 'Your name: ', 'id=my-id, placeholder=My Text, required=required');
$form->addInput('password', 'pass', '', 'Your password: ', 'required=required, pattern=(.){7\,15}');
$form->addTextarea('my-textarea', '', 'Your message: ', 'cols=30, rows=4');
$form->addBtn('button', 'myBtnName', 1, 'Cancel', 'class=btn btn-danger, onclick=alert(\'cancelled\');');
Elements
$form->addInput($type, $name [, $value = '', $label = '', $attr = '']);
/**
* Adds input to the form
*
* @param string $type Accepts all input html5 types except checkbox and radio:
* button, color, date, datetime, datetime-local,
* email, file, hidden, image, month, number, password,
* range, reset, search, submit, tel, text, time, url, week
* @param string $name The input name
* @param string $value (Optional) The input default value
* @param string $label (Optional) The input label
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the input.
* Example: class=my-class,placeholder=My Text,onclick=alert(\'clicked\');
*/
Input Groups allow to have several inputs / selects on the same line in horizontal forms.
Up to 12 elements can be grouped.
2 ways to set arguments:
// 1st way: each fieldname as argument
$form->groupInputs('street', 'zip', 'countries');
// 2nd way: a single array including all fieldnames as argument
$fields = array('street', 'zip', 'countries');
$form->groupInputs($fields);
Always create your input group BEFORE creating the input elements.
$form->groupInputs($input1, $input2 [, $input3 = '', $input4 = '', $input5 = '', $input6 = '', $input7 = '', $input8 = '', $input9 = '', $input10 = '', $input11 = '', $input12 = '']);
/**
* Allows to group inputs in the same wrapper
*
* Arguments can be:
* - a single array with fieldnames to group
* OR
* - fieldnames given as string
*
* @param string|array $input1 The name of the first input of the group
* OR
* array including all fieldnames
*
* @param string $input2 The name of the second input of the group
* @param string $input3 [optional] The name of the third input of the group
* @param string $input4 [optional] The name of the fourth input of the group
* @param string ...etc.
*/
Input Groups Example
$form->startFieldset('Personal informations');
$form->groupInputs('street', 'zip', 'countries');
$form->setCols(3, 4);
$form->addInput('text', 'street', '', 'Your address: ', 'placeholder=street,required=required');
$form->setCols(0, 2);
$form->addInput('text', 'zip', '', '', 'placeholder=zip code,required=required');
$form->setCols(0, 3);
$form->addOption('countries', '', 'Countries');
$form->addOption('countries', 'United States', 'United States');
$form->addOption('countries', 'Canada', 'Canada');
$form->addOption('countries', 'France', 'France');
$form->addSelect('countries', '', '');
$form->endFieldset();
Textarea
$form->addTextarea($name, $value [, $label, $attr]);
/**
* Adds textarea to the form
* @param string $name The textarea name
* @param string $value (Optional) The textarea default value
* @param string $label (Optional) The textarea label
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the textarea.
* Example: cols=30, rows=4;.
*/
Options for Select list
Always add your options BEFORE creating the select element
-
1
Add your options
-
2
Create your select
$form->addOption($selectName, $value, $txt [, $group_name, $attr]);
/**
* Adds option to the $select_name element
*
* @param string $select_name The name of the select element
* @param string $value The option value
* @param string $txt The text that will be displayed
* @param string $group_name (Optional) the optgroup name
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the option.
* Example: class=my-class
*/
Select list
$form->addSelect($selectName, $label [, $attr = '', $displayGroupLabels = true]);
addSelect() function plays nice with bootstrap-select plugin and select2 plugin.
Just add selectpicker class for Bootstrap select or select2 class for Select2 plugin, data-attributes and phpformbuilder will do the job..
Don't forget to activate your plugins to add the required css/js files to your page.
/**
* Adds a select element
*
* IMPORTANT: Always add your options BEFORE creating the select element
*
* @param string $select_name The name of the select element
* @param string $label (Optional) The select label
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the input.
* Example: class=my-class
* @param string $displayGroupLabels (Optional) True or false.
* Default is true.
*/
Example with optgroup
$form->addOption('select-with-groupnames', 'option-1', 'option 1', 'group 1');
$form->addOption('select-with-groupnames', 'option-2', 'option 2', 'group 1', 'selected=selected');
$form->addOption('select-with-groupnames', 'option-3', 'option 3', 'group 1');
$form->addOption('select-with-groupnames', 'option-4', 'option 4', 'group 2');
$form->addOption('select-with-groupnames', 'option-5', 'option 5', 'group 2');
$form->addSelect('select-with-groupnames', 'Select please: ', '');
Example with multiple selections
for ($i=1; $i < 11; $i++) {
$form->addOption('myMultipleSelectName[]', $i, 'option ' . $i);
}
$form->addSelect('myMultipleSelectName[]', 'Select please:
(multiple selections)', 'multiple=multiple');
Country Select list
Always add your options BEFORE creating the select element
Country Select uses the bootstrap-select plugin, which requires Bootstrap's dropdown in your bootstrap.min.js
$form->addCountrySelect($select_name [, $label = '', $attr = '', $user_options = array()]);
/**
* adds a country select list with flags
* @param array $select_name
* @param string $label (Optional) The select label
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the input.
* Example: class=my-class
* @param array $user_options (Optional):
* lang : MUST correspond to one subfolder of [PLUGINS_DIR]countries/country-list/country/cldr/
* *** for example 'en', or 'fr_FR' Default: 'en'
* flags : true or false. Default: true
* *** displays flags into option list
* flag_size : 16 or 32 Default: 32
* return_value : 'name' or 'code' Default: 'name'
* *** type of the value that will be returned
* show_tick : true or false
* *** shows a checkmark beside selected options Default: true
* live_search : true or false Default: true
*/
Live examples with code are available here:
jquery-plugins.php#bootstrap-select-example
jquery-plugins.php#select2-example
Radio Btns
- Add your radio buttons
- Call printRadioGroup
$form->addRadio($group_name, $label, $value [, $attr = '']);
/**
* Adds radio button to $group_name element
*
* @param string $group_name The radio button groupname
* @param string $label The radio button label
* @param string $value The radio button value
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* Example: checked=checked
*/
Print Radio Group
$form->printRadioGroup($group_name, $label [, $inline = true, $attr = '']);
/**
* Prints radio buttons group.
*
* @param string $group_name The radio button group name
* @param string $label (Optional) The radio buttons group label
* @param string $inline (Optional) True or false.
* Default is true.
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the input.
* Example: class=my-class
*/
Example
$form->addRadio('myRadioBtnGroup', 'choice one', 'value 1');
$form->addRadio('myRadioBtnGroup', 'choice two', 'value 2', 'checked=checked');
$form->addRadio('myRadioBtnGroup', 'choice three', 'value 3');
$form->printRadioGroup('myRadioBtnGroup', 'Choose one please', true, 'required=required');
Several plugins are available to replace the ugly browser default radio buttons with nice ones:
Checkboxes
- Add your checkboxes
- Call printCheckboxGroup
$form->addCheckbox($group_name, $label, $value [, $attr = '']);
/**
* Adds checkbox to $group_name
*
* @param string $group_name The checkbox groupname (will be converted to an array of indexed value)
* @param string $label The checkbox label
* @param string $value The checkbox value
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* Example: checked=checked
*/
Print Checkbox Group
$form->printCheckboxGroup($group_name, $label [, $inline = true, $attr = '']);
/**
* Prints checkbox group.
*
* @param string $var (Optional) description
*
* @param string $group_name The checkbox button group name
* @param string $label (Optional) The checkbox group label
* @param string $inline (Optional) True or false.
* Default is true.
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the input.
* Example: class=my-class
*/
Example
$form->addCheckbox('myCheckboxGroup', 'choice one', 'value 1');
$form->addCheckbox('myCheckboxGroup', 'choice two', 'value 2', 'checked=checked');
$form->addCheckbox('myCheckboxGroup', 'choice three', 'value 3', 'checked=checked');
$form->printCheckboxGroup('myCheckboxGroup', 'Check please: ', true, 'required=required');
Several plugins are available to replace the ugly browser default checkboxes with nice ones:
Buttons
For a single button, just call addBtn() and let $btnGroupName empty.
For button group, call addBtn() for each button, give a name to $btnGroupName, then call printBtnGroup()
$form->addBtn($type, $name, $value, $text [, $attr = '', $btnGroupName = '']);
/**
* Adds button to the form
*
* If $btnGroupName is empty, the button will be automaticaly displayed.
* Otherwise, you'll have to call printBtnGroup to display your btnGroup.
*
* @param string $type The html button type
* @param string $name The button name
* @param string $value The button value
* @param string $text The button text
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the input.
* Example: class=my-class,onclick=alert(\'clicked\');
* @param string $btnGroupName (Optional) If you want to group several buttons, group them then call printBtnGroup.
*
*/
Print Btn Group
$form->printBtnGroup($btnGroupName);
/**
* Prints buttons group.
*
* @param string $btnGroupName The buttons group name
* @param string $label (Optional) The buttons group label
*
*/
Single button example
$form->addBtn('submit', 'myBtnName', 1, 'Submit form', 'class=btn btn-primary');
Button group example
$form->addBtn('submit', 'mySubmitBtnName', 1, 'Submit form', 'class=btn btn-primary', 'myBtnGroup');
$form->addBtn('button', 'myCancelBtnName', 0, 'Cancel', 'class=btn btn-danger, onclick=alert(\'cancelled\');', 'myBtnGroup');
$form->printBtnGroup('myBtnGroup');
Custom HTML
You can add some html code at any place you want when creating your form.
This way, you can:
$form->addHtml($html [, $element_name = '', $pos = 'after']);
/**
* Adds HTML code at any place of the form
*
* @param string $html The html code to add.
* @param string $element_name (Optional) If not empty, the html code will be inserted.
* just before or after the element.
* @param string $pos (Optional) If $element_name is not empty, defines the position
* of the inserted html code.
* Values can be 'before' or 'after'.
*/
When your HTML is linked to an element, always call addHtml() BEFORE creating the element
To add helper texts icons buttons or any input group addon it'll be even better to use the shortcut functions:
Add HTML between elements
$form->addInput('text', 'input-name', '', 'Your name: ');
$form->addHtml('<p class="alert alert-danger">Your e-mail address is required</p>');
$form->addInput('text', 'email', '', 'Your e-mail', 'required');
Prepend or append HTML to elements
$form->addInput('text', 'input-name-2', '', 'Your name: ');
$form->addHtml('<p class="form-text alert alert-danger">Your e-mail address is required</p>', 'email-2', 'after');
$form->addInput('text', 'email-2', '', 'Your e-mail', 'required');
wrapper can be one or two html elements
$form->addInputWrapper($html, $element_name);
/**
* Wraps the element with html code.
*
* @param string $html The html code to wrap the element with.
* The html tag must be opened and closed.
* Example: <div class="my-class"></div>
* @param string $element_name The form element to wrap.
*/
Example
$form->addInputWrapper('<div class="bg-dark rounded p-2"><div class="bg-white rounded p-2"></div></div>', 'imput-wrapped');
$form->addInput('text', 'imput-wrapped', '', 'Input wrapped with custom divs');
Render
Renders the form.
Set $debug to true if you wants to display HTML code
Set $display to false if you wants to return HTML code but not display on page
$form->render([$debug = false, $display = true]);
/**
* Renders the html code of the form.
*
* @param boolean $debug (Optional) True or false.
* If true, the html code will be displayed
* @param boolean $display (Optional) True or false.
* If false, the html code will be returned but not displayed.
*
*/
Ajax loading
PHP Form Builder allows you to load your forms with Ajax.
Loading in Ajax allows to:
- integrate your forms in any html page
- load the forms asynchronously, which is good for your page loading speed
To load your form with Ajax:
-
1
Create your form using the built-in PHP functions and save it in a php file somewhere on your server.
Set the ajax option to true to enable Ajax loading.
Here's a sample code:
<?php
use phpformbuilder\Form;
use phpformbuilder\Validator\Validator;
/* =============================================
start session and include form class
============================================= */
$form_id = 'my-form';
session_start();
include_once rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . '/phpformbuilder/Form.php';
/* =============================================
validation if posted
============================================= */
if ($_SERVER["REQUEST_METHOD"] == "POST" && Form::testToken($form_id) === true) {
// do stuff
}
/* ==================================================
The Form
================================================== */
$form = new Form($form_id, 'horizontal', 'data-fv-no-icon=true, novalidate');
// $form->setMode('development');
// enable Ajax loading
$form->setOptions(['ajax' => true]);
// add your fields & plugins here
// render the form
$form->render();
-
2
In your main file (html):
Create a div with a specific id, for instance: <div id="ajax-form"></div>
-
3
In your main file (html):
Add the Javascript code to load your form:
<script>
var $head= document.getElementsByTagName('head')[0],
target = '#ajax-form'; // replace with the id of your div
var loadData = function(data, index) {
if (index <= $(data).length) {
var that = $(data).get(index);
if ($(that).is('script')) {
// output script
var script = document.createElement('script');
script.type = 'text/javascript';
if (that.src != '') {
script.src = that.src;
script.onload = function() {
loadData(data, index + 1);
};
$head.append(script);
} else {
script.text = that.text;
$('body').append(script);
loadData(data, index + 1);
}
} else {
// output form html
$(target).append($(that));
loadData(data, index + 1);
}
} else {
$.holdReady(false);
}
};
$(document).ready(function() {
$.ajax({
url: 'ajax-forms/contact-form-1.php', // replace with the url of your php form
type: 'GET'
}).done(function(data) {
$.holdReady(true);
loadData(data, 0);
}).fail(function(data, statut, error) {
console.log(error);
});
});
</script>
You'll find an example here: https://www.phpformbuilder.pro/templates/bootstrap-4-forms/ajax-loaded-contact-form-1.html
useLoadJs
Use the great LoadJs library to load CSS & Javascript plugins dependencies.
This feature is great for optimization ; it requires to include the LoadJs Javascript library in your page
Details & sample codes here: jquery-plugins.php#optimization-with-loadjs
$form->useLoadJs($bundle = '');
/**
* load scripts with loadJS
* https://github.com/muicss/loadjs
* @param string $bundle optional loadjs bundle name to wait for
* @return void
*/
Print plugins includes
The printIncludes() function is used to insert the CSS & Javascript files required by each plugin used in your form.
Call printIncludes() at the right places (generally css inside your <head></head> section, and js just before </body>.
If your form contains no plugin, no need to call this function.
printIncludes($type, $debug = false, $display = true, $combine_and_compress = true);
/**
* Prints html code to include css or js dependancies required by plugins.
* i.e.:
* <link rel="stylesheet" ... />
* <script src="..."></script>
*
* @param string $type value : 'css' or 'js'
* @param boolean $debug (Optional) True or false.
* If true, the html code will be displayed
* @param boolean $display (Optional) True or false.
* If false, the html code will be returned but not displayed.
* @param boolean $combine_and_compress (Optional) True or false.
* If true, dependancies are combined and compressed into plugins/min/ folder.
* @return $this
*/
About optimization
PHP Form Builder is conceived for maximum optimization and extremely fast loading time.
Detailed explanations available here: Optimization (CSS & JS dependencies)
Example with colorpicker plugin
$form->addInput('text', 'my-colorpicker', '', 'ColorPicker: ');
$form->addPlugin('colorpicker', '#my-colorpicker');
// call this just before </head>
$form->printIncludes('css');
<link href="../../phpformbuilder/plugins/colpick/css/colpick.css" rel="stylesheet" media="screen">
$form->addInput('text', 'my-colorpicker', '', 'ColorPicker: ');
$form->addPlugin('colorpicker', '#my-colorpicker');
// call this just before </body>
$form->printIncludes('js');
<script src="../../phpformbuilder/plugins/colpick/js/colpick.js"></script>
Print plugins JS code
Prints the JS code generated by the plugin.
If your form contains no plugin, no need to call this function.
$form->printJsCode($debug = false);
/**
* Prints js code generated by plugins.
* @param boolean $debug (Optional) True or false.
* If true, the html code will be displayed
* @param boolean $display (Optional) True or false.
* If false, the html code will be returned but not displayed.
*/
Example with colorpicker plugin
$form->addInput('text', 'my-colorpicker', '', 'ColorPicker: ');
$form->addPlugin('colorpicker', '#my-colorpicker');
$form->printJsCode();
<script type="text/javascript">
$(document).ready(function() {
$("#my-colorpicker").colpick({
onSubmit:function(hsb,hex,rgb,el) {
$(el).val('#'+hex);
$(el).colpickHide();
}
});
});
</script>
Set Cols
The setCols() function wraps label and fields with columns.
The columns can only be set in horizontal forms.
$form->setCols($labelsCols, $fieldsCols [, $breakpoint = 'sm']);
Bootstrap 4 auto column
Bootstrap 4 allows automatic-width columns.
To build automatic-width columns, set $fieldsCols to -1
/**
* Shortcut for
* $options = array(
* 'horizontalLabelCol' => 'col-' . $breakpoint . '-' . $labelsCols,
* 'horizontalOffsetCol' => 'col-' . $breakpoint . '-offset-' . $labelsCols,
* 'horizontalElementCol' => 'col-' . $breakpoint . '-' . $fieldsCols,
* );
* $form->setOptions($options);
*
* @param number $labelsCols number of columns for label
* @param number $fieldsCols number of columns for fields
* @param string $breakpoint Bootstrap's breakpoints: xs | sm | md |lg
*
*/
Example
$form->setCols(3, 9);
$form->addInput('text', 'username', '', 'Name');
Will generate the following markup:
<div class="form-group row justify-content-end">
<label for="username" class="col-sm-3 col-form-label">
Name
</label>
<div class="col-sm-9">
<input id="username" name="username" type="text" value="" class="form-control">
</div>
</div>
Equivalent to:
$options = array(
'horizontalLabelCol' => 'col-sm-3',
'horizontalElementCol' => 'col-sm-9'
);
$form->setOptions($options);
$form->addInput('text', 'username', '', 'Name');
Bootstrap 4 automatic-width example
$form->setCols(-1, -1, 'sm');
$form->groupInputs('user-name', 'user-first-name');
$form->addInput('text', 'user-name', '', 'Name', 'required, placeholder=Name');
$form->addInput('text', 'user-first-name', '', 'First name', 'required, placeholder=First Name');
$form->setCols(-1, -1); // without breakpoint
$form->addIcon('user-email', '<i class="fa fa-envelope" aria-hidden="true"></i>', 'before');
$form->addInput('email', 'user-email', '', '', 'required, placeholder=Email');
Will generate the following markup:
<div class="form-group row justify-content-end">
<label for="user-name" class="col-sm col-form-label">
Name <sup class="text-danger">* </sup>
</label>
<div class="col-sm">
<input id="user-name" name="user-name" type="text" value="" required placeholder="Name" class="form-control fv-group">
</div>
<label for="user-first-name" class="col-sm col-form-label">
First name <sup class="text-danger">* </sup>
</label>
<div class="col-sm">
<input id="user-first-name" name="user-first-name" type="text" value="" required placeholder="First Name" class="form-control fv-group">
</div>
</div>
<div class="form-group row justify-content-end">
<div class=" col-sm">
<div class="input-group">
<div class="input-group-prepend">
<span class="input-group-text"><i class="fa fa-envelope" aria-hidden="true"></i></span>
</div>
<input id="user-email" name="user-email" type="email" value="" required placeholder="Email" class="form-control">
</div>
Add Helper
Adds helper text after the chosen field
$form->addHelper($helper_text, $element_name);
addHelper() MUST always be called BEFORE creating the element
/**
* Shortcut to add element helper text
*
* @param string $helper_text The helper text or html to add.
* @param string $element_name the helper text will be inserted just after the element.
*/
Example
$form->addHelper('Enter your last name', 'last-name');
$form->addInput('text', 'last-name', '', 'Last name', 'required');
Add Addon
Adds button or text addon before or after the chosen field
$form->addAddon($input_name, $addon_html, $pos);
/**
* shortcut to prepend or append button or text addon to an input
* @param string $input_name the name of target input
* @param string $addon_html button or text addon html code
* @param string $pos before | after
*/
Example
$addon = '<button class="btn btn-secondary" type="button" onclick="$(\'#input-with-button-after\').val(\'\');">cancel</button>';
$form->addAddon('input-with-button-after', $addon, 'after');
$form->addInput('text', 'input-with-button-after', '', 'Your name');
Add Icon
Adds an icon before or after the chosen field
$form->addIcon($input_name, $icon_html, $pos);
/**
* shortcut to prepend or append icon to an input
* @param string $input_name the name of target input
* @param string $icon_html icon html code
* @param string $pos before | after
*/
Example
$form->addIcon('username', '<i class="fa fa-user" aria-hidden="true"></i>', 'before');
$form->addInput('text', 'username', '', 'Name');
Center buttons inside their wrapper
$form->centerButtons($center);
/**
* @param boolean $center
*/
Example
$form->centerButtons(true);
$form->addBtn('submit', 'submit-btn', 1, 'Submit', 'class=btn btn-success');
E-mail Sending
sendMail() function
$sent_message = Form::send($options, $smtp_settings = array());
See details at E-mail Sending
Registering / Clearing values
Global registration process
PHP Form Builder manages the memorization of fields and posted values without you needing to take any action.
If your form is posted with errors (validation fails), the posted values are automatically displayed in the corresponding fields.
To set the default value of a field, it must be saved in the PHP session in this way:
$_SESSION['form-id']['field-name'] = 'my-value';
If the form is posted, the field will have the posted value. Otherwise it will have the default value registered in the PHP session.
Here's the global workflow:
- You create your form and add fields.
PHP Form Builder registers each field name in PHP session: $_SESSION['form-id']['fields'][] = 'field-name';
- You post the form
- You validate the posted values:
$validator = Form::validate('form-id');
- If the validation fails:
The error messages are stored in PHP session: $_SESSION['errors'][$form_ID] as $field => $message
- You instanciate your form again:
PHP Form Builder registers the posted values in PHP session: $_SESSION['form-id']['field-name'] = $_POST['my-value'];
PHP Form Builder gets and displays the session value and the possible error for each field.
registerValues (static function)
When you instantiate a form, it automatically stores corresponding posted values in session unless you called clear function before creating your form.
Values are registered this way: $_SESSION['form-id']['field-name']
You can call Form::registerValues('form-id') manually at any time.
Form::registerValues('form-id');
/**
* register all posted values in session
* @param string $form_ID
*
* ex: $_SESSION['form-id']['field-name'] = $_POST['field-name'];
*/
mergeValues (static function)
mergeValues is used to merge previously registered values in a single array.
Usefull for step forms to send all steps values by email or store into database for example.
Form::mergeValues(array('step-form-1', 'step-form-2', 'step-form-3'));
/**
* merge previously registered session vars => values of each registered form
* @param array $forms_array array of forms IDs to merge
* @return array pairs of names => values
* ex: $values[$field_name] = $value
*/
clear (static function)
Clears the corresponding previously registered values from session.
Form::clear('form-id');
