Twitter Bootstrap Forms with ZF2. Easily.

Twitter Bootstrap Forms with ZF2. Easily.

Twitter Bootstrap contains pretty much everything you might need in a web app UI (and more). Its forms are nice and clean so why not use them with ZF2? I wrote a module DluTwBootstrap to make the process dead easy.

UPDATE 1: ZF2 Beta 4 contains a completely rewritten Form package. The Beta 3 form decorators in DluTwBootstrap module described in this post are obsolete and do not work in Beta 4. Please stay tuned for a new version of the DluTwBootstrap module which will support ZF2 Beta 4 as well as more Twitter Bootstrap features (navigation).
UPDATE 2: The DluTwBootstrap module has been updated to Zend Framework 2 Beta 4. Please see this post for more info.
UPDATE 3: The DluTwBootstrap module has been updated to Zend Framework 2 RC3. Please see DluTwBootstrap updated to ZF2 RC3 for more info.

DluTwBootstrap supports almost everything Twitter Bootstrap offers for forms.

Wait! Do not reinvent the wheel

Before I set out to write my own module I first looked for an available one and indeed there were two. Unfortunately neither of them suited my needs. But maybe they will be a better fit for you so here are the links:

DluTwBootstrap — what can it do for you?

DluTwBootstrap supports almost everything Twitter Bootstrap offers for forms.

Form types

All four Twitter Bootstrap form types are supported:

  • Horizontal
  • Vertical
  • Inline
  • Search
Controls

All ZF2 form elements except Captcha and Image are supported:

  • Button
  • Checkbox
  • File
  • Hash
  • Hidden
  • MultiCheckbox
  • Multiselect
  • Password
  • Radio
  • Reset
  • Select
  • Submit
  • Text
  • Textarea
Element descriptions

Various descriptive and help texts are supported depending on the type of the element:

  • Label
  • Description
  • Inline help
  • Placeholder text

Error state and required elements

Elements with validation errors are rendered in red and the validation errors are clearly visible.

The required elements stand out.

Extras

The MultiCheckbox and Radio elements can be optionally rendered inline.

The Text element can optionally have a prepended or appended pieces of text.

If the form has a legend set, it is displayed as a form heading.

Get, install, check

First you need to get the DluTwBootstrap module, install it in your ZF2 application and check the demo page to see that everything is working correctly.

Please see the repository overview page with detailed installation instructions.

Twitter Bootstrap libraries

Enabling the DluTwBootstrap module in your ./config/application.config.php WILL NOT automatically provide the Twitter Bootstrap environment for your project. You either have to already have the Twitter Bootstrap functioning or you can follow instructions supplied with DluTwBootstrap to manually enable it for your project. All necessary libraries and scripts are packaged with the module as well as an example layout template, so it is pretty easy.

Demo forms

There are demo forms included with the module. Go to the URL
http://<your-machine>/tw-bootstrap-demo/form
to see them in action. Check the source code to see how the forms are constructed.

Basic usage

The DluTwBootstrap module is basically just a set of forms, elements and decorators extending the original ZF2 classes. The usage is very simple. Just extend one of the supplied form classes and go about the rest of your form as usual and you are done.

use DluTwBootstrap\Form\Horizontal;
class MyForm extends Horizontal
{
    public function init() {
        //Add your form controls in any standard ZF2 way
        //...
    }
}

By extending one of the supplied form classes (Horizontal, Vertical, Inline, Search) you are configuring the form plugin loader with custom prefix paths to load the supplied elements and decorators before the standard ones. As this is the standard way to extend the form functionality in ZF, you are still able to use any standard way to add elements to the form: addElement(), createElement() or configuration.

Advanced usage

There are a few Twitter Bootstrap form features not addressed by any standard ZF2 form means:

  • Inline help text
  • Placeholder text
  • Inline Radio and MultiCheckbox elements
  • Prepend and Append texts for the Text element
  • Indented action buttons

All these are accessible either via setter methods (e.g. setInlineHelp(), setPlaceholderText()) or using configuration. The indented action buttons require a specific display group.

Please see the repository overview page for detailed instructions on basic as well as advanced usage.

All this in vain (sort of)

This is all very nice, but it won’t last! The ZF2 Form package is getting a major overhaul and some very basic concepts are going to change (e.g. we likely lose the decorators in favour of the view helpers). See the RFC – Forms to learn more. When the new Form package arrives in one of the future betas this module will need massive refactoring (and probably your form classes too). But until then we can easily generate nice looking Twitter Bootstrap forms using the DluTwBootstrap module.