README

BootstrapFormRenderer is a PHP library that automatically styles Nette Framework forms to look great with Bootstrap CSS. Instead of manually adding Bootstrap classes to each form field, this library handles all the styling for you.

When you build web forms using the Nette Framework, they normally render as plain HTML. This library acts as a renderer that wraps your form fields in the proper Bootstrap markup - adding the right CSS classes, error styling, field grouping, and layout structure that Bootstrap requires.

Key features

Automatic Bootstrap styling - Transforms standard Nette forms into Bootstrap-styled forms without manual HTML markup
Form validation styling - Automatically applies Bootstrap error states and displays validation messages
Flexible layouts - Supports horizontal and other Bootstrap form layouts
Smart field handling - Properly handles different input types (text fields, checkboxes, radio buttons, buttons)
Input add-ons - Supports prepend/append icons or text to form fields (like the @ symbol for email fields)
Translator support - Works with Nette's translation system for multilingual forms
Group support - Handles form field grouping with proper Bootstrap styling

Requirements

PHP 8.3 through 8.5
Nette Framework 3.3
Latte 3.1.4 or newer (Latte 2 is not supported; for Latte 2 use v3.0.x of this library with Nette 3.0 or 3.1)

The integration suite tests both ends of the supported dependency matrix:

PHP	Dependency set	Latte / Application / Forms / Utils / Component model
8.3	lowest	3.1.4 / 3.3.0 / 3.3.0 / 4.1.0 / 3.2.0
8.3 – 8.5	highest Nette 3.3	3.1.x / 3.3.x / 3.3.x / 4.x / 4.x

Getting Started

Use composer to install the library:

composer require jozefizso/bootstrap-form-renderer

Compatibility with Nette Framework

Version	Branch	PHP	compatible	Nette series
`^4.x`.	`main`	`>= 8.3`	`8.5`	Nette 4
`^3.3.0`	`nette-3.3`	`>= 8.3`	`8.5`	Nette 3.3, Latte 3.1
`^3.2.0`	`nette-3.2`	`>= 8.1`	`8.5`	Nette 3.2, Latte 3.0
`^3.0.0`	`nette-3.0`	`>= 7.1`	`8.3`	Nette 3.0, 3.1, Latte 2
`^2.4.0`	`nette-2.4`	`>= 5.6`	`8.0`	Nette 2.4
`^2.3.0`	`nette-2.3`	`>= 5.6`	`7.1`	Nette 2.3
`^2.2.0`	`nette-2.2`	`>= 5.6`	`7.0`	Nette 2.2
`^2.1.0`	`nette-2.1`	`>= 5.6`	`7.0`	Nette 2.1
`^2.0.0`	`nette-2.0`	`>= 5.2`	`5.6`	Nette 2.0

Note: Compatibility always applies to the latest patch release within each minor version series.

Usage

Step 1: Register the Renderer Extension

The easiest way to set up BootstrapFormRenderer is to register the extension in your config.neon configuration file:

extensions:
    twBootstrapRenderer: Kdyby\BootstrapFormRenderer\DI\RendererExtension

The extension will register the Bootstrap2FormFactory to create Bootstrap styled forms and the Latte 3 extension with the tags {form body}, {pair}, {group} and {container}.

Alternative: Register the Latte extension via Nette config

Use configuration files to register only the Latte extension:

latte:
    extensions:
        - Kdyby\BootstrapFormRenderer\Latte\FormsExtension

On a plain Latte engine, add it after the Nette forms extension, whose {form} tag it overrides:

$latte->addExtension(new Nette\Bridges\FormsLatte\FormsExtension);
$latte->addExtension(new Kdyby\BootstrapFormRenderer\Latte\FormsExtension);

Alternative: programmatic bootstrap

If you prefer to register the extension programmatically in app/bootstrap.php:

Kdyby\BootstrapFormRenderer\DI\RendererExtension::register($configurator);

Step 2: Create Bootstrap-Styled Forms

There are three ways to create forms with Bootstrap styling:

Option A: Using Bootstrap2FormFactory (Recommended)

The recommended approach is to use the factory that's automatically registered when you enable the extension:

use Kdyby\BootstrapFormRenderer\Bootstrap2FormFactory;

class RegistrationPresenter extends Nette\Application\UI\Presenter
{
    /** @var Bootstrap2FormFactory @inject */
    public $bootstrap2FormFactory;

    protected function createComponentContactForm()
    {
        // Factory creates Bootstrap2Form instances
        $form = $this->bootstrap2FormFactory->create();

        // Add your form fields as usual
        $form->addText('name', 'Name');
        $form->addText('email', 'E-mail')->setType('email');
        $form->addSubmit('register', 'Register');

        return $form;
    }
}

Option B: Using Bootstrap2Form Class

For simple cases or rapid prototyping, you can directly instantiate the Bootstrap2Form class:

use Kdyby\BootstrapFormRenderer\Bootstrap2Form;

class RegistrationPresenter extends Nette\Application\UI\Presenter
{
    protected function createComponentContactForm()
    {
        // Bootstrap2Form has BootstrapRenderer already configured
        $form = new Bootstrap2Form;

        // Add your form fields as usual
        $form->addText('name', 'Name');
        $form->addText('email', 'E-mail')->setType('email');
        $form->addSubmit('register', 'Register');

        return $form;
    }
}

Option C: Manual Renderer Setup

If you need maximum control or are working with existing code, you can apply the BootstrapRenderer directly:

use Kdyby\BootstrapFormRenderer\BootstrapRenderer;

// In your presenter or form factory method
protected function createComponentContactForm()
{
    $form = new Nette\Application\UI\Form;

    // Apply Bootstrap styling
    $form->setRenderer(new BootstrapRenderer);

    // Add your form fields as usual
    $form->addText('name', 'Name');
    $form->addText('email', 'E-mail')->setType('email');
    $form->addSubmit('send', 'Send');

    return $form;
}

Step 3: Render Your Form in Templates

Now you can use the special tags in your Latte templates to render the form. See the examples below for various rendering options.

Form Rendering Examples

Complete Form Rendering

The simplest way to render a complete form with all Bootstrap styling:

{control contactForm}

In PHP, casting the form to a string returns the complete HTML. Calling $form->render() writes the same HTML to the output stream:

$html = (string) $form;
$form->render();

Partial Form Rendering

For more control over the form layout, you can render individual parts:

Opening and Closing Tags Only

To render just the form's opening <form> and closing </form> tags (without any form body), use the self-closing syntax:

{form contactForm /}

This is equivalent to:

{form contactForm}{/form}

Both render only the begin and end tags (plus unrendered hidden fields). Use this when you want to manually render form content or integrate with other components.

Opening Tag with Custom Content

{form contactForm}
    {* Your custom content here *}
{/form}

Form Errors

Renders validation errors that aren't associated with specific fields (like form-level errors):

{form errors}

Form Body

Renders all form controls and groups that haven't been rendered yet:

{form body}

Controls Only

Renders all input controls (excluding buttons):

{form controls}

Buttons Only

Renders all submit and button controls:

{form buttons}

Complete Custom Layout Example

{form contactForm}
    {form errors}

    <div class="row">
        <div class="col-md-6">
            {pair name}
            {pair email}
        </div>
        <div class="col-md-6">
            {pair message}
        </div>
    </div>

    {form buttons}
{/form}

Rendering Individual Form Components

Single Control

Renders a complete control with its label, input field, and validation messages:

{pair name}

Or using the verbose syntax:

{$form->render($form['name'])}

Container

Renders all controls within a container:

{container personalInfo}

Group

Renders a form group with its fieldset, legend, and all controls:

{group "Personal Information"}

Validation Errors Rendering

The renderer provides control over how validation errors are displayed through the $errorsAtInputs property:

Default Behavior (errorsAtInputs = TRUE)

By default, the renderer distinguishes between form-level and control-level errors:

Form-level errors (added with $form->addError()) appear in Bootstrap alert boxes at the top of the form
Control errors (added with $control->addError()) appear inline next to their inputs with the help-inline class

$form->setRenderer(new BootstrapRenderer());
// errorsAtInputs = TRUE by default

This prevents duplicate error messages and provides better UX by showing each error in the most appropriate location.

Show All Errors in Alerts (errorsAtInputs = FALSE)

If you prefer to display all errors (both form-level and control errors) in alert boxes without inline errors:

$renderer = new BootstrapRenderer();
$renderer->errorsAtInputs = FALSE;
$form->setRenderer($renderer);

With this setting:

All errors appear in Bootstrap alert boxes at the top
No inline error messages are displayed next to inputs
The control groups still receive the error CSS class for styling

Translation Behavior

BootstrapFormRenderer works seamlessly with Nette 2.2's built-in translation system. When you set a translator on your form using $form->setTranslator($translator), almost everything is automatically translated—you don't need to manually translate individual elements.

What Gets Translated Automatically

Nette 2.2 automatically translates:

Control labels and captions
Placeholders on text inputs and textareas
Validation rule messages (both default and custom)
Select options, radio button labels, and checkbox labels

BootstrapFormRenderer translates:

Form group labels and descriptions
Control descriptions (the description option)

Important Guidelines

Manual errors - If you add errors manually using $form->addError() or $control->addError() with plain strings, translate them yourself before calling addError(). Rule-generated errors are translated automatically.

Pre-rendered HTML - Use Nette\Utils\Html for content that shouldn't be translated:

$htmlError = Html::el('strong')->setText('Already exists');
$form['username']->addError($htmlError); // Not translated

Latte Variable Conventions

{form name} resolves the form as a component of the current control:

uiControl Latte provider - Registered by Nette application templates ($control in the template); used for form lookup
$form - The current form inside {form}...{/form} blocks

{form $form} also accepts a Nette\Forms\Form instance directly.

Template Requirements

Presenter and control templates created by Nette's TemplateFactory need no configuration. When rendering a template on a plain Latte engine, register the owning component with $latte->addProvider('uiControl', $control); the $_control template variable is no longer used.

Custom group and control templates

Templates set with the template option of a group or control should be absolute paths (for example __DIR__ . '/control.latte'). Latte 3 resolves other names, including stream-wrapper URLs such as mock://…, relative to the renderer's internal template.

License

You may use BootstrapFormRenderer library under the terms of either the New BSD License or the GNU General Public License (GPL) version 2 or 3.

Read LICENSE for more information.

Forked from the original Kdyby/BootstrapFormRenderer by Filip Procházka.

jozefizso / bootstrap-form-renderer

Package info

Security

Statistics