DluTwBootstrap updated to ZF2 RC3

2012-08-10 · by dlu · in

DluTwBootstrap – the Zend Framework 2 module for generating Twitter Bootstrap UI (forms) has been updated to Zend Framework 2 RC3.

About

DluTwBootstrap is a Zend Framework 2 module consisting primarily of view helpers, which let you easily generate Twitter Bootstrap UI forms from your standard Zend Framework 2 Form objects without getting your hands dirty with Twitter Bootstrap mark-up.

Reworked from scratch

The module has been updated to reflect the changes in Zend Framework 2 RC3. There are numerous BC breaks, so please refactor your projects. The Zend Framework 2 API should be changing much less now as we are approaching the stable release, so the DluTwBootstrap module should be now also more stable and should not be that picky about the ZF2 version.

Yes, the much asked for echo $form; is here (well, not exactly that but a one-liner nonetheless).

The module has been not only updated to the latest ZF2 release, but also reworked from gound up so it is much cleaner and consistent now.

First go to on-line demo

As always, you should first visit the on-line demo here:

http://apps.zfdaily.com/dlutwbootstrap-demo

The on-line demo shows everything the module can do side-by-side with the source used to produce the demo output. The demo application is your primary reference.

Components

  • DluTwBootstrap module – a ZF2 module containing view helpers, classes and styles which enable your applications to render Twitter Bootstrap UI (forms).
  • DluTwBootstrap Demo module – a ZF2 module demonstrating capabilities of the DluTwBootstrap module. Install and enable this module in your app to check that you have installed DluTwBootstrap correctly.
  • DluTwBootstrap Demo Application (on-line) – a simple ZF2 application integrating both the modules. You should not need the app’s source, but it’s here for your reference.

Installation

The installation steps are described in README.md files in the root of each package. Go to the respective repositories mentioned above to review them.

Usage

First of all: Yes, the much asked for echo $form; is here (well, not exactly that but a one-liner nonetheless). Although Zend Framework 2 itself does not support form display with a single command I decided to implement this feature with the following disclaimer:

The one-liner should be used only either for a quick form preview or in situations when there are no special requirements for form presentation. If you need anything else, use the manually controlled form output DluTwBootstrap offers.

So you can have it both ways. Either a dead simple fully automated form display on one line or a more laborous fully controlled form output. Your call.

The simplest case
  1. Create a standard Zend\Form\Form object
  2. Pass your form object to view
  3. Prepare your form: $form->prepare();
  4. Output the form: echo $this->formTwb($form);

This procedure would output a horizontal Twitter Bootstrap form. The horizontal form type is considered default in DluTwBootstrap. Pass second argument to the formTwb() helper to control which form type will be displayed. Use the provided constants:

echo $this->formTwb($form, \DluTwBootstrap\Form\FormUtil::FORM_TYPE_VERTICAL);

There is also the third optional parameter to formTwb() which contains the display options. You can use it to change the most common display aspects of the form (e.g. the size of input fields) and still use the simple one line form output. The display options also control which fields will be marked as required (more on that later). Please go to the on-line demo to see how the $displayOptions parameter is used.

The not so simple case

If you need more control over your form presentation, your best friend is the formRowTwb() view helper. It’s used like this:

echo $this->formTwb()->openTag($form, $formType);
echo $this->formRowTwb($form->get('myElement'), $formType, $elementDisplayOptions);
echo $this->formTwb()->closeTag();

This sequence of commands would output a single form element together with label, hint, description, possible validation errors and any required Twitter Bootstrap mark-up. The formRowTwb() helper can render any supported form element (inputs, checkboxes, buttons, etc.).

This is the optimal level of control. You can insert anything special between form elements yet you still do not have to think about Twitter Bootstrap markup. Just output any number of formRowTwb() interspersed with your custom display code, wrap everything in opening/closing tags and you are done.

As for the level of control, you can go in both directions from here. You can output whole fieldsets using

echo $this->formFieldsetTwb($fieldset, $formType, $fieldsetDisplayOptions);

or you can dig deeper and manually control the individual parts of the formRow using the appropriate view helpers for label, element, description, errors, etc. In this case though you are the one who is responsible for proper Twitter Bootstrap mark-up and your forms may not render correctly if you mess things up.

What is obvious

DluTwBootstrap module mimicks the original Zend Framework view helpers where possible. If there is the formRow() view helper in ZF2, DluTwBootstrap has formRowTwb(). Just add Twb suffix.

What is not so obvious

There are two DluTwBootstrap view helpers you should know about which do not have a ZF2 counter part: formFieldsetTwb() which we’ve already talked about (outputs whole fieldsets) and formActionsTwb(). The formActionsTwb() view helper outputs form buttons with correct Twitter Bootstrap mark-up around. See the on-line demo for details.

DluTwBootstrap can optionally highlight required fields. This is something you won’t find in Twitter Bootstrap itself, but I think it’s useful to indicate to the user which fields are mandatory. (I do not want to start a philosophical debate on this, although your opinion is welcome. This feature is optional, so if you think form fields should be never visually marked as required, just ignore it.)

If you want to visually mark a field as required, use the $displayOptions array parameter and set 'required' => true. (See the on-line demo for details.) There are three places where you can specify the element as ‘required’. Their meaning differs though:

  • ‘required’ attribute of the element object – just adds the HTML5 ‘required’ attribute to the tag. Makes the form/element semantically correct.
  • ‘required’ option of the input filter – forces the user to actually fill out the field otherwise the form won’t validate
  • ‘required’ option of the DluTwBootstrap display options – visually marks the element as required/mandatory

Supported elements

All basic elements are supported by DluTwBootstrap. The TODO list contains all HTML5 elements (date, color, etc.), captcha, image and collections. If you need any of them on your form now, you can add markup for them manually in your view script.

DluTwBootstrap benefits

There are two important aspects worth noting: DluTwBootstrap does not force you into a specific form output mode. You can select the required level of control as you wish from fully automated output in one line of code to fully controlled output of the individual atomic form parts. You can also combine these two aproaches at will.

The other strong point of DluTwBootstrap is its clean separation of presentation specifics from the form definition. The form definition (i.e. the form object) contains no information used solely to control output of Twitter Bootstrap markup (e.g. a Twitter Bootstrap CSS class). The user controllable Twitter Bootstrap specifics are contained in the $displayOptions parameter optionaly passed to the Twb view helpers. If you decide to abandon Twitter Bootstrap and use another CSS template system, your form objects are perfectly ok, do not contain any Twitter Bootstrap specific artifacts and do not need any refactoring. Your changes would be kept exclusively inside your view scripts.

BC breaks

There are too many BC to mention them individually. The view helpers are renamed and removed, the parameters changed, the form objects should be defined as per ZF2 RC3 API (which is different – e.g. options instead of attributes), etc. Please check the on-line demo, review the demo form output and examine the source. DluTwBootstrap is easy to use and the best way to learn it is by example.

Links

Tags: , , , ,