README

Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

Nette extension for Bootstrap forms.

Versions

State	Version	Branch	Nette	PHP	Bootstrap
dev	`^0.9`	`master`	3.3+	`^8.3`	`4.x` `5.x`
stable	`^0.8`	`master`	3.0+	`^8.1`	`4.x` `5.x`
stable	`^0.7`	`master`	3.0+	`^8.1`	`4.x` `5.x`
stable	`^0.6`	`master`	3.0+	`^8.1`	`4.x` `5.x`
stable	`^0.5`	`master`	3.0+	`>=7.2`	`4.x` `5.x`
stable	`^0.4`	`master`	3.0+	`^7.2`	`4.x`
stable	`^0.3`	`master`	3.0+	`^7.2`	`4.x`
stable	`^0.2`	`master`	3.0+	`^7.2`	`4.x`
stable	`^0.1`	`master`	3.0+	`^7.2`	`4.x`

Installation

The best way is via composer:

composer require contributte/forms-bootstrap

Note that if you simply clone the main branch from this repo, it is not guaranteed to work, use releases instead

Requirements

Works with Nette\Application\UI\Form, not Nette\Forms\Form, so you need the whole Nette framework.
PHP version according to the supported package version, see Versions.
Client-side Bootstrap 4 or 5 stylesheets and JavaScript.

Compatibility

This package is compatible with Bootstrap 4 and 5.

Examples

See example on CodePen

Features

Bootstrap 5 forms HTML generation
Bootstrap 4 forms HTML generation
All layout modes: vertical, side-by-side and inline
TextInput placeholders
Highly configurable renderer
Bootstrap custom forms
Date(Time) picker, variety of human readable date/time formats, placeholder example generation
Validation styles
Programmatically generated Bootstrap grid
Assisted manual rendering
BootstrapForm::$allwaysUseNullable (legacy spelling) to set all fields as nullable (calls $component->setNullable() for all fields automatically)

Usage

Form

Probably the main class you will be using is Contributte\FormsBootstrap\BootstrapForm. It has all the features of this library pre-configured and extends Nette\Application\UI\Form functionality by:

Only accepts Contributte\FormsBootstrap\BootstrapRenderer or its children (which is default)
Built-in AJAX support (adds ajax class upon rendering) via ajax(bool) property
Has direct access to render mode property of renderer (property renderMode)
All add* methods are overridden by bootstrap-enabled controls

$form = new BootstrapForm;
$form->renderMode = RenderMode::VERTICAL_MODE;

It will behave pretty much the same as the default Nette form, with the exception of not grouping buttons. That feature would only add unnecessary and deceiving overhead to this library, use grid instead, it will give you much finer control

Render modes

Vertical (Enums\RenderMode::VERTICAL_MODE) all controls are below their labels
Side-by-side (Enums\RenderMode::SIDE_BY_SIDE_MODE) controls have their labels on the left. It is made up using Bootstrap grid. The default layout is 3 columns for labels and 9 for controls. This can be altered using BootstrapRenderer::setColumns($label, $input).
Inline Enums\RenderMode::INLINE all controls and labels will be in one enormous line

Bootstrap versions support

^4 (Enums\BootstrapVersion::V4) version 4 mode (default)
^5 (Enums\BootstrapVersion::V5) version 5 mode

BootstrapForm::switchBootstrapVersion(Enums\BootstrapVersion::V5)
$form = new BootstrapForm;

Controls / inputs

Each default control has been extended by bootstrap-enabled controls and will render itself correctly even without the renderer. You can distinguish them easily - they all have Input suffix.

TextInput

TextInput can have placeholder set ($input->setPlaceholder($val)). All text-based inputs (except for TextArea) inherit from this control.

DateTimeInput

Its format can be set ($input->setFormat($str)), the default is d.m.yyyy h:mm (though you must specify it in standard PHP format!).

You may use DateTimeFormats class constants as a list of pretty much all formats:

DateTimeFormat::D_DMY_DOTS_NO_LEAD

is the default format for Date and

DateTimeFormat::D_DMY_DOTS_NO_LEAD . ' ' . DateTimeFormat::T_24_NO_LEAD

is the default format for DateTime. You can also change this globally with

DateInput::$defaultFormat = DateTimeFormat::D_DMY_DOTS_NO_LEAD;
DateTimeInput::$defaultFormat = DateTimeFormat::D_DMY_DOTS_NO_LEAD . ' ' . DateTimeFormat::T_24_NO_LEAD;

If you want to add HTML classes for those elements so they can be connected with a JavaScript date(time) picker, use:

DateInput::$additionalHtmlClasses = 'datepicker';
DateTimeInput:$additionalHtmlClasses = 'datetimepicker';

See PhpDoc for further explanation.

UploadInput

Nothing out of the ordinary, but it needs the <html lang="xx"> attribute to work.

Has property buttonCaption, which sets the text on the button on the left. The right button is set by Bootstrap CSS, which depends on <html lang="xx">.

Renderer

The renderer is enhanced by the following API:

property	type	meaning
mode	int constant	see render mode above in form section
gridBreakPoint	string / null	Bootstrap grid breakpoint for side-by-side view. Default is 'sm'
groupHidden	bool	if true, hidden fields will be grouped at the end. If false, hidden fields are placed where they were added. Default is true.

Grid

The library provides a way to programmatically place controls into Bootstrap grid and thus greatly reduces the need for manual rendering.

Simply add a new row like this:

$row = $form->addRow();
$row->addCell(6)
	->addText('firstname', 'First name');
$row->addCell(6)
	->addText('surname', 'Surname');

And firstname and surname will be beside each other.

Notes

By calling getElementPrototype() on row or cell, you can influence the elements of row / cell
A cell can only hold one control (or none)
You are not limited to numerical column specification. Also check out \Contributte\FormsBootstrap\Grid\BootstrapCell::COLUMNS_NONE and \Contributte\FormsBootstrap\Grid\BootstrapCell::COLUMNS_AUTO

Assisted manual rendering

Why do we use manual rendering? Mostly to just rearrange the inputs, we rarely create a completely different feel. But there is a hefty price for using manual rendering - we have to do almost everything ourselves, even the things the renderer could do for us. Only if there were a way to let the renderer do most of the work...

Assisted rendering capabilities

Assisted manual rendering will render label-input pairs for you using a filter. This means that it will take care of wrapping things into div.form-group and validation messages - the most mundane thing to implement in a template.

Implementation

First of all, you must implement this yourself, this won't work out of the box! The implementation is quite dirty, but I think the benefits outweigh this cost.

It works like this:

1. Implement a filter

add a new filter to your latte engine, for example:

$this->template->addFilter('formPair', function ($control) {
	/** @var BootstrapRenderer $renderer */
	$renderer = $control->form->renderer;
	$renderer->attachForm($control->form);

	return $renderer->renderPair($control);
});

2. Use it

{$form['firstname']|formPair|noescape}

That will result in

<div class="form-group row">
    <label for="frm-form-firstname" class="col-sm-3">First name</label>

    <div class="col-sm-9">
        <input type="text" name="firstname" id="frm-form-firstname" class="form-control">
    </div>
</div>

Development

See how to contribute to this package.

This package is currently maintaining by these authors.

Based on abandoned czubehead package bootstrap-4-forms

Consider to support contributte development team. Also thank you for using this package.

contributte / forms-bootstrap

Maintainers

Package info

Fund package maintenance!

Statistics

Security