Componette

Componette

nepada

nepada / form-renderer v1.12.0

Latte template based form renderer for Nette forms with full support for Bootstrap 3, 4 & 5.

download-cloud-line composer require nepada/form-renderer

Form Renderer

Build Status Coverage Status Downloads this Month Latest stable

Installation

Via Composer:

$ composer require nepada/form-renderer

Register the extension in config.neon:

extensions:
    formRenderer: Nepada\Bridges\FormRendererDI\FormRendererExtension

Usage

Nette gives you two options how to render a form:

  1. Render the whole form manually in Latte template using form macros. This way you have complete control over the rendering, but writing all the templates quickly gets repetitive.
  2. Render it using a form renderer, e.g. DefaultFormRenderer from nette/forms. DefaultFormRenderer is very customizable, but it's hard to setup special rendering rules for only some controls of a form, or add support for rendering of new form control types.

nepada/form-renderer is built on top of Latte templates and their powerful blocks, thus combining strengths of manual rendering with DRY principle of form renderers.

TemplateRenderer

You can use TemplateRendererFactory service to create the renderer with preconfigured default template. It renders a form more or less the same way as DefaultFormRenderer.

Customizing rendering

You can customize rendering by importing blocks from a template file - blocks imported later override the previously imported ones of the same name. You can also pass custom variables to the template.

/** @var Nepada\FormRenderer\TemplateRendererFactory $factory */
$renderer = $factory->create();
$renderer->importTemplate(__DIR__ . '/custom-form-rendering-blocks.latte');
$renderer->getTemlate()->foo = 'bar'; 
$form->setRenderer($renderer);

Tips:

  • You can define special rendering for a specific control of a form in #control-name-* block (e.g. #control-name-container-subcontainer-foocontrol).
  • If you need special rendering for both a control and its label, define it in #pair-name-* block.
  • Rendering of different control types (based on the value of $control->getOption('type')) is controlled by blocks #control-type-* and #pair-type-*. The default template actually uses this for buttons (rendering of consecutive buttons in one row).
  • You can also specify template files to be imported in your config.neon:
    formRenderer:
        default:
            imports:
                - %appDir%/templates/@form-extras1.latte
                - %appDir%/templates/@form-extras2.latte

For a complete overview of supported blocks and better understanding how the renderer works, please read the code of the template.

Creating custom TemplateRenderer setup from scratch

You don't need to use the default template, you can create one from scratch with blocks tailored to your needs. You can define factory for your custom setup like this:

services:
    customRenderer:
        implement: Nepada\FormRenderer\TemplateRendererFactory
        setup:
          - importTemplate('%appDir%/templates/@form.latte')
          - importTemplate('%appDir%/templates/@form-extras.latte')

Just make sure that one of your template files defines block named #form - this is used as a starting point for the rendering.

Filter safeTranslate in templates

For translations the templates may use custom safeTranslate filter. The key differences from standard translate filter are:

  1. It avoids translating instances of Nette\Utils\IHtmlString and Latte\Runtime\IHtmlString.
  2. It uses a translator from the form instance that is being rendered.
  3. If the form has no translator set, than it simply returns the passed string untranslated.

Improved version of n:class macro

In all form templates there is also available an improved version of n:class macro that supports merging of classes from Nette\Utils\Html instances. You can do stuff like <input n:name="$control" n:class="$control->controlPrototype->class, form-control"> and don't need to worry if the class attribute is really represented as a string or array, it all just works.

Bootstrap5Renderer

Form renderer compatible with Bootstrap 5, it internally uses TemplateRenderer with custom template.

The template supports three rendering modes:

/** @var Nepada\FormRenderer\Bootstrap5RendererFactory $factory */
$renderer = $factory->create();
$renderer->setBasicMode(); // Basic form
$renderer->setInlineMode(); // Inline form
$renderer->setHorizontalMode(4, 8); // Horizontal form (you can optionally set the size of label and control columns)

Use $renderer->setRenderValidState(true) to enable/disable rendering of "valid" form control state for filled inputs after form submission.

In inline mode the error messages are always rendered as tooltips. In the other modes you can switch between standard and tooltip rendering by calling $renderer->setUseErrorTooltips(true).

You can enable floating labels by $renderer->setUseFloatingLabels(true) (ignored in horizontal mode only). By default, all controls of text, datetime, textarea and select type are rendered with floating label, but you can manually override this on a specific control by setting $input->setOption('floatingLabel', false).

To render a checkbox as a switch, you need to set type option: $checkboxInput->setOption('type', 'switch').

To render radio or checkbox as a toggle button, add btn class (and any desired button styling class) to label prototype: $radio->getItemLabelPrototype()->addClass('btn btn-outline-primary').

Bootstrap5Renderer makes a couple of adjustments to the form before it is passed over to TemplateRenderer:

  1. It adds btn btn-primary classes to the control prototype of first SubmitButton in the form, unless there already is such a control in the form.
  2. It adds btn btn-secondary classes to the control prototype of every Button control, unless it already has btn class set.
  3. Changes type option on all Checkbox, CheckboxList, RadioList controls setup to be rendered as toggle buttons from checkbox/radio to togglebutton/togglebuttonlist.
  4. Changes type option on all CheckboxList controls from checkbox to checkboxlist.
  5. When floating labels are enabled, it sets boolean floatingLabel option (unless already set) on all controls to indicate whether the floating label should be rendered.

You can change the default renderer configuration from your config.neon:

formRenderer:
  bootstrap5:
    mode: horizontal
    renderValidState: true
    useErrorTooltips: true
    imports:
      - %appDir%/templates/@form-extras.latte

Bootstrap4Renderer

Form renderer compatible with Bootstrap 4, it internally uses TemplateRenderer with custom template.

The template supports three rendering modes:

/** @var Nepada\FormRenderer\Bootstrap4RendererFactory $factory */
$renderer = $factory->create();
$renderer->setBasicMode(); // Basic form
$renderer->setInlineMode(); // Inline form
$renderer->setHorizontalMode(4, 8); // Horizontal form (you can optionally set the size of label and control columns)

Use $renderer->setRenderValidState(true) to enable/disable rendering of "valid" form control state for filled inputs after form submission.

In inline mode the error messages are always rendered as tooltips. In the other modes you can switch between standard and tooltip rendering by calling $renderer->setUseErrorTooltips(true).

You can enable the use of custom form controls by $renderer->setUseCustomControls(true).

To render a checkbox as a switch, you need to set type option: $checkboxInput->setOption('type', 'switch').

Bootstrap4Renderer makes a couple of adjustments to the form before it is passed over to TemplateRenderer:

  1. It adds btn btn-primary classes to the control prototype of first SubmitButton in the form, unless there already is such a control in the form.
  2. It adds btn btn-secondary classes to the control prototype of every Button control, unless it already has btn class set.
  3. Changes type option on all CheckboxList controls from checkbox to checkboxlist.

You can change the default renderer configuration from your config.neon:

formRenderer:
    bootstrap4:
        mode: horizontal
        renderValidState: true
        useErrorTooltips: true
        useCustomControls: true
        imports:
            - %appDir%/templates/@form-extras.latte

Bootstrap3Renderer

Form renderer compatible with Bootstrap 3, it internally uses TemplateRenderer with custom template.

The template supports three rendering modes:

/** @var Nepada\FormRenderer\Bootstrap3RendererFactory $factory */
$renderer = $factory->create();
$renderer->setBasicMode(); // Basic form
$renderer->setInlineMode(); // Inline form
$renderer->setHorizontalMode(4, 8); // Horizontal form (you can optionally set the size of label and control columns)

Use $renderer->setRenderValidState(true) to enable/disable rendering of "valid" form control state for filled inputs after form submission.

Bootstrap3Renderer makes a couple of adjustments to the form before it is passed over to TemplateRenderer:

  1. It adds btn btn-primary classes to the control prototype of first SubmitButton in the form, unless there already is such a control in the form.
  2. It adds btn btn-default classes to the control prototype of every Button control, unless it already has btn class set.
  3. Changes type option on all CheckboxList controls from checkbox to checkboxlist.

You can change the default renderer configuration from your config.neon:

formRenderer:
    bootstrap3:
        mode: horizontal
        renderValidState: true
        imports:
            - %appDir%/templates/@form-extras.latte
  • v1.12.0 1.12.0

    • Bootstrap 3-4 renderer: render new Nette datetime input the same way as other text inputs
    • Added new Bootstrap 5 renderer
      • Initial implementation thanks @martenb
      • Color input rendering supported
      • Toggle Buttons rendering supported
      • Floating labels supported in basic and inline mode
  • v1.12.0-rc2 1.12.0 RC2

    • Bootstrap 3-4 renderer: render new Nette datetime input the same way as other text inputs
    • Added new Bootstrap 5 renderer
      • Initial implementation thanks @martenb
      • Color input rendering supported
      • Toggle Buttons rendering supported
      • Floating labels supported in basic mode

    Changes since RC1

    • Bootstrap 5: floating labels refactored to allow opt in/out of rendering via form control option
    • Bootstrap 5: floating labels are now allowed in inline mode
    • Bootstrap 5: remove invalid placeholder attribute from <select> with floating labels
    • Bootstrap 5: remove extra bottom margin from checkboxes & radios in inline mode
  • v1.12.0-rc1 1.12.0 RC1

    • Bootstrap 3-4 renderer: render new Nette datetime input the same way as other text inputs
    • Added new Bootstrap 5 renderer
      • Initial implementation thanks @martenb
      • Color input rendering supported
      • Toggle Buttons rendering supported
      • Floating labels supported in basic mode
  • v1.12.0-beta1 1.12.0 beta1

    • New Bootstrap 5 renderer (thanks @martenb)
  • v1.11.1 1.11.1

    • Bootstrap 4: Fix vertical alignment of Range control
    • Preliminary support for nette/forms 3.2.x
      • Replace deprecated usage of getOption()
      • Add generics annotations for BaseControl and Control
  • v1.11.0 1.11.0

    • Drop support for PHP <8.1
    • Drop support for Latte 2.x
    • Use PHP8 native typehints
    • Drop useless annotations
    • PHP 8.3 compatibility
  • v1.10.3 1.10.3

    • Latte strict mode support (thanks @Gappa)
  • v1.10.2 1.10.2

    • Support nette/utils 4
  • v1.10.1 1.10.1

    • PHP 8.2 compatibility
  • v1.10.0 1.10.0

    • Latte 3.x compatibility
  • v1.9.0 1.9.0

    • Drop support for Latte <2.9
    • Latte 2.11 support
    • Replace deprecated Nette & Latte symbols (e.g. renamed interfaces)
  • v1.8.0 1.8.0

    • PHP 8.1 compatibility.
  • v1.7.0 1.7.0

    • PHP 8.0 compatiblity.
    • Requires Latte 2.6 or greater.
  • v1.6.1 1.6.1

    • validationClass helper: password input is always considered not filled
  • v1.6.0 1.6.0

    • Bootstrap 4:
      • Add support for rendering error messages as tooltips in basic and horizontal mode.
      • Add opt-in support for rendering "valid" state of form controls (it is rendered for correctly filled controls after form submission).
      • Add validationClass helper latte filter for selecting appropriate validation class.
      • Error messages are displayed via d-block class instead of relying on sibling validation state selector.
      • Fix rendering of multiple error messages in tooltip - messages are now merged into one tooltip.
    • Bootstrap 3:
      • Add opt-in support for rendering "valid" state of form controls (it is rendered for correctly filled controls after form submission).
      • Add validationClass helper latte filter for selecting appropriate validation class.
    • Fix: do not translate error messages (they are already translated in Nette 3).
  • v1.5.1 1.5.1

    • Dropped interface prefix:
      • Nepada\FormRenderer\IBootstrap3RendererFactory is deprecated, use Nepada\FormRenderer\Bootstrap3RendererFactory instead
      • Nepada\FormRenderer\IBootstrap4RendererFactory is deprecated, use Nepada\FormRenderer\Bootstrap4RendererFactory instead
      • Nepada\FormRenderer\ITemplateRendererFactory is deprecated, use Nepada\FormRenderer\TemplateRendererFactory instead
  • v1.5.0 1.5.0

    • Added support for Bootstrap 4 via Bootstrap4Renderer.
  • v1.4.1 1.4.1

    • FormRendererExtension: fix default imports for bootstrap 3 renderer
    • safeTranslate filter now correctly treats HTML strings from Latte, i.e. Nette\Utils\IHtmlString and Latte\Runtime\IHtmlString are handled the same way.
  • v1.3.1 1.3.1

    • FormRendererExtension: fix default imports for bootstrap 3 renderer
  • v1.2.1 1.2.1

    • FormRendererExtension: fix default imports for bootstrap 3 renderer
  • v1.4.0 1.4.0

    • Requires PHP >=7.4.
    • Uses native property typehints.
  • v1.3.0 1.3.0

    • Requires PHP >=7.2.
    • PHP 7.4 compatibility.
    • FormRendererMacros marked final (possible BC break).
  • v1.2.0 1.2.0

    • Requires Latte 2.5 and Nette 3.0 (Nette 2.4 support was dropped).
  • v1.1.0 1.1.0

    • Nette 3 support.
  • v1.0.4 1.0.4

    • CI improvements.
  • v1.0.3 1.0.3

    • Refactored exception hierarchy (use standard exceptions instead of custom InvalidStateException).
  • v1.0.2 1.0.2

    • Code style improvements.
  • v1.0.1 1.0.1

  • v1.0.0 1.0.0

    • Initial release with TemplateRenderer and Bootstrap3Renderer.
bar-chart-fill

Statistics

download-cloud-fill
117169
star-fill
10
bug-fill
0
flashlight-fill
28d
price-tag-2-line

Badges

guide-fill

Dependencies

php (>=7.1.0)
nette/utils (^2.4@dev || ^3.0@dev)
nette/forms (^2.4.6@dev || ^3.0@dev)
nette/application (^2.4@dev || ^3.0@dev)
latte/latte (^2.4.1@dev)
Componette Componette felix@nette.org