Statistics
130
1
0
79d
Badges
Tags
latte
Dependencies

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 ITemplateRendererFactory 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\ITemplateRendererFactory $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\ITemplateRendererFactory
        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.
  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.

Bootstrap3Renderer

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

The template supports three rendering modes:

$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)

Rendering mode and template files with custom rendering rules can be set in your config.neon:

formRenderer:
    bootstrap3:
        mode: horizontal
        imports:
            - %appDir%/templates/@form-extras.latte

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.
  • v1.0.1 1.0.1

  • v1.0.0 1.0.0

    • Initial release with TemplateRenderer and Bootstrap3Renderer.

Is this addon outdated? Did you find an issue? Please report it.

Componette Componette admin@componette.com