netzmacht / contao-form-helper
Library for supporting customized Contao form rendering
Installs: 8 434
Dependents: 1
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 0
Type:contao-bundle
Requires
- php: >=5.3
- contao-community-alliance/dependency-container: ~1.0
- contao-community-alliance/event-dispatcher: ~1.0
- contao/core: >=3.1,<3.6-dev
- netzmacht/html: ~1.0
Requires (Dev)
This package is auto-updated.
Last update: 2020-04-06 10:38:14 UTC
README
This library provides extended form widget rendering for Contao frontend form widgets. By default the rendering of Contao forms widgets are not very customizable because of inline html rendering. Adjust output can be quite difficult.
Contao Form Helper provides an event driven form rendering which is fully backward compatible. This means that it supports the html output usually provided by Contao. Also every widgets from extension will work without any customizing.
Contao Form Helper renders the form in two steps. First it creates objects representing the HTML elements before passing them to the templates. Using the event driven interface it is possible to simply change attributes, provide extra features and so on.
Installation
To install the extension simply install netzmacht/contao-form-helper
using the
Composer repository.
Changelog
Changes between 0.x version and 1.x
- Change namespace of
Netzmacht\FormHelper
toNetzmacht\Contao\FormHelper
- Using a view object which is created instead of return an array of elements
- Simplify events (no select message event anymore)
- Introduce an attributes object for
- Drop supporting form messages handling
How it works
By default this extension enables the extended form rendering for every form widget which is shipped with Contao. They are activated by customized form templates.
The helper creates a view object for each widget. The view contains:
- Attributes which can be used for a wrapper
<div>
- The form label
- Container including the element and by default the extra submit button
- Error messages
- Using a layout which is used to render
<?php // form_widget.html5 // shortcut Netzmacht\Contao\FormHelper\Helper::generate($this); // what actually happens $helper = Netzmacht\Contao\FormHelper\Helper::getInstance(); /** @var Netzmacht\Contao\FromHelper\View */ $view = $helper->createView($view); echo $view->render();
Events
Events are dispatched by the (Contao Event dispatcher)[https://github.com/contao-community-alliance/event-dispatcher].
Each event names are stored in Netzmacht\Contao\FormHelper\Event\Events
:
Events::CREATE_VIEW
is triggered first to create the view instance. The element is not available at this momentEvents::CREATE_ELEMENT
is fired when creating the html element of the given widgetEvents::PRE_GENERATE_VIEW
is fired after creating the elementEvents::GENERATE_VIEW
is fired for generating the
Customizing widgets
There are two ways for manipulating the output. The proposed way is writing your custom events
<?php // config.php $GLOBALS['TL_EVENTS'][Netzmacht\Contao\FormHelper\Event\Events::GENERATE_VIEW][] = function(Netzmacht\Contao\FormHelper\Event\ViewEvent $event) { // access Contao widget and form $form = $event->getFormModel(); $widget = $event->getWidget(); // adjust element $container = $event->getContainer(); $element = $container->getElement(); // adjust rows if($form->id == 9 && $widget->type == 'textarea') { $element->setAttribute('rows', 50); } }
You can also adjust the rendering using the templates:
<?php // form_widget.html5 $helper = Netzmacht\Contao\FormHelper\Helper::getInstance(); /** @var Netzmacht\Contao\FromHelper\View */ $view = $helper->createView($view); $errors = $view->getErrors(); // display all errors which belongs to an element $errors->setTemplateName('formhelper_error_all'); // wrapping element can be a string with %s placeholder or an Netzmacht\Html\Node object $wrapper = '<div class="form-element">%s</div>'; $container = $view->getContainer(); $container->add('wrapper', $wrapper, $container::POSITION_WRAPPER); echo $view->render();