JavaScript plugins

Overview

The addPlugin() Function

$form->addPlugin(string $plugin_name, string $selector, string $js_config = 'default', array $plugin_settings = [])
Argument Type Value Description
$plugin_name * String - The plugin name. Must be the name of the XML file in /plugins-config without extension.
$selector * String - The CSS selector (e.g., '#fieldname' or '.fieldname') of the field on which the plugin will be enabled.
$config String 'default' The XML node where the plugin JavaScript code is in plugins-config/[plugin-name.xml]
$options Array [] Associative array containing the key/value pairs of plugin-specific options.

How to enable plugins

Enabling plugins with PHP Form Builder is deadly fast and straightforward:

  1. 1 Create your field. e.g., $form->addInput('text', 'my-date', '', 'Pickup a date');
  2. 2 Add the plugin. e.g., $form->addPlugin('pickadate', '#my-date');
  3. 3 Call $form->printIncludes('css'); in your <head> section
  4. 4 Call $form->printIncludes('js'); then $form->printJsCode(); just before </body>

It will add the pickadate plugin to the input named my-date.
The plugin will use its default configuration stored in phpformbuilder/plugins-config/pickadate.xml

printIncludes('css'), printIncludes('js') and printJsCode() must be called only once,
even if your form uses several plugins.

Special notes:

Some plugins can be enabled by simply adding an attribute (data-attr) or a CSS class to the target field without calling the addPlugin() function.

You'll see this by referring to the documentation for each plugin.

To go further:

Plugin files & configuration

Plugins

The plugin source files (CSS & JS files) are located in the /plugins folder.

Plugins configuration (XML configuration files)

Each plugin has its own XML configuration file in the /plugins-config directory.

Each XML configuration file contains the necessary information for PHP to generate the code required to initialize it:

  • Addition of the plugin's CSS and JavaScript dependencies
  • JavaScript initialization code

The XML structure is always the same: 

<root>
    <default>
        <includes>
            <css>
                <file>../../phpformbuilder/plugins/[plugin dir]/[plugin].css</file>
            </css>
            <js>
                <file>../../phpformbuilder/plugins/[plugin dir]/[plugin].js</file>
            </js>
        </includes>
        <js_code>
            <![CDATA[
                // JavaScript init code here
            ]]>
        </js_code>
    </default>
</root>

You can create, save and reuse as many configurations as you like for each plugin.
Create a new node in the plugin's XML file and insert your JavaScript code inside. See Customizing plugins

CSS & JS dependencies

Each plugin has its own CSS & JS dependencies in its folder inside phpformbuilder/plugins/

PHP Form Builder generates a single compiled and minified CSS file for each form, including all the plugins css used by the form.

The plugins' JS dependencies are compiled the same way.

These compiled files are located in phpformbuilder/plugins/min/css and phpformbuilder/plugins/min/js folders.

Optimization (CSS & JS dependencies)
In 'production' mode, PHP Form Builder minifies and compiles all the plugins' JavaScript and CSS dependencies into a single CSS/JavaScript file for ultra-fast loading.

$form->setMode(string $mode);
Argument Type Value Description
$mode * String 'production' 'development' or 'production'
The default mode is 'production' until you change it with the setMode($mode) function.

The production mode

When your form is in production mode:

When you call $form->printIncludes('css'); or $form->printIncludes('js');, all plugins assets (plugin's CSS and JavaScript dependencies) are compressed and minified for fast loading in a single js|css file in phpformbuilder/plugins/min/[css|js]/[framework-][form-name].min.[css|js].

Your form will load a single CSS file and a single JavaScript file instead of a file for each plugin, which dramatically improves performance.

Your phpformbuilder/plugins/min/[css|js]/ dir has to be writable (chmod 0755+)

The development mode

When your form is in 'development' mode:

  • $form->printIncludes('css'); will add each plugin CSS dependencies to your page
  • $form->printIncludes('js'); will add each plugin JavaScript dependencies to your page

The 'development' mode is helpful to inspect or debug your code. Still, you'll have many CSS & JavaScript files to load, depending on your form's number of plugins.

Async loading with LoadJs library

LoadJs is a tiny async loader/dependency manager for modern browsers (789 bytes)

Used with PHP Form Builder it allows to load the plugins CSS & JS dependencies asynchronously without blocking your page rendering.

$form->useLoadJs(string $bundle = '');
Argument Type Value Description
$bundle String '' Optional bundle name to wait for before triggering the domReady events

Wen you enable LoadJs, $form->printJsCode(); will load all the CSS & JS dependencies.

  • Don't call $form->printIncludes('css');: the CSS files will be loaded with LoadJs
  • Don't call $form->printIncludes('js'); the JS files will be loaded with LoadJs

Example 1

<?php
$form = new Form('my-form', 'horizontal');

$form->useLoadJs();

$form->addInput('text', 'my-color', '', 'Pick a color:');
$form->addPlugin('colorpicker', '#my-color');
$form->addBtn('submit', 'submit-btn', 1, 'Submit', 'class=btn btn-success ladda-button, data-style=zoom-in');
$form->render();
?>
<script src="https://cdnjs.cloudflare.com/ajax/libs/loadjs/3.5.5/loadjs.min.js"></script>

<!-- The following line will load the plugins CSS & JS dependencies -->
<?php $form->printJsCode(); ?>

Example 2: wait for your bundle before triggering the domReady events

<?php
$form = new Form('my-form', 'horizontal');

$form->useLoadJs('core');

$form->addInput('text', 'my-color', '', 'Pick a color:');
$form->addPlugin('colorpicker', '#my-color');
$form->addBtn('submit', 'submit-btn', 1, 'Submit', 'class=btn btn-success ladda-button, data-style=zoom-in');
$form->render();
?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/loadjs/3.5.5/loadjs.min.js"></script>

<script>
// loading jQuery with loadJs (core bundle)
loadjs(['assets/javascripts/jquery-3.3.1.min.js'], 'core');

// Core's loaded - do any stuff
loadjs.ready('core', function() {
   // ...
});
</script>

<!-- load the form CSS & JS dependencies
Trigger domready when the core bundle and the form JS dependencies are loaded -->
<?php $form->printJsCode(); ?>

Customizing plugins

To customize a plugin:

Duplicate the plugin's XML file from plugins-config to the plugins-config-custom folder.
It will allow you to update PHP Form Builder's package at any time without overwriting your custom config.

PHP Form Builder will always look for a custom XML file in the plugins-config-custom/ folder. If none exist, it will load the default one in plugins-config/.

You can use both default & custom config in the same form. There's no need to duplicate default XML nodes in your custom XML file.

  1. 1 Open the plugin XML file in your code editor. I.e., plugins-config/the-plugin.xml
  2. 2 Copy the <default> node structure and give it a name
    (for example, replace '<default>' with '<custom>')
  3. 3 If the <includes> node does not need to be modified, delete it from your structure.
    The program will use the default include node instead.
  4. 4 Enter your JavaScript code (the code to instanciate the plugin) in the <js_code> node
  5. 5 If you need some other replacements than %selector% in your JavaScript code, use custom markup like %my-value% in XML, then define them in $options when you call addPlugin.

Customizing plugin example

$options = array('skin' => 'red', 'my-value' => 'replacement-text');
$form->addPlugin('nice-check', 'form', 'default', $options);

Adding your own plugins

You can easily add any javascript plugin to PHP Form Builder. Here's how to do it:

  1. 1 Upload your plugin in plugin/
  2. 2 Create an XML file with the name of your plugin in plugins-config-custom/ dir,
    using the tree described in the Customizing Plugins section
  3. 3 Call your plugin with the addPlugin() function

Credits (plugins list)

PHP Form Builder includes the following JavaScript Plugins:

Thanks to all the authors for their excellent work

JavaScript Plugins - Usage & Code examples

Accordion

https://github.com/stuartjnelson/badger-accordion

The Accordion plugin allows you to create a step-by-step form, each embedded in a dropdown section in the accordion.

To create an accordion form:

PHP Form Builder will automatically load the plugin and generate the appropriate markup to run the accordion.

Loading the plugin ...

Please wait ...

Autocomplete

https://github.com/TarekRaafat/autoComplete.js

The Autocomplete plugin offers the user a dropdown list of suggestions based on the characters entered. Suggestions can be defined by an array in PHP or loaded with an Ajax call, which must return an object in JSON format.

$form->addPlugin('autocomplete', $selector, $config, $options);
Argument Type Value Description
autocomplete * String '' The plugin name, which is 'autocomplete'.
$selector * String ''

The CSS selector (e.g., '#fieldname') of the field on which the plugin will be enabled.

The autocomplete plugin must be activated individually for each target field (It doesn't accept CSS class selectors).
$config * String ''

'default' | 'ajax'

The configuration node in the plugin's XML file.
You can add your own configurations in phpformbuilder/plugins-config/autocomplete.xml
$options * Array []

Associative array with ['src' => $target]

  • If $config is 'default'
    $target must be an array of the available completions. Example: 
    $options = [
    'src' => [
        'Completion 1',
        'Completion 2',
        // ...
    ];
];
  • If $config is 'ajax'
    $target is the target url that will be called with Ajax and must return a JSON array of strings or objects. Example: 
    $options = ['src' => 'autocomplete-ajax.php'];

Autocomplete plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-start-with Boolean false If true the results items must start with the search string.
data-debounce Number 0 Sets the delay time duration in milliseconds that counts after typing is done for autoComplete.js engine to start.
data-multiple-choices Boolean false If true the user can perform several consecutive searches, and the selected results are added and separated by commas.
data-threshold Number 0 Sets the threshold value of the length of the minimum characters where the autoComplete.js engine starts.
data-max-results Number 5 Sets the maximum number of results items.

Loading the plugin ...

Please wait ...

Bootstrap Input Spinner

https://github.com/shaack/bootstrap-input-spinner

The Bootstrap Input Spinner plugin wraps a input[type="number"] field with "-" and "+" buttons to decrement/increment the field value.

$form->addInput('number', $input_name, $value, $label, 'data-input-spinner=true, min=0, max=20, data-buttons-clazz=btn-outline-light');
Argument Type Value Description
$type * String '' The input type. The Bootstrap Input Spinner plugin must be used with an input[type="number"], so the expected value is 'number'.
$input_name * String '' The name of the input field.
$value String '' The initial value of the input field.
$label String '' The label of the input field.
$attr String '' The input field attributes documentation

Special notes:

Add the data-input-spinner attribute to the input element to activate the Bootstrap Input Spinner plugin.
There is no need to call the addPlugin() function.

Bootstrap Input Spinner plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-decrement-button String '-' The "-" button text.
data-increment-button String '+' The "+" button text.
data-group-clazz String '' CSS class of the resulting input-group
data-buttons-clazz String 'btn-outline-secondary' CSS class of the resulting '+' & '-' buttons.
data-buttons-width String '2.5rem' CSS width of the resulting '+' & '-' buttons.
data-text-align String 'center' CSS alignment of the entered number.
data-auto-delay Number 500 ms threshold before auto value change.
data-auto-interval Number 50 Speed of auto value change.
data-buttons-only Boolean false Set this true to disable the possibility to enter or paste the number via keyboard.
data-suffix String '' Add a suffix to the input (see Example 2)
data-decimals Number null Number of decimals for the input value (see Example 2)

Loading the plugin ...

Please wait ...

Bootstrap Select

http://silviomoreto.github.io/bootstrap-select/

The Bootstrap Select plugin offers many features to enhance and facilitate the use of Select dropdowns.

$form->addSelect($select_name, $label, 'class=selectpicker show-tick');
Argument Type Value Description
$select_name * String '' The select field name.
$label String '' The label of the select field.
$attr String '' The select field attributes documentation

Special notes:

Add the class=selectpicker attribute to the attributes of the select element to activate the Bootstrap Select plugin.
There is no need to call the addPlugin() function.

Options:

Pass options with data attributes. Example:

$form->addSelect('select-name', 'Label', 'class=selectpicker, data-icon-base=glyphicon');

The complete data-attribute list is available at https://developer.snapappointments.com/bootstrap-select/options/#bootstrap-version.

Loading the plugin ...

Please wait ...

Colorpicker

https://github.com/Simonwep/pickr

The Colorpicker plugin allows you to select colours, set up the colour picker interface and choose the output format.

$form->addInput('text', 'my-color', '', 'Pick a color:', 'data-colorpicker=true');
Argument Type Value Description
$type * String '' The input type. The Colorpicker plugin must be used with an input[type="text"], so the expected value is 'text'.
$input_name * String '' The name of the input field.
$value String '' The initial value of the input field.
$label String '' The label of the input field.
$attr String '' The input field attributes documentation

Special notes:

Add the data-colorpicker attribute to the input element to activate the Colorpicker plugin.
There is no need to call the addPlugin() function.

Colorpicker plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-theme String 'classic' The colorpicker theme: 'classic', 'monolith' or 'nano'
data-lock-opacity Boolean false If true, the user won't be able to adjust any opacity.
Opacity will be locked at 1, and the opacity slider will be removed.
The HSVaColor object also doesn't contain an alpha, so the toString() methods print HSV, HSL, RGB, HEX, etc.
data-preview Boolean true Enable/disable the preview.
data-hue Boolean true Enable/disable the hue adjustment.
data-output-format String 'HEX' Output color format and default color representation of the colorpicker input/output textbox.
Valid options are 'HEX', 'RGBA', 'HSVA', 'HSLA' and 'CMYK'.
data-position String 'bottom-middle' Defines the position of the color-picker.
Any combinations of top, left, bottom, or right with one of these optional modifiers: start, middle, end.
Examples: 'top-start'/'right-end'
If clipping occurs, the color picker will automatically choose its position.
data-interaction-[button] Boolean No interaction button except the save button. Whether to show the interaction buttons.
e.g., data-interaction-hex=true
The available buttons are the followings: hex rgba hsla hsva cmyk input clear save

Loading the plugin ...

Please wait ...

Dependent Fields

The Dependent Fields plugin allows you to show/hide one or more fields based on the value of another.

$form->startDependentFields($parent_field, $show_values[, $inverse = false]);
// add the dependent fields here
// they'll be shown if the $parent_field value belongs to $show_values
$form->endDependentFields();
Argument Type Value Description
$parent_field * String '' The name of the field which will trigger show/hide on dependent fields
$show_values * String '' The value(s) (single value or comma separated values) that will show the dependent fields if one is selected
$inverse Boolean false if true, dependent fields will be shown if any other value than $show_values is selected.

The 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.

The Dependent fields can be nested (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.

Triggering events with Javascript

In some situations the browser may not dispatch the parent field's change event.
Eg,: if the parent field is an hidden field.

The alternative in such cases is to trigger the event manually with Javascript:

const evt = new Event('change', { bubbles: true });
document.querySelector('input[name="the-parent-field-name"]').dispatchEvent(evt);

Loading the plugin ...

Please wait ...

FileUploader

https://innostudio.de/fileuploader/

The FileUploader plugin offers a user-friendly interface and makes it easy to set up file fields: click or drag and drop uploads, choice of allowed extensions, file sizes, etc.

Uploading images, resizing them, creating thumbnails and displaying them is integrated and very easy to set up.

$form->addFileUpload(string $name, string $value = '', string $label = '', string $attr = '', array  $fileUpload_config = [], array  $current_file = []);
Argument Type Value Description
$input_name * String '' The name of the input field.
$value String '' The initial value of the input field.
$label String '' The label of the input field.
$attr String '' The input field attributes documentation
$fileUpload_config Array [] The plugin configuration node in phpformbuilder/plugins-config/fileuploader.xml
See Ready-to-use configurations below
$current_file Array [] File data if the uploader has to be loaded with an existing file.
Useful for update purpose.
Example of use here: templates/bootstrap-5-forms/fileupload-test-form.php

Ready-to-use configurations

File Uploader is supplied with several ready XML configs:

Value Uploader
'default' phpformbuilder/plugins/fileuploader/default/php/ajax_upload_file.php
'image-upload' phpformbuilder/plugins/fileuploader/image-upload/php/ajax_upload_file.php
'drag-and-drop' phpformbuilder/plugins/fileuploader/drag-and-drop/ajax_upload_file.php

$fileUpload_config - default configuration

$default_config = array(
    'xml'           => 'default',
    'uploader'      => 'ajax_upload_file.php',
    'upload_dir'    => '../../../../../file-uploads/',
    'limit'         => 1,
    'extensions'    => ['jpg', 'jpeg', 'png', 'gif'],
    'file_max_size' => 5,
    'thumbnails'    => false,
    'editor'        => false,
    'width'         => null,
    'height'        => null,
    'crop'          => false,
    'debug'         => false
);

$fileUpload_config - arguments

Name Type Default Description
'xml' String 'default' Name of the XML configuration node called in phpformbuilder/plugins-config/fileuploader.xml
'uploader' String 'ajax_upload_file.php' name of the PHP uploader file in phpformbuilder/plugins/fileuploader/[xms-node-name]/
'upload_dir' String '../../../../../file-uploads/' Path from the PHP uploader (i.e., phpformbuilder/plugins/fileuploader/default/php/ajax_upload_file.php) to the upload directory
'limit' Integer 1 Maximum number of uploaded files
'extensions' Array ['jpg', 'jpeg', 'png', 'gif'] Array with the allowed extensions
'file_max_size' Integer 5 maximal file size in MB
'thumbnails' Boolean false For image upload - Defines whether the uploader creates thumbnails or not - the thumbnails can be configured in the PHP image uploader in phpformbuilder/plugins/fileuploader/image-upload/php/ajax_upload_file.php
'editor' Boolean false For image upload - uploaded images can be clicked & edited by user (true|false)
'width' Integer|null null For image upload - maximum image width in px. null = no limitation
'height' Integer|null null For image upload - maximum image height in px. null = no limitation
'crop' Boolean false For image upload - crop image to fit the given width & height (true|false)
'debug' Boolean false Log errors in the browser console (true|false)

You can easily deal with uploaded files, thumbnails and images sizes in plugins/fileuploader/[xml]/php/[uploader].php

Other examples with code are available in Templates

Loading the plugin ...

Please wait ...

Uploaded file names and replacements

These options are set in phpformbuilder/plugins/fileuploader/[default|drag-and-drop|image-upload]/php/ajax_upload_file.php

The uploader PHP documentation is available on the author's website: https://innostudio.de/fileuploader/documentation/#php.

If the uploaded file has the same name as an existing file, the fileuploader will add a suffix.
E.g., "my-file-1.jpg".

To deal with the posted uploaded files:

// at the beginning of your file
use fileuploader\server\FileUploader;
include_once rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . 'phpformbuilder/plugins/fileuploader/server/class.fileuploader.php';

// once the form is validated
if (isset($_POST['user-logo']) && !empty($_POST['user-logo'])) {
    $posted_img = FileUploader::getPostedFiles($_POST['user-logo']);
    $filename   = $posted_img[0]['file'];
    // Then do what you want with the filename
}

Form Validation

http://formvalidation.io/

The Form Validation plugin is a professional JavaScript validation module with extensive functionality. It integrates perfectly with all frameworks and other plugins.

For complete documentation, see javascript validation.

HCaptcha

https://docs.hcaptcha.com

The HCaptcha plugin is an excellent alternative to Google's Recaptcha. It allows you to verify that the user of your form is not a bot without asking for problems for human users.

$form->addHcaptcha($hcaptcha_site_key, $attr);

// Validation after POST:
$validator->hcaptcha('hcaptcha-secret-key', 'Captcha Error')->validate('h-captcha-response');
Argument Type Value Description
$hcaptcha_site_key * String '' The HCaptcha site key. You have to get it on the HCaptcha website.
$attr String '' The HCaptcha data-attributes in a comma-separated list.
HCaptcha accepts several data-attributes for its configuration, you'll find them here: https://docs.hcaptcha.com/configuration
  • If you use CSP headers, please add the following to your configuration:
    • script-src should include https://hcaptcha.com, https://*.hcaptcha.com
    • frame-src should include https://hcaptcha.com, https://*.hcaptcha.com
    • style-src should include https://hcaptcha.com, https://*.hcaptcha.com
    • connect-src should include https://hcaptcha.com, https://*.hcaptcha.com
  • If you encounter any issue please see the hCaptcha documentation..

HCaptcha Local Development

PHP Form Builder detects your environment (localhost vs production) with this code:

if ($_SERVER['REMOTE_ADDR'] == '127.0.0.1' || $_SERVER['REMOTE_ADDR'] == '::1') {
    // local development server detected
}

If a local development server is detected, PHP Form Builder automatically replaces your HCaptcha keys with the Test Keys provided by hcaptcha.

In short, this means that your HCaptcha will work on your localhost and your production server. You don't have to worry about it.

Loading the plugin ...

Please wait ...

iCheck

https://github.com/fronteed/icheck

The iCheck plugin transforms radio buttons and checkboxes to make them look better

$form->addPlugin('icheck', $selector, $config, $options;
Argument Type Value Description
icheck * String '' The plugin name, which is 'icheck'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field(s) on which the plugin will be enabled.
$config * String 'default' 'default': Configuration to be used with the 'flat', 'minimal' or 'square' themes
'theme': Configuration to be used with the 'futurico' or 'polaris' themes
'line': Configuration to be used with the 'line' theme
$options * Array []

Associative array with:

Key Value
'theme' A theme from plugins/icheck/skins/.
Available themes: 'flat', 'futurico', 'line', 'minimal', 'polaris', 'square'
'color' A color from plugins/icheck/skins/[theme]/.
Available colors: 'purple', 'blue', 'green', 'grey', 'orange', 'pink', 'purple', 'red', 'yellow'
Example: 
[
    'theme' => 'flat',
    'color' => 'red'
]

Loading the plugin ...

Please wait ...

Image Picker

https://rvera.github.io/image-picker/

The Image Picker plugin allows you to select images by clicking them instead of displaying a select dropdown list. applies on <select> elements.

$form->addPlugin('image-picker', 'select');
Argument Type Value Description
image-picker * String '' The plugin name, which is 'image-picker'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field(s) on which the plugin will be enabled.
$config String 'default'

The configuration node in the plugin's XML file.
You can add your own configurations in phpformbuilder/plugins-config/image-picker

Image Picker plugin ~ available data-attributes for the option tags:

The following options are available with data-attributes on the <option> tags.

Attribute Type Default Description
data-img-src String '' The URL of the source image
data-img-alt String '' The alternative text
data-img-label String '' The image label (the parent select must have the show_label class

Image Picker plugin ~ available data-attributes for the select tags:

The following options are available with data-attributes and CSS class on the <select> fields

Attribute Type Default Description
data-limit Number null Limit maximum selection in multiple select
data-img-alt String '' The alternative text
show_label Boolean false Add the show_label class (i.e, class=show_label) to enable label for each option (image)

Loading the plugin ...

Please wait ...

Other examples with option groups & multiple selections are available at https://www.phpformbuilder.pro/templates/bootstrap-4-forms/image-picker-form.php.

Intl Tel Input (International Phone Numbers)

https://github.com/jackocnr/intl-tel-input

The Intl Tel Input plugin allows you to choose a country and display a corresponding phone number placeholder. It is perfectly well supported by the JavaScript validation plugin.

$form->addInput('tel', $name, $value, $label, 'data-intphone=true');
Argument Type Value Description
$type * String '' The input type. The Intl Tel Input plugin must be used with an input[type="tel"], so the expected value is 'tel'.
$input_name * String '' The name of the input field.
$value String '' The initial value of the input field.
$label String '' The label of the input field.
$attr String '' The input field attributes documentation

Special notes:

Add the data-intphone attribute to the input element to activate the Intl Tel Input plugin.
There is no need to call the addPlugin() function.

Intl Tel Input plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-allow-dropdown Boolean true Whether or not to allow the dropdown. If disabled, there is no dropdown arrow, and the selected flag is not clickable. Also, we display the selected flag on the right instead because it is just a state marker.
data-exclude-countries String '' In the dropdown, display all countries except the ones you specify here. You must enter countries' codes separated by commas.
data-initial-country String 'auto' Set the initial country selection by specifying its country code. You can also set it to "auto", which will look up the user's country based on their IP address
Example: 'fr'
data-only-countries String '' In the dropdown, display only the countries you specify. You must enter countries' codes separated by commas.
data-preferred-countries String '' Specify the countries to appear at the top of the list. You must enter countries' codes separated by commas.

If you use Intl Tel Input with the Formvalidation plugin,
add data-fv-intphonenumber=true to the input attributes.

Loading the plugin ...

Please wait ...

JS-Captcha

https://github.com/robiveli/js-captcha

Simple numeric captcha (anti-spam) rendered within basic canvas element.

$form->addInput('text', 'j-captcha-input', '', 'Type in result please', 'class=jCaptcha');

Special notes:

Add the jCaptcha class to the input element to activate the JS-Captcha plugin.
There is no need to call the addPlugin() function.

JS-Captcha plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-color String '#333' The CSS color for the challenge operation.
data-error-text String 'Wrong result' The error text for wrong result.
data-color [String]
The CSS color for the challenge operation.
Default: '#333'
data-error-text [String]
The error text for wrong result.

Server-side validation

The JS-Captcha plugin is effective only if JavaScript is enabled.
To overcome this problem, PHP Form Builder automatically creates a hidden field that allows server-side validation by adding this line to the PHP validator:

// replace 'j-captcha-input' with your input name
$validator->jsCaptcha()->validate('j-captcha-input');

Loading the plugin ...

Please wait ...

Ladda (Buttons spinners)

https://github.com/hakimel/Ladda

Buttons with built-in loading indicators, effectively bridging the gap between action and feedback.

$form->addBtn($type, $btn_name, $value, $label, 'data-ladda-button=true');
Argument Type Value Description
$type * String '' The button type. 'submit', 'button' or 'reset'.
$btn_name * String '' The name of the button.
$value * String '' The value of the button.
$label * String '' The label of the button.
$attr String '' The button attributes documentation

Special notes:

Add the data-ladda-button attribute to the button element to activate the Ladda plugin.
There is no need to call the addPlugin() function.

Ladda plugin ~ available data-attributes:

The following options are available with data-attributes on the <button> tag.

Attribute Type Default Description
data-style String 'zoom-in' The style of the Ladda loader.
'expand-left', 'expand-right', 'expand-up', 'expand-down', 'contract', 'contract-overlay', 'zoom-in', 'zoom-out', 'slide-left', 'slide-right', 'slide-up', 'slide-down'
data-spinner-size Number 40 pixel dimensions of spinner, defaults to dynamic size based on the button height.
data-spinner-color String '#fff' A hex code or any named CSS color.
data-spinner-lines Number 12 The number of lines the for the spinner

Loading the plugin ...

Please wait ...

LC-Switch (Checkbox/radio switches)

https://lcweb.it/lc-switch-javascript-plugin

The LC-Switch plugin turns radio buttons and checkboxes into switches.

It can be enabled globally on checkbox groups/radio button groupsith common texts and colors, or enabled individually on checkboxes/radio buttons with specific settings for each one.

$form->printCheckboxGroup($group_name, $label, $inline, 'data-lcswitch=true');
// or
$form->printRadioGroup($group_name, $label, $inline, 'data-lcswitch=true');
Argument Type Value Description
$group_name * String '' The name of the target checkbox group/radio button group.
$label String '' The main label of the checkbox group/radio button group.
$inline Boolean true Defines whether if the checkboxes/radio buttons are displayed inline or not.
$attr String '' The checkbox group/radio button group attributes documentation

Special notes:

To activate the LC-Switch plugin, add the data-lcswitch attribute to the checkbox group/radio button group.
There is no need to call the addPlugin() function.

LC-Switch plugin ~ available data-attributes:

The following options are available with data-attributes on the checkbox group/radio button group, AND <radio> or <radio> element.

Attributes defined on checkbox/radio elements have priority over those defined on checkbox group/radio button group

Attribute Type Default Description
data-ontext String 'Yes' Short 'On' text to fit into the switch width.
data-offtext String 'No' short 'Off' text to fit into the switch width.
data-oncolor String 'rgb(117, 185, 54)' Sets the background color of the "On" switches.
Can be any CSS color/gradient in any format.
data-oncss String '' Sets the background color of the "On" switches.
Can be any CSS classname.
"data-oncolor" takes precedence on "data-oncss".

Loading the plugin ...

Please wait ...

Litepicker (Date/Date range picker)

https://wakirin.github.io/Litepicker/

The LitePicker plugin is a very light and powerful date picker with many advanced features.

$form->addInput($type, $input_name, $value, $label, 'data-litepick=true');
Argument Type Value Description
$type * String '' The input type. The Litepicker plugin must be used with an input[type="text"], so the expected value is 'text'.
$input_name * String '' The name of the input field.
$value String '' The initial value of the input field.
$label String '' The label of the input field.
$attr String '' The select field attributes documentation

Special notes:

Add the data-litepick attribute to the input element to activate the Litepicker plugin.
There is no need to call the addPlugin() function.

The following options, whose value is an object or a function, must be passed in JavaScript, as well as the callback events:

  • buttonText (Object)
  • lockDaysFilter (function)
  • tooltipText (Object)

See The litePicker JavaScript API (Object & events)

Year/Month dropdowns

The original plugin passes a dropdowns object to enable Year/Month dropdowns.

With PHP Form Builder, you can enable the dropdowns with the data-dropdown-months and data-dropdown-years attributes.

LitePicker plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-allow-repick Boolean false If a date range is already selected, the user can change only the start date or the end date (depending on the clicked field) instead of the new date range.
data-auto-apply Boolean true Hide the apply and cancel buttons and automatically apply a new date range as soon as two dates are clicked.
data-auto-refresh Boolean false Indicates whether the date range picker should automatically update the value of the <input> element it's attached to at initialization and when the selected dates change.
data-delimiter String " - " Delimiter between dates.
data-disallow-lock-days-in-range Boolean false Prevent to select date ranges with locked dates.
data-dropdown-min-year Number 1990 Minimum year in the Years dropdown selector
data-dropdown-max-year Number null Maximum year in the Years dropdown selector
data-dropdown-months Boolean false Enables the Months dropdown selector
data-dropdown-years Boolean false Enables the Years dropdown selector
data-element-end String null Bind the datepicker to a element for end date. The value is the element ID.
data-end-date Date | Number | String null Preselect end date.
Required startDate.
Date Object or Unix Timestamp (with milliseconds) or String (must be equal to option format).
data-first-day Number 1 Day of start week. (0 - Sunday, 1 - Monday, 2 - Tuesday, etc.
data-format String "YYYY-MM-DD"

Allowed formats:

Token Output
Day of Month D 1 2 … 30 31
DD 01 02 … 30 31
Month M 1 2 … 11 12
MM 01 02 … 11 12
MMM Jan Feb … Nov Dec
MMMM January February … November December
Year YY 70 71 … 29 30
YYYY 1970 1971 … 2029 2030
data-highlighted-days Array [] Highlight days. Can contains array with range:
E.g., [ ['2019-01-01', '2019-01-10'], '2019-01-31' ].
Can contain Date Object or Unix Timestamp (with milliseconds) or String (must be equal to option highlightedDaysFormat).
data-highlighted-days-format String "YYYY-MM-DD" Date format for option highlightedDays.
data-inline-mode Boolean false Show calendar inline.
data-lang String "en-US" Language. This option affect to day names, month names via Date.prototype.toLocaleString() and also affect to plural rules via Intl.PluralRules.
data-lock-days Array [] Disable days for select. Can contain array with range:
Eg: [ ['2019-01-01', '2019-01-10'], '2019-01-31' ].
This example will disable range from 01 Jan 2019 to 10 Jan 2019 and 31 Jan 2019.
Can contain Date Object or Unix Timestamp (with milliseconds) or String (must be equal to option lockDaysFormat).
data-lock-days-format String "YYYY-MM-DD" Date format for option lockDays.
data-lock-days-inclusivity String "[]" A [ indicates inclusion of a value. A ( indicates exclusion. If the inclusivity parameter is used, both indicators must be passed.
data-max-date Date | Number | String null The maximum/latest date that users can select.
Date Object or Unix Timestamp (with milliseconds) or ISO String.
data-max-days Number null The maximum days of the selected range.
data-min-date Date | Number | String null The minimum/earliest date that users can choose.
Date Object or Unix Timestamp (with milliseconds) or ISO String.
data-min-days Number null The minimum days of the selected range.
data-number-of-columns Number 1 Number of columns months.
data-number-of-months Number 1 Number of visible months.
data-parent-el String null Adds the date picker to an element. The value is the element ID.
data-position String 'auto'

A space-separated string consisting of one or two of left or right, top or bottom, and auto (may be omitted).

For example:

  • 'top left' - calendar will be displayed above the element.
  • 'bottom' - calendar will be displayed below the element. Horizontal orientation will be default to auto.
  • 'right' - vertical orientation will default to auto.
data-reset-button Boolean false Adds a reset button to clear the current selection.
data-scroll-to-date Boolean true Scroll to start date on open.
data-select-backward Boolean false Select second date before the first selected date.
data-select-forward Boolean false Select second date after the first selected date.
data-show-tooltip Boolean true Showing tooltip with how much days will be selected.
data-show-week-numbers Boolean false Show week numbers. Based on option firstDay.
data-single-mode Boolean true Choose a single date instead of a date range.
data-split-view Boolean true Enable the previous and the next button for each month.
data-start-date Date | Number | String null Preselect date.
If option singleMode is disabled, then endDate must be set too.
Date Object or Unix Timestamp (with milliseconds) or String (must be equal to option format).
data-switching-months Number null Indicates whether the date range picker should switch months by this value instead of the numberOfMonths' value'.
data-z-index Number 9999 Control zIndex of the picker element.

The litePicker JavaScript API (Object & events)

PHP Form Builder creates a global litePickers object. Then each instance is registered with its input field name.
It allows access to each instance individually and the use of the litepicker Events or functions.
For instance:

// get the input id
let inputId = 'my-input';

// set some options
litePickers[inputId].setOptions({'onSelect': function() {
    console.log(this.options);
    console.log(this.getDate());
    console.log(document.getElementById(inputId).value);
}});

litePickers[inputId].setOptions({
    'buttonText': {
        "apply":"Apply",
        "cancel":"Cancel",
        "previousMonth":"<svg>...</svg>",
        "nextMonth":"<svg>...</svg>",
        "reset":"<svg>...</svg>"
    }
});

Loading the plugin ...

Please wait ...

Other examples with different options are available at https://www.phpformbuilder.pro/templates/bootstrap-4-forms/date-range-picker-form.php.

Material Design plugin

https://materializecss.com/

Material Design must be enabled globally as a framework when creating your form.

Check out the code of the "Material" and "Material Bootstrap" templates to see how it works.

$form = new Form($form_id, $layout, $attr, 'material');

// if your page uses Bootstrap add the following line to enable the Material Design style
$form->addPlugin('materialize', $selector);
Argument Type Value Description
materialize * String '' The plugin name, which is 'materialize'.
$selector * String '' The CSS selector (e.g., '#my-form') of the form on which the plugin will be enabled.

Loading the plugin ...

Please wait ...

Material Datepicker

https://materializecss.com/pickers.html

The Material Datepicker plugin can be used with any framework (Bootstrap 4, Bootstrap 5, Bulma, Foundation, Material Design, ...)

$form->addPlugin('material-datepicker', $selector, $config);
Argument Type Value Description
material-datepicker * String '' The plugin name, which is 'material-datepicker'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field(s) on which the plugin will be enabled.
$config String 'default'

The configuration node in the plugin's XML file.
You can add your own configurations in phpformbuilder/plugins-config/material-datepicker

If you use the Material Datepicker plugin with Ajax AND without Material framework,
you have to load the 3 following files in your main page:

  • <link rel="stylesheet" href="/phpformbuilder/plugins/material-pickers-base/dist/css/material-pickers-base.min.css">
  • <script src="/phpformbuilder/plugins/material-pickers-base/dist/js/material-pickers-base.min.js"></script>
  • <script src="/phpformbuilder/plugins/material-datepicker/dist/i18n/en_EN.js"></script>

Special notes:

Material Datepicker JavaScript API (Object & events)

Get the Datepicker instance as described in Materialize's documentation: var instance = M.Datepicker.getInstance(elem);.

Material Datepicker plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-auto-close Boolean false Automatically close picker when date is selected.
data-format String 'mmm dd, yyyy' The date output format for the input field value.
data-default-date null|String null The initial date to view when first opened.
The date must be a string in JavaScript Date Object format
data-set-default-date Boolean false Make the defaultDate the initially selected value.
data-disable-weekends Boolean false Prevent selection of any date on the weekend.
data-first-day Number 0 First day of the week (0: Sunday, 1: Monday, etc.).
data-min-date null|String null The earliest date that can be selected.
The date must be a string in JavaScript Date Object format.
data-max-date null|String null The latest date that can be selected.
The date must be a string in JavaScript Date Object format.
data-year-range Number 10 Number of years either side or array of upper/lower range.
data-is-rtl Boolean false Changes Datepicker to RTL.
data-show-month-after-year Boolean false Show the month after the year in the Datepicker title.
data-show-days-in-next-and-previous-months Boolean false Render days of the calendar grid that fall in the next or previous month.
data-show-clear-btn Boolean false Show the clear button in the datepicker.

Translation (i18n)

  1. Add your language file in phpformbuilder/plugins/material-datepicker/dist/i18n/
  2. Initialize the plugin with your language, for example:
    $form->addPlugin('material-datepicker', '#selector', 'default', array('language' => 'fr_FR'));

Loading the plugin ...

Please wait ...

Material Timepicker

https://materializecss.com/pickers.html

The Material Timepicker plugin can be used with any framework (Bootstrap 4, Bootstrap 5, Bulma, Foundation, Material Design, ...)

$form->addPlugin('material-timepicker', $selector, $config);
Argument Type Value Description
material-timepicker * String '' The plugin name, which is 'material-timepicker'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field(s) on which the plugin will be enabled.
$config String 'default'

The configuration node in the plugin's XML file.
You can add your own configurations in phpformbuilder/plugins-config/material-timepicker

If you use the Material Timepicker plugin with Ajax AND without Material framework,
you have to load the 3 following files in your main page:

  • <link rel="stylesheet" href="/phpformbuilder/plugins/material-pickers-base/dist/css/material-pickers-base.min.css">
  • <script src="/phpformbuilder/plugins/material-pickers-base/dist/js/material-pickers-base.min.js"></script>
  • <script src="/phpformbuilder/plugins/material-datepicker/dist/i18n/en_EN.js"></script>

Special notes:

Timepicker Datepicker JavaScript API (Object & events)

Get the Datepicker instance as described in Materialize's documentation: var instance = M.Timepicker.getInstance(elem);.

Material Timepicker plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-show-clear-btn Boolean false Show the clear button in the timepicker.
data-default-time String 'now' Default time to set on the timepicker.
e.g., 'now' or '13:14'.
data-from-now Number 0 Millisecond offset from the defaultTime.
data-auto-close Boolean false Automatically close picker when minute is selected.
data-twelve-hour Boolean true Use 12 hour AM/PM clock instead of 24 hour clock.

Translation (i18n)

  1. Add your language file in phpformbuilder/plugins/material-timepicker/dist/i18n/
  2. Initialize the plugin with your language, for example:
    $form->addPlugin('material-timepicker', '#selector', 'default', array('language' => 'fr_FR'));

Loading the plugin ...

Please wait ...

https://github.com/Ghosh/micromodal

The Micromodal plugin is a lightweight, configurable and Accessibility-enabled modal library written in pure JavaScript.

PHP Form Builder creates the HTML code for the modal and wraps your form inside it when you enable it.
So you just need to add a link to your page to open the modal with the form inside.
No additional code is required.

Special notes:

The link that will open the modal must have the data-micromodal-trigger="modal-form-id" attribute where modal-form-id is the literal string 'modal-' + the form id.

For instance, if you create your form with $form = new Form('my-form');, the data-attribute for the modal link will be: data-micromodal-trigger="modal-my-form"

<?php
// create the form & enable the modal plugin
$form = new Form('form-id');
// add fields, ...

// enable the modal plugin
$form->modal();

// ... or with some custom options
$modal_options = [
    'title'       => 'Here is a modal form',
    'title-class' => 'text-secondary',
    'title-tag'   => 'h3',
    'animation'   => 'slide-in-top',
    'blurred'     => false
];
$form->modal($modal_options);
?>

<!-- PHP code inside <head /> -->
<?php $form->printIncludes('css'); ?>

<!--
HTML modal link, anywhere inside the <body /> tag
"modal-form-id" is the literal string 'modal-' + the id of your modal form.
e.g., if your form id is 'my-form', the code will be:
<button data-micromodal-trigger="modal-my-form" ...


IMPORTANT - DON'T FORGET TO ADD "modal-" before your form-id in "data-micromodal-trigger" -->
<button data-micromodal-trigger="modal-form-id" class="btn btn-primary text-white btn-lg">Open the modal form</button>

<!-- Render the form anywhere inside the <body /> tag --> -->
<?php $form->render(); ?>

<!-- PHP code at the end of <body /> -->
<?php
$form->printIncludes('js');
$form->printJsCode();
?>

Available options:

$modal_options is an optional array which can contain the following keys/values:

Option Type Default Description
'title' String '' Title (string or HTML code) of the modal header. If empty, the modal won't have any header.
'title-class' String '' CSS class of the title.
'title-tag' String 'h2' The HTML tag name of the title.
'animation' String 'fade-in' The entrance animation for the modal; one of the followings:
'fade-in', 'slide-in-top', 'slide-in-left', 'slide-in-right', 'slide-in-bottom', 'scale-in', 'flip-in-horizontal', 'flip-in-vertical'
'blur' Boolean true Blur the page behind the modal overlay if enabled

Nice Check

The Nice Check plugin converts your checkboxes and ratio buttons to make them look better.

$form->addPlugin('nice-check', $selector, $config, $options);
Argument Type Value Description
nice-check * String '' The plugin name, which is 'nice-check'.
$selector * String '' The selector of the form (e.g., #my-form) in which the plugin is activated.
$config * String 'default'

The XML node where the plugin JavaScript code is in plugins-config/nice-check.xml
$options * Array ['skin' => 'green']

Associative array with:

Key Value
'skin' A skin from the available skins listed below.

Available skins:

Example with skins & code available here: Custom radio checkbox css form

Loading the plugin ...

Please wait ...

Passfield

https://antelle.net/passfield/

The Passfield plugin makes it easy to create passwords, choose the required complexity, generate them automatically, and warn users if their password is too simple.

The functions required for validation in PHP are provided for server-side validation.

$form->addPlugin('passfield', $selector, $config);
Argument Type Value Description
passfield * String '' The plugin name, which is 'passfield'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field on which the plugin will be enabled.
$config * String 'default'

One of the available configurations in phpformbuilder/plugins-config/passfield.xml.
Each Passfield pattern represents the constraints that the password must meet (number of characters, uppercase, numbers, special characters). See Available patterns below.

Available patterns ($config values):

The patterns are validated in JavaScript by the Passfield plugin.
An additional server-side validation after posting the form is recommended.
We can easily do it with the PHP Validators.

x is a number between 3 and 8.

Value Description PHP validation
'default' The password must contain lowercase letters + numbers and be 8 characters long. 
$validator
->hasLowercase()
->hasNumber()
->minLength(8)
->validate('user-password');
'lower-upper-min-x' The password must contain lowercase + uppercase letters and be x characters long. 
$validator
->hasLowercase()
->hasUppercase()
->minLength(x)
->validate('user-password');
'lower-upper-number-min-x' The password must contain lowercase + uppercase letters + numbers and be x characters long. 
$validator
->hasLowercase()
->hasUppercase()
->hasNumber()
->minLength(x)
->validate('user-password');
'lower-upper-number-symbol-min-x' The password must contain lowercase + uppercase letters + numbers + symbols and be x characters long. 
$validator
->hasLowercase()
->hasUppercase()
->hasNumber()
->hasSymbol()
->minLength(x)
->validate('user-password');

You can easily add your own patterns into phpformbuilder/plugins-config/passfield.xml.A pattern generator is available at https://antelle.net/passfield/demo.html.

Loading the plugin ...

Please wait ...

Pickadate

http://amsul.ca/pickadate.js/

Pickadate is a jQuery date/time picker jQuery. A new version in Vanilla JavaScript is planned for a future update.

The author of the plugin is working on a new Vanilla JS version.
It will be released as soon as a stable version is available.

Date picker

$form->addPlugin('pickadate', $selector, $config);
Argument Type Value Description
pickadate * String '' The plugin name, which is 'pickadate'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field(s) on which the plugin will be enabled.
$config String 'default'

'default' | 'pickatime'

The 'default' configuration is for the datepicker,
'pickatime' is for the timepicker.

Special notes:

The list of the date formats used by the Pickadate plugin is available here: https://amsul.ca/pickadate.js/date/#formatting-rules.

Pickadate plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-format String 'mmm dd, yyyy' The date output format for the input field value.
data-format-submit String undefined Display a human-friendly format and use an alternate one to submit to the server.
It is done by creating a new hidden input element with the same name attribute as the original with the _submit suffix.
data-select-years Boolean undefined Display select menu to pick the year.
data-select-months Boolean undefined Display select menu to pick the month.
data-first-day Number undefined First day of the week (0: Sunday, 1: Monday, etc.).
data-min String null The earliest date that can be selected.
The date must be a string in JavaScript Date Object format.
data-max String null The latest date that can be selected.
The date must be a string in JavaScript Date Object format.
data-close-on-select Boolean true When a date is selected, the picker closes. To change this behavior, use the following option.
data-close-on-clear Boolean true When the "clear" button is pressed, the picker closes. To change this behavior, use the following option.

Translation (i18n)

  1. Add your language file in phpformbuilder/plugins/pickadate/lib/translations/
  2. Initialize the plugin with your language, for example:
    $form->addPlugin('pickadate', '#selector', 'default', array('language' => 'fr_FR'));

Loading the plugin ...

Please wait ...

Time picker

The Time picker is built with Pickadate, a jQuery date/time picker. A new version in Vanilla JavaScript is planned for a future update.

The author of the plugin is working on a new Vanilla JS version.
It will be released as soon as a stable version is available.

$form->addPlugin('pickadate', $selector, $config);
Argument Type Value Description
pickadate * String '' The plugin name, which is 'pickadate'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field(s) on which the plugin will be enabled.
$config String 'default'

'default' | 'pickatime'

The 'default' configuration is for the datepicker,
'pickatime' is for the timepicker.

Time picker plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-format String 'h:i A' The time output format for the input field value.
data-format-submit String undefined Display a human-friendly format and use an alternate one to submit to the server.
This is done by creating a new hidden input element with the same name attribute as the original with the _submit suffix.
data-interval Number 30 Choose the minutes interval between each time in the list.
data-min String undefined Set the minimum selectable times on the picker.
Arrays formatted as [HOUR, MINUTE] (see example below).
data-max String undefined Set the maximum selectable times on the picker.
Arrays formatted as [HOUR, MINUTE] (see example below).
data-close-on-select Boolean true When a time is selected, the picker closes. To change this behavior, use the following option.
data-close-on-clear Boolean true When the "clear" button is pressed, the picker closes. To change this behavior, use the following option.

Translation (i18n)

  1. Add your language file in phpformbuilder/plugins/pickadate/lib/translations/
  2. Initialize the plugin with your language, for example:
    $form->addPlugin('pickadate', '#selector', 'pickatime', array('language' => 'fr_FR'));

Loading the plugin ...

Please wait ...

Popover

https://atomiks.github.io/tippyjs/

The Popover plugin uses tippyjs, as well as the Tooltip plugin.
The configuration is therefore defined in the popover node of plugins-config/tooltip.xml.
The settings must be passed as data-attributes on the link(s) that will open the popover.

Special notes:

The link that will open the popover must have the data-popover-trigger="form-id" attribute where form-id is your form id.

For instance, if you create your form with $form = new Form('my-form');, the data-attribute for the popover link will be: data-popover-trigger="my-form"

<?php
// create the form & enable the popover plugin
$form = new Form('form-id');
// add fields, ...

// enable the popover plugin
$form->popover();
?>

<!-- PHP code inside <head /> -->
<?php $form->printIncludes('css'); ?>

<!-- HTML popover link, anywhere inside the <body /> tag -->
<button data-popover-trigger="form-id" class="btn btn-primary text-white btn-lg">Open the popover form</button>

<!-- Render the form anywhere inside the <body /> tag --> -->
<?php $form->render(); ?>

<!-- PHP code at the end of <body /> -->
<?php
$form->printIncludes('js');
$form->printJsCode();
?>

Popover plugin ~ available data-attributes:

The following options are available with data-attributes on the link or button that will open the popover.

Attribute Type Default Description
data-animation String 'fade' The popover show/hide animation, among the followings: 'fade', 'shift-away', 'shift-toward', 'scale', 'perspective'
data-arrow Boolean true The arrow that points toward the element.
data-backdrop Boolean false Covers the page with a semi-opaque background. The background can be customized in plugins/tippyjs/stylesheets/backdrop.min.css
data-delay Number 0 The delay in milliseconds before opening the popover.
data-max-width String 'none' The maximum width of the popover. All valid css units are accepted (px, rem, vw, etc.).
data-placement String 'top' The preferred placement of the tippy. Popper's flip modifier can change it to the opposite placement if it has more space.
'top', 'top-start', 'top-end', 'right', 'right-start', 'right-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end', 'auto', 'auto-start', 'auto-end'
data-theme String 'light' The package comes with themes for you to use:
'light', 'light-border', 'material', 'translucent', 'null'
data-trigger String 'click' Determines the events that cause the tippy to show. Multiple event names are separated by spaces.
For instance: 'mouseenter focus'.
data-z-index Number 9999 Specifies the z-index CSS on the root popper node.

Loading the plugin ...

Please wait ...

Pretty Checkbox

https://github.com/lokesh-coder/pretty-checkbox

Pretty Checkbox is a pure CSS library to beautify checkbox and radio buttons.
The PHP Form Builder Pretty Checkbox plugin adds a small JavaScript layer that makes it easier to activate and configure the plugin by setting its options globally and its parameters using data-attributes.

$form->addPlugin('pretty-checkbox', $selector, $config, $options);

Activate the plugin and set its options globally with the $form->addPlugin() function. Then you can change any option individually on each target element.

The plugin allows icons, colors, and a toggle function; these options must be defined for each element individually using data-attributes.

Argument Type Value Description
pretty-checkbox * String '' The plugin name, which is 'pretty-checkbox'.
$selector * String '' The CSS selector (e.g., '#my-form') of the field(s) on which the plugin will be enabled.
$config String 'default'

The configuration node in the plugin's XML file.
You can add your own configurations in phpformbuilder/plugins-config/pretty-checkbox.xml
$options Array ['checkboxStyle' => 'default', 'radioStyle' => 'default', 'fill' => 'none', 'plain' => '', 'size' => 'none', 'animations' => 'none']

An associative array with the options names => values.

The available options are the followings:

Option name Type Available values Default value
checkboxStyle [String] 'default', 'curve', 'round' 'default' (square shapes)
radioStyle [String] 'default', 'curve', 'round' 'round'
fill [String] '', 'fill', 'thick' '' (default style)
plain [String] '', 'plain' ''
size [String] '', 'bigger' '' (default size)
animations [String] '', 'smooth', 'jelly', 'tada', 'rotate', 'pulse' ''
(no animation)

Pretty Checkbox plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-color String '' One of the followings: 'primary', 'primary-o', 'success', 'success-o', 'info', 'info-o', 'warning', 'warning-o', 'danger', 'danger-o'
The -o means "outline".
data-icon String '' Icon class from any icon library.
You need to add the appropriate font icon library to your application.
data-toggle Boolean false

Toggle allows showing a different content depending on the input on/off state.
When you enable data-toggle you can set the on/off states with the following data-attributes:

Attribute Type description
data-on-label String The text of the label when checked
data-off-label String The text of the label when unchecked
data-on-icon String The icon class when checked.
For the Material Icons library, add the material-icons class and then the icon name.
e.g., data-on-icon=material-icons radio_button_checked
data-on-label String The text of the label when checked
data-off-icon String The icon class when unchecked.
For the Material Icons library, add the material-icons class and then the icon name.
e.g., data-on-icon=material-icons radio_button_unchecked
data-on-color String The color when checked
data-off-color String The color when unchecked

Loading the plugin ...

Please wait ...

Recaptcha V3 - https://www.google.com/recaptcha/

The Recaptcha V3 plugin allows you to verify that your form user is not a bot without asking for problems for human users.

$form->addRecaptchav3($sitekey);

// Validation after POST:
$validator->recaptcha($secretkey, $error_msg)->validate('g-recaptcha-response');

$sitekey is the site key that you get from the Google Recaptcha website.

$secretkey is the secret key that you get from the Google Recaptcha website.

$error_msg is the error message shown to the users if the verification fails.
Default is "Recaptcha Error"

'g-recaptcha-response' is the name of the response field (leave it as it is).

Live examples available in Templates

Select2

https://select2.org/

The Select2 plugin gives you a customizable select box with support for searching, tagging, remote data sets, infinite scrolling, and many other highly used options.

$form->addSelect($select_name, $label, 'class=select2');
Argument Type Value Description
$select_name * String '' The name of the target select field.
$label String '' The label of the select field.
$attr String '' The select field attributes documentation

Special notes:

Add the select2 class to the select element to activate the Select2 plugin.
There is no need to call the addPlugin() function.

Select2 plugin ~ available data-attributes:

Options:

Pass options with data-attributes on the <select> field. Example:

$form->addSelect('select-name', 'Label', 'class=select2, data-width=100%');

The data-attribute list is available at https://select2.org/configuration/options-api.

More details about data-attribute usage at https://select2.org/configuration/data-attributes

Instead of adding the select2 class to the select element, you can also call the addPlugin() function.

This way, you can call a custom node from the XML configuration file (phpformbuilder/plugins-config/select2.xml).

This method allows you to store different custom select2 configurations and, for example, change the buildTemplate function, which builds the options dropdown list.

Loading the plugin ...

Please wait ...

Quick Tips

Remove search box
Select2 adds a search box to the dropdowns. To remove the search box, add data-minimum-results-for-search=Infinity to the select element attributes.
Placeholders
To add a placeholder, first add an empty option:
$form->addOption('category', '', '');
Then use data-placeholder=Your placeholder text

Signature pad

https://github.com/szimek/signature_pad

The Signature Pad plugin is a JavaScript library for drawing smooth signatures. It's HTML5 canvas based and uses variable width Bézier curve interpolation. It works in all modern desktop and mobile browsers and doesn't depend on any external libraries.

$form->addInput('hidden', $input_name, $value, $label, 'class=signature-pad, data-background-color=#336699, data-pen-color=#fff, data-width=100%, data-clear-button=true, data-clear-button-class=btn btn-sm btn-warning, data-clear-button-text=clear, data-fv-not-empty, data-fv-not-empty___message=You must sign to accept the license agreement');
Argument Type Value Description
$type * String '' The input type. The Signature pad plugin must be used with an input[type="hidden"], so the expected value is 'hidden'.
$input_name * String '' The name of the input field.
$value String '' The initial value of the input field.
$label String '' The label of the input field.
$attr String '' The input field attributes documentation

Special notes:

Add the data-signature-pad attribute to the input element to activate the Signature pad plugin.
There is no need to call the addPlugin() function.

The signature value is sent with the hidden input. The value is a base64 png image (data:image/png;base64).

Here's how to save the image on the server:

$data_uri = $_POST['fieldname'];
$encoded_image = explode(',', $data_uri)[1];
$decoded_image = base64_decode($encoded_image);
file_put_contents('signature.png', $decoded_image);

Signature pad plugin ~ available data-attributes:

The following options are available with data-attributes on the <input> field.

Attribute Type Default Description
data-width Number | String '100%' The input field width. Accepts number (in pixels) or percent value.
data-height Number 300 The input field height. Accepts number (in pixels).
data-background-color String 'rgba(255, 255, 255, 0)' The background color in valid CSS format. The default background color is white.
data-pen-color String 'rgb(0, 0, 0)' The pen color in valid CSS format. The default pen color is black.
data-clear-button Boolean false Show a button to clear the signature
data-clear-button-class String '' The CSS classes for the clear button
data-clear-button-text String 'clear' The text of the clear button

Loading the plugin ...

Please wait ...

Slimselect

http://slimselectjs.com

The Slimselect plugin is a Vanilla JS plugin to enhance the select dropdown lists.

It's an excellent alternative to the Select2 plugin for those who want to avoid the jQuery dependency. Similar features are available: search, tagging, Ajax, many others options and callbacks.

$form->addSelect($select_name, $label, 'data-slimselect=true');
Argument Type Value Description
$select_name * String '' The name of the target select field.
$label String '' The label of the select field.
$attr String '' The select field attributes documentation

Special notes:

Add the data-slimselect attribute to the select element to activate the Slimselect plugin.
There is no need to call the addPlugin() function.

Slimselect JavaScript API (Object & events)

The JavaScript instance is stored in the global variable window.slimSelects[selectId] when you activate the plugin.

You can then use it to call the Slimselect JavaScript API, for example:

<script>
    document.addEventListener('DOMContentLoaded', function(event) {
        slimSelects['my-select-name'].enable();
    });
</script>

Slimselect ~ available data-attributes:

The following options are available with data-attributes on the <select> field.

Attribute Type Default Description
data-placeholder String '' Set a placeholder text when nothing is selected. Single selects require an empty option with data-placeholder set to true to enable it.
data-allow-deselect Boolean true This will allow you to deselect a value on a single select dropdown.
Be sure to have an empty option data placeholder, so slimselect has an empty string value to select.
data-allow-deselect-option Boolean true This will allow you to deselect a value in the dropdown by clicking the option again.
Be sure to have an empty option data placeholder, so slimselect has an empty string value to select.
data-deselect-label String 'x' svg image This will allow you to change the deselect label (default is an 'x' svg image) on single select lists and the delete label on multiple-select lists.
Note: Be aware of the limited space available for it.
data-addable Boolean false Slim select can dynamically add options via the search input field. The added values are automatically sanitized by PHP Form Builder using dompurify.
data-limit Number 0 When using multi-select, you limit the number of selections you can have.
Zero is no limit.
data-show-search Boolean true Decide whether or not to show the search.
data-search-text String 'No Results' The string that will show in the event there are no results.
data-search-placeholder String 'Search ...' The input search placeholder text.
data-search-focus Boolean false Focus search input on opening
data-search-highlight Boolean true Highlights search results
data-close-on-select Boolean true Determines whether or not to close the content area upon selecting a value.
data-show-content String 'auto' Decide where to show your content when it comes out. By default, slimselect will try to put the content where it can without going off-screen. But you may always want to show it in one direction.
Possible Options: 'auto', 'up' or 'down'.
data-add-to-body Boolean true Configures the select dropdown to be added directly to the document body, rather than the parent container. It allows using slimselect in scenarios where you have no control of the overflow state of the parent containers. Remember that the widget has to be removed explicitly by calling destroy.
data-select-by-group Boolean false Enables the selection of all options under a specific group by clicking that option group's label.
data-hide-selected-option Boolean false Hide the current selected option in the dropdown.

The following options are available with data-attributes on the <option> tags. For instance:

$form->addOption('select-name', 'value', 'text', 'opt-groupname', 'data-icon=bi bi-headphones me-2');
Attribute Type Default Description
data-icon String '' The icon CSS classes of the icon tag that'll be added before the option text.
You can use any icon library of your choice: Fontawesome, Material icons, ...
data-html String '' Replaces the option text by any HTML code of your choice.

Loading the plugin ...

Please wait ...

Tinymce

https://www.tiny.cloud/tinymce/

Tinymce is a WYSIWYG editor known, and loved, by millions of developers worldwide

$form->addPlugin('tinymce', $selector, $config);
Argument Type Value Description
tinymce * String '' The plugin name, which is 'tinymce'.
$selector * String '' The CSS selector (e.g., '#fieldname') of the field(s) on which the plugin will be enabled.
$config * String 'default'
'default' The default configuration activates the most common Tinymce plugins, including the Responsive Filemanager.
'word-char-count' Same configuration as the default, with the addition of a word and character counter.
'light' Minimal configuration, without file manager, to be used, for example, for a contact form.

The configuration node in the plugin's XML file.
You can add your own configurations in phpformbuilder/plugins-config/tinymce.xml

Customization &Translation (i18n)

To customize the TinyMCE editor settings:

  1. Duplicate phpformbuilder/plugins-config/tinymce.xml to phpformbuilder/plugins-config-custom/tinymce.xml
  2. Make your changes in the duplicated file (in the plugins-config-custom folder).

If you change the language:

Download the language file on tiny.cloud website and put it in phpformbuilder/plugins/tinymce/langs/

Loading the plugin ...

Please wait ...

Tooltip

https://atomiks.github.io/tippyjs/

The Tooltip plugin uses tippyjs, as well as the Popover plugin.

Special notes:

Add the data-tooltip attribute to the input element to activate the Tooltip plugin.
There is no need to call the addPlugin() function.

You can add tooltips anywhere in your form, not only on fields but also on labels, helpers, or any content.

The tooltips can also contain HTML content based on HTML templates and be interactive.

Tooltip plugin ~ available data-attributes:

The following options are available with data-attributes.

Attribute Type Default Description
data-tooltip String '' Enables the tooltip on the element.
The value is the tooltip text content if data-content-src is not defined.
data-content-src String undefined The id of the template that contains the tooltip HTML content.
For instance, create a <template id="tooltip-html-content"></template>, then set data-content-src=tooltip-html-content.
(See example 2 below).
data-animation String 'fade' The popover show/hide animation, among the followings: 'fade', 'shift-away', 'shift-toward', 'scale', 'perspective'
data-arrow Boolean true The arrow that points toward the element.
data-delay Number 0 The delay in milliseconds before opening the popover.
data-interactive Boolean false Whether to enable interactivity inside the tooltip content.
data-placement String 'top' The preferred placement of the tippy. Popper's flip modifier can change this to the opposite placement if it has more space.
'top', 'top-start', 'top-end', 'right', 'right-start', 'right-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end', 'auto', 'auto-start', 'auto-end'
data-theme String 'light' The package comes with themes for you to use:
'light', 'light-border', 'material', 'translucent', 'null'
data-trigger String 'mouseenter' Determines the events that cause the tippy to show. Multiple event names are separated by spaces.
For instance: 'mouseenter focus'.
data-z-index Number 9999 Specifies the z-index CSS on the root popper node.

Loading the plugin ...

Please wait ...

Word/Character Count

The Word/Character Count plugin is a tiny custom PHP Form Builder plugin built to display a characters/words counter below textareas. It can also be used with Tinymce.

$form->addPlugin('word-character-count', $selector, $config, $options);
Argument Type Value Description
word-character-count * String '' The plugin name, which is 'word-character-count'.
$selector * String ''

The CSS selector (e.g., '#fieldname') of the field on which the plugin will be enabled.

The word-character-count plugin must be activated individually for each target field (It doesn't accept CSS class selectors).
$config * String 'default'

The configuration node in the plugin's XML file.
You can add your own configurations in phpformbuilder/plugins-config/word-character-count.xml
$options * Array []

Associative array with:

Key Value
'maxCharacters' [Number] The maximum number of characters.
Default: 100
'maxWords' [Number] The maximum number of words.
Default: 10
characterCount [Boolean] Whether to display the characters counter or not.
Default: true
wordCount [Boolean] Whether to display the words counter or not.
Default: true
characterText [String] The text for 'character(s)'
Default: 'character(s)'
wordText [String] The text for 'word(s)'.
Default: 'word(s)'
separator [String] The separator character(s) between words count and characters count.
Default: ' • '
wrapperClassName [String] The CSS classname(s) for the wrapper div element.
Default:
automatically set according to your framework:
Bootstrap 4/5: 'form-text',
Bulma: 'help',
Foundation: 'help-text',
Material: 'form-text',
Tailwind: 'mt-2 text-sm',
UIkit: 'uk-text-small'
className [String] The CSS classname for the counter when the maximum number of characters is not reached.
Default:
automatically set according to your framework:
Bootstrap 4/5: 'text-muted mb-0',
Bulma: 'has-text-grey',
Foundation: '',
Material: 'text-muted',
Tailwind: 'text-gray-500 dark:text-gray-400',
UIkit: 'uk-text-muted uk-margin-remove-bottom'
errorClassName [String] The CSS classname for the counter when the maximum number of characters is reached.
Default:
automatically set according to your framework:
Bootstrap 4/5: 'text-danger mb-0',
Bulma: 'has-text-danger',
Foundation: '',
Material: 'text-danger',
Tailwind: 'text-danger-500 dark:text-danger-400',
UIkit: 'uk-text-danger uk-margin-remove-bottom'

Loading the plugin ...

Please wait ...