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)
- Clone this project into your
./vendor/
directory. - (Optionnal) Clone the Twitter bootstrap project (v3.*) into your
./vendor/
directory.
With composer (the faster way)
-
Add this project in your composer.json:
"require": { "neilime/zf2-twb-bundle": "2.*@stable" }
-
Now tell composer to download TwbBundle by running the command:
$ php composer.phar update
Post installation
-
Enabling it in your
application.config.php
file.<?php return array( 'modules' => array( // ... 'TwbBundle', ), // ... );
-
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
TwbBundle\Form\View\Helper\TwbBundleForm
Form : 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.
TwbBundle\Form\View\Helper\TwbBundleFormButton
Button : 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.
TwbBundle\Form\View\Helper\TwbBundleFormCheckbox
Checkbox : 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)
)));
TwbBundle\Form\View\Helper\TwbBundleFormCollection
Form collection : 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.
TwbBundle\Form\View\Helper\TwbBundleFormElement
Form element : 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-onscalar
: the value will be translated and rendered in the add-onarray
: The array accept once of the following keys :text
(scalar) : the value will be translated and rendered in the add-onelement
(array) : An element will be created by \Zend\Form\Factory and the given array, then rendered in the add-onelement
(Zend\Form\ElementInterface) : the element will be rendered in the add-on
TwbBundle\Form\View\Helper\TwbBundleFormElementErrors
Form element errors : 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.
TwbBundle\Form\View\Helper\TwbBundleFormMultiCheckbox
Multi-Checkbox : 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.
TwbBundle\Form\View\Helper\TwbBundleFormRadio
Radio : 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.
TwbBundle\Form\View\Helper\TwbBundleFormRow
Form row : 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
twb-row-open
(bool) can be passed to the element where the row must start and will be printed before the element is rendered. It could be you have to provide the column-size
in combination with this option.
The option twb-row-close
(bool) can be passed to the element to close the earlier opened row and will be printed after the elements is rendered.
Note: closing earlier opened rows is your responsibility.
You can allow the label html rendering after toggling off escape :
<?php
$this->formRow(new \Zend\Form\Element('my-element', array(
'label' => 'My <i>Label</i> :',
'label_options' => array('disable_html_escape' => true)
)));
TwbBundle\Form\View\Helper\TwbBundleFormStatic
Static : Static helper can be called in a view with the view helper service formStatic(\Zend\Form\ElementInterface $oElement)
:
<?php
$this->formStatic(new \Zend\Form\Element\ElementInterface());
This helper accepts an element as first param.
Mixed
TwbBundle\View\Helper\TwbBundleAlert
Alert : Alert helper can be called in a view with the view helper service alert($sAlertMessage = null, $aAlertAttributes = null, $bDismissable = false)
:
<?php
$this->alert('alert message',array('class' => 'alert-success'));
This helper accepts a message as first param, attributes for alert container as second param (optionnal) and boolean as third param to display or not a close action to the alert message (optionnal). The class attribute "alert" is auto added to the alert container.
TwbBundle\View\Helper\TwbBundleBadge
Badge : Badge helper can be called in a view with the view helper service badge($sBadgeMessage = null, array $aBadgeAttributes = null)
:
<?php
$this->badge('badge message',array('class' => 'pull-right'));
This helper accepts a message as first param, and attributes for badge container as second param (optionnal). The class attribute "badge" is auto added to the badge container.
TwbBundle\View\Helper\TwbBundleButtonGroup
Button group : Button group helper can be called in a view with the view helper service buttonGroup(array $aButtons = null, array $aButtonGroupOptions = null)
:
<?php
$this->buttonGroup(array(new \Zend\Form\Element\Button('left', array('label' => 'Left'))),array('class' => 'pull-right'));
This helper accepts an array of buttons as first param, and attributes for button group container as second param (optionnal).
The buttons can be instance of \Zend\Form\Element\Button
or array containing data to build an element with the \Zend\Form\Factory
TwbBundle\View\Helper\TwbBundleGlyphicon
Glyphicon : Glyphicon helper can be called in a view with the view helper service glyphicon($sGlyphicon = null, array $aGlyphiconAttributes = null)
:
<?php
$this->glyphicon('star',array('class' => 'pull-right'));
This helper accepts an icon name as first param (e.g. "star", "search" ...), and attributes for glyphicon element as second param (optionnal). The class attribute "glyphicon" is auto added to the glyphicon container.
TwbBundle\View\Helper\TwbBundleFontAwesome
FontAwesome : FontAwesome helper can be called in a view with the view helper service fontAwesome($sFontAwesome = null, array $aFontAwesomeAttributes = null)
:
<?php
$this->fontAwesome('star',array('class' => 'pull-right'));
This helper accepts an icon name as first param (e.g. "star", "search" ...), and attributes for fontAwesome element as second param (optionnal). The class attribute "fa" is auto added to the fontAwesome container.
TwbBundle\View\Helper\TwbBundleDropDown
Dropdown : Dropdown helper can be called in a view with the view helper service dropdown(array $aDropdownOptions = null)
:
<?php
$this->dropdown(array('Item #1',\TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_DIVIDER,'Item #2'));
This helper accepts dropdown configuration as first param :
attributes
(array) : attributes for the dropdown container (optionnal)label
(scalar) : Label content (will be translated), may be empty (optionnal)toggle_attributes
(array) : attributes for the dropdown toggle container (optionnal)items
(array) : list of items, should contains :scalar
:\TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_DIVIDER
: display a dividertext
: display a text (translated) into a link (anchor attribute is the same as content)array
: the item options :type
(string) : the type of item *\TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_HEADER
: render an item as header It needs the following option :label
(scalar) content text (translated) of the item\TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_DIVIDER
: render a divider\TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_LINK
: render an item as a link<a ...>
It needs the following option :label
(scalar) content text (translated) of the itemitem_attributes
(array) : attributes for the item container (optionnal)
attributes
(array) : the attributes of the item containerlist_attributes
(array) : attributes for the dropdown list container (optionnal)
TwbBundle\View\Helper\TwbBundleLabel
Label : Label helper can be called in a view with the view helper service label($sLabelMessage = null, array $aLabelAttributes = 'label-default')
:
<?php
$this->label('label message',array('class' => 'label-primary'));
This helper accepts a message as first param, and attributes for label container as second param (optionnal). The class attribute "label" is auto added to the label container and "label-default" is no attributes is given. Default label container is a span, but it can be changed by passing the tag name in the attributes array :
<?php
$this->label('label message',array('class' => 'label-primary','tagName' => 'a'));
Ignore custom view helpers
By default, this module tries to add form-control class to every form element. There are some elements, like checkboxes, radios and buttons, that does not use that class in bootstrap. This config allows you to tell the render method to ignore your custom form view helper and do NOT add that class.
return [
'twbbundle' => [
'ignoredViewHelpers' => [
'viewhelpername'
]
]
];
Elements
TwbBundle provides new elements to supports Twitter Bootstrap potential.
TwbBundle\Form\Element\StaticElement
StaticElement : Static element is a form element witch provides Static control
and should be rendered by static form helper
<?php
$this->formStatic(new \TwbBundle\Form\Element\StaticElement());