TwbBundle, v2.0

(Supports Twitter Bootstrap v3.*)

NOTE : If you want to contribute don't hesitate, I'll review any PR.

Introduction

TwbBundle is a module for Zend Framework 2, for easy integration of the Twitter Bootstrap v3.*.

Contributing

If you wish to contribute to TwbBundle, please read the CONTRIBUTING.md file.

Demonstration / example

Render forms, buttons, alerts with TwbBundle : see it in action on-line.

Requirements

• Zend Framework 2 (2.*)
• Twitter Bootstrap (v3.*)

Installation

Main Setup

By cloning project (manual)

1. Clone this project into your ./vendor/ directory.
2. (Optionnal) Clone the Twitter bootstrap project (v3.*) into your ./vendor/ directory.

With composer (the faster way)

1. Add this project in your composer.json:

   "require": {
       "neilime/zf2-twb-bundle": "2.*@stable"
   }

2. Now tell composer to download TwbBundle by running the command:

   $ php composer.phar update

Post installation

1. Enabling it in your application.config.php file.

   <?php
   return array(
       'modules' => array(
           // ...
           'TwbBundle',
       ),
       // ...
   );

2. Include Twitter Bootstrap assets

With AssetsBundle module (easy way)

• Install the AssetsBundle module(1.0)
• Install Twitter Bootstrap (v2.3.2)

• Edit the application module configuration file module/Application/config/module.config.php, adding the configuration fragment below:

  <?php
  return array(
      //...
       'asset_bundle' => array(
           'assets' => array(
               'less' => array('@zfRootPath/vendor/twitter/bootstrap/less/bootstrap.less')
           )
       ),
       //...
   );

• Edit layout file module/Application/view/layout/layout.phtml, to render head scripts :

  <?php
  //...
  echo $this->headScript();
  //...

Manually

• Copy bootstrap.css file (available on Twitter Bootstrap website(https://github.com/twbs/bootstrap/archive/v3.0.0.zip) into your assets folder and add it in your head scripts

How to use TwbBundle

View helpers

TwbBundle provides view helpers helping render html elements

Forms

Form : TwbBundle\Form\View\Helper\TwbBundleForm

Form helper can be called in a view with the view helper service form(\Zend\Form\FormInterface $oForm = null, $sFormLayout = \TwbBundle\Form\View\Helper\TwbBundleForm::LAYOUT_HORIZONTAL) :

<?php
$this->form(new \Zend\Form\Form());

Open form tag with a specific layout :

<?php
$this->form(null,\TwbBundle\Form\View\Helper\TwbBundleForm::LAYOUT_INLINE)->openTag($oForm);

This helper accepts a form element as first param, and an optionnal Bootstrap defined layout style definition as second param. Here are the available layouts :

• TwbBundle\Form\View\Helper::LAYOUT_HORIZONTAL : horizontal (default)
• TwbBundle\Form\View\Helper::LAYOUT_INLINE : inline

The helper auto add form specific class and form role attributes.

Button : TwbBundle\Form\View\Helper\TwbBundleFormButton

Button helper can be called in a view with the view helper service formButton(\Zend\Form\ElementInterface $oElement, $sButtonContent = null) :

<?php
$this->formButton(new \Zend\Form\Element());

This helper accepts a button element as first param, and an optionnal button content as second param. It auto add button specific class (btn & btn-default is no button class is defined) attribute.

The option glyphicon (string or array) and fontAwesome (string or array) can be defined to render a glyphicon or a fontAwesome icon into the element : The glyphicon is rendered by the glyphicon renderer. The fontAwesome is rendered by the fontAwesome renderer.

If the option is a string, it should be the name of the icon (e.g. "star", "search" ...), the glyphicon will prepend the label if exists. If the option is an array, it accept the folling options :

• string icon : the name of the icon (e.g. "star", "search" ...).
• string position : (optional) the position of the glyphicon to prepend or append the button content, \TwbBundle\Form\View\Helper\TwbBundleFormButton::GLYPHICON_PREPEND (the default) and \TwbBundle\Form\View\Helper\TwbBundleFormButton::GLYPHICON_APPEND.
• array attributes : (optional) the additional attributes to the glyphicon element

Button can be set as dropdown button by defined the option dropdown (array) to the element : The dropdown is rendered by the dropdown renderer, it accept the folling additionnal options :

• boolean split : the button element and the carret are splitted.
• boolean dropup : render a dropup element instead of a dropdown.

The option disable-twb can be passed to the element to disable rendering it in a div container.

Checkbox : TwbBundle\Form\View\Helper\TwbBundleFormCheckbox

Checkbox helper can be called in a view with the view helper service formCheckbox(\Zend\Form\Checkbox $oElement) :

<?php
$this->formCheckbox(new \Zend\Form\Element\Checkbox('checkbox-input'));

This helper accepts a checkbox element as first param. As the input is rendered into a label element, the label position (append by default) can passed as an option The option disable-twb (boolean) can be passed to the element to disable rendering it in a label.

<?php
$this->formCheckbox(new \Zend\Form\Element\Checkbox('checkbox-input',array(
    'label' => 'Prepend label',
    'label_options' => array('position' => \Zend\Form\View\Helper\FormRow::LABEL_PREPEND)
)));

Form collection : TwbBundle\Form\View\Helper\TwbBundleFormCollection

Form collection helper can be called in a view with the view helper service formCollection(\Zend\Form\ElementInterface $oElement) :

<?php
$this->formCollection(new \Zend\Form\Element());

This helper accepts a form collection (fieldset) element as first param.

Form element : TwbBundle\Form\View\Helper\TwbBundleFormElement

Form element helper can be called in a view with the view helper service formElement(\Zend\Form\ElementInterface $oElement) :

<?php
$this->formElement(new \Zend\Form\Element());

This helper accepts a form element as first param. This helper can render prepend and/or append add-on by setting the appropriate option add-on-prepend and/or add-on-append to the element. These options accept the following values :

• Zend\Form\ElementInterface : the element will be rendered in the add-on
• scalar : the value will be translated and rendered in the add-on
• array : The array accept once of the following keys :
  • text (scalar) : the value will be translated and rendered in the add-on
  • element (array) : An element will be created by \Zend\Form\Factory and the given array, then rendered in the add-on
  • element (Zend\Form\ElementInterface) : the element will be rendered in the add-on

Form element errors : TwbBundle\Form\View\Helper\TwbBundleFormElementErrors

Form element errors helper can be called in a view with the view helper service formElementErrors(\Zend\Form\ElementInterface $oElement) :

<?php
$this->formElementErrors(new \Zend\Form\Element());

This helper accepts a form element as first param. This helper render element's errors.

Multi-Checkbox : TwbBundle\Form\View\Helper\TwbBundleFormMultiCheckbox

Multi-Checkbox helper can be called in a view with the view helper service formMultiCheckbox(\Zend\Form\ElementInterface $oElement) :

<?php
$this->formMultiCheckbox(new \Zend\Form\Element\ElementInterface());

This helper accepts an element as first param. The option inline (boolean) can be passed to the element to display checkoxes inlined (default) or not.

Radio : TwbBundle\Form\View\Helper\TwbBundleFormRadio

Radio helper can be called in a view with the view helper service formCheckbox(\Zend\Form\ElementInterface $oElement) :

<?php
$this->formRadio(new \Zend\Form\Element\ElementInterface());

This helper accepts an element as first param. The option disable-twb (boolean) can be passed to the element to disable rendering it in a div container.

Form row : TwbBundle\Form\View\Helper\TwbBundleFormRow

Form element helper can be called in a view with the view helper service formRow(\Zend\Form\ElementInterface $oElement) :

<?php
$this->formRow(new \Zend\Form\Element());

This helper accepts a form element as first param. The option twb-layout (string) can be passed to the element to render the row with a defined layout style as form helper. The option validation-state (string) can be passed to the element to render the row with a defined validation state class attribute(has-...). If the element has messages, has-error class attribute is auto added. The option column-size (int) can be passed to the element to render the row with a defined column size class attribute(col-lg-...). The option help-block (string) can be passed to the element to render an help block translated appending the element.

If you like to wrap elements into a

<?php
$this->formRow(new \Zend\Form\Element('my-element',  array(
    'label' => 'My <i>Label</i> :',
    'label_options' => array('disable_html_escape' => true)
)));

{% for f in server_form %}
    {% do f.setOption( 'twb-form-group-size', 'form-group-sm' ) %}
    {{ formRow( f ) }}
{% endfor %}

<?php
$this->formStatic(new \Zend\Form\Element\ElementInterface());

<?php
$this->alert('alert message',array('class' => 'alert-success'));

<?php
$this->badge('badge message',array('class' => 'pull-right'));

<?php
$this->buttonGroup(array(new \Zend\Form\Element\Button('left', array('label' => 'Left'))),array('class' => 'pull-right'));

<?php
$this->glyphicon('star',array('class' => 'pull-right'));

<?php
$this->fontAwesome('star',array('class' => 'pull-right'));

<?php
$this->dropdown(array('Item #1',\TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_DIVIDER,'Item #2'));

<?php
$this->label('label message',array('class' => 'label-primary'));

<?php
$this->label('label message',array('class' => 'label-primary','tagName' => 'a'));

return [
    'twbbundle' => [
        'ignoredViewHelpers' => [
            'viewhelpername'
        ]
    ]
];

<?php
$this->formStatic(new \TwbBundle\Form\Element\StaticElement());