Utillities

Input Groups

Input Groups allow having several inputs/selects on the same line in horizontal forms.

You can group up to twelve elements.

There's two ways to set arguments:

    // 1st way: each fieldname as argument
    $form->groupElements('street', 'zip', 'countries');

    // 2nd way: a single array including all fieldnames as argument
    $fields = array('street', 'zip', 'countries');
    $form->groupElements($fields);

Always create your input group BEFORE creating the input elements.

$form->groupElements($input1, $input2, ..., $input12 = '');

/**
 * Allows to group inputs in the same wrapper
 *
 * Arguments can be :
 *     -    a single array with fieldnames to group
 *     OR
 *     -    fieldnames given as strings
 *
 * @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.
 * @return \phpformbuilder\Form
 */

Input Groups Example

    $form->startFieldset('Personal informations');
    $form->groupElements('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();

Personal informations

Your address: ^*

Countries United States Canada France

Set Cols

The setCols() function wraps label and fields with columns.

The columns can only be set in horizontal forms.

$form->setCols(int $labelColNumber, int $fieldColNumber, string $breakpoint = 'sm');

Bootstrap 4 / 5 auto column
Bootstrap 4 & Bootstrap 5 allows automatic-width columns.
To build automatic-width columns, set $fieldsCols to -1

/**
 * Shortcut for labels & cols options
 *
 * @param int $labelColNumber number of columns for label
 * @param int $fieldColNumber number of columns for fields
 * @param string $breakpoint Bootstrap's breakpoints : xs | sm | md |lg
 * @return \phpformbuilder\Form
 */

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 mb-3">
            <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->groupElements('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="bi bi-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 mb-3">
            <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 mb-3">
            <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 mb-3">
            <div class="input-group">
                <div class="input-group-prepend">
                    <span class="input-group-text"><i class="bi bi-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(string $helperText, string $elementName);

addHelper() MUST always be called BEFORE creating the element

/**
 * Shortcut to add element helper text
 *
 * @param string $helperText    The helper text or HTML to add.
 * @param string $elementName   the helper text will be inserted just after the element.
 * @return \phpformbuilder\Form
 */

Example

    $form->addHelper('Enter your last name', 'last-name');
    $form->addInput('text', 'last-name', '', 'Last name', 'required');

Last name ^*

Enter your last name

Add Addon

Adds button or text addon before or after the chosen field

$form->addAddon(string $inputName, string $addonHtml, string $pos);

/**
 * shortcut to prepend or append any adon to an input
 * @param string $inputName the name of target input
 * @param string $addonHtml  addon html code
 * @param string $pos        before | after
 * @return \phpformbuilder\Form
 */

Example

    $addon = '<button class="btn btn-warning" type="button" onclick="document.getElementById(\'input-with-button-after\').value=\'\';">reset</button>';
    $form->addAddon('input-with-button-after', $addon, 'after');
    $form->addInput('text', 'input-with-button-after', '', 'Your name');

Your name

Add Heading

Add a HTML heading tag.

$form->addHeading(string $html, string $tagName = 'h4', string $attr = '')

/**
 * add a HTML heading
 *
 * @param  string $html         the heading content text or HTML
 * @param  string $tagName     (Optional) the heading tag name (h1, h2, ...)
 * @param  string $attr         (Optional) the heading attributes
 * @return void
 */

Example

    $form->addHeading('Please fill the form', 'h5', 'class=text-muted');

Please fill the form

Add Icon

Adds an icon before or after the chosen field

$form->addIcon(string $inputName, string $iconHtml, string $pos);

/**
 * shortcut to prepend or append icon to an input
 *
 * @param string $inputName the name of target input
 * @param string $iconHtml  icon html code
 * @param string $pos        before | after
 * @return \phpformbuilder\Form
 */

Example

    $form->addIcon('username', '<i class="bi bi-person-fill" aria-hidden="true"></i>', 'before');
    $form->addInput('text', 'username', '', 'Name');

Name

buildAlert (static method)

Build an alert div according to the given framework

Form::buildAlert(string $contentText, string $framework, string $type = 'success');

/**
 * build an Alert message according to the framework html
 *
 * @param  string $contentText
 * @param  string $framework     bs4|bs5|bulma|foundation|material|tailwind|uikit
 * @param  string $type  success|primary|info|warning|danger
 * @return string the alert HTML code
 */

Example

    Form::buildAlert('<strong>This is a danger alert example</strong>', 'bs5', 'danger');

This is a danger alert example

startDiv

Start a new HTML DIV Element

$form->startDiv(string $class = '', string $id = '')

/**
 *
 * Start a HTML div element
 * @param string $class
 * @param string $id
 * @return \phpformbuilder\Form
 */

Example

    $form->startDiv('classname', 'div-id');

endDiv

End a HTML div Element

$form->endDiv()

startRow

Start a new HTML row according to the form framework

$form->startRow(string $additionalClass = '', string $id = '')

/**
 * Start a HTML row
 *
 * @param string $additionalClass
 * @param string $id
 * @return \phpformbuilder\Form
 */

Example

    $form->startRow();

Others examples in templates:

Special Offer Sign Up Form
Order Form

endRow

End a row HTML div

$form->endRow()

startCol

Start a new HTML responsive column according to the form framework

$form->startCol(int $colNumber, string $breakpoint = 'sm', string $additionalClass = '', string $id = '')

/**
 * Start a column HTML div
 *
 * @param int $colNumber - the number of columns between 1 and 12
 * @param string $breakpoint - xs, sm, md or lg
 * @param string $additionalClass
 * @param string $id
 * @return \phpformbuilder\Form
 */

Example

    $form->startCol(6);

Others examples in templates:

Special Offer Sign Up Form
Order Form

endCol

End a column HTML div

$form->endCol()

Center Content

Center any field or element horizontally on the page. The centered elements can be displayed on the same line or stacked.

$form->centerContent(bool $center = true, bool $stack = false);

/**
 * @param bool $center
 * @param bool $stack
 * @return \phpformbuilder\Form
 */

Example

    $form->centerContent();
    $form->addBtn('submit', 'submit-btn', 1, 'Submit', 'class=btn btn-success');

Email Sending

sendMail() function

$sentMessage = Form::send($options, $smtpSettings = array());

See details at Email Sending