README

(支持 Twitter Bootstrap v3.*)

注意：如果您想贡献，请不要犹豫，我会审查任何 PR。

介绍

TwbBundle 是一个用于 Zend Framework 2 的模块，用于轻松集成 Twitter Bootstrap v3.*。

贡献

如果您希望为 TwbBundle 做贡献，请阅读 CONTRIBUTING.md 文件。

演示/示例

使用 TwbBundle 渲染表单、按钮、警告：在线查看 操作。

要求

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

安装

主要设置

通过克隆项目（手动）

1. 将此项目克隆到您的 ./vendor/ 目录。
2. （可选）将 Twitter bootstrap 项目（v3.*）克隆到您的 ./vendor/ 目录。

使用 composer（更快的方式）

1. 将此项目添加到您的 composer.json

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

2. 现在运行以下命令，让 composer 下载 TwbBundle

   $ php composer.phar update

安装后

1. 在您的 application.config.php 文件中启用它。

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

2. 包含 Twitter Bootstrap 资产

使用 AssetsBundle 模块（简单方式）

• 安装 AssetsBundle 模块（1.0）

• 安装 Twitter Bootstrap（v2.3.2）

• 编辑应用程序模块配置文件 module/Application/config/module.config.php，添加以下配置片段

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

• 编辑布局文件 module/Application/view/layout/layout.phtml，以渲染 head 脚本

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

手动

• 将 bootstrap.css 文件（可在 Twitter Bootstrap 网站上找到，https://github.com/twbs/bootstrap/archive/v3.0.0.zip）复制到您的资产文件夹，并将其添加到您的 head 脚本中

如何使用 TwbBundle

视图助手

TwbBundle 提供视图助手，帮助渲染 HTML 元素

表单

表单：TwbBundle\Form\View\Helper\TwbBundleForm

表单助手可以使用视图助手服务 form(\Zend\Form\FormInterface $oForm = null, $sFormLayout = \TwbBundle\Form\View\Helper\TwbBundleForm::LAYOUT_HORIZONTAL) 调用

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

使用特定布局打开表单标签

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

此助手接受一个表单元素作为第一个参数，以及一个可选的 Bootstrap 定义布局样式定义作为第二个参数。以下是可用的布局

• TwbBundle\Form\View\Helper::LAYOUT_HORIZONTAL：水平（默认）
• TwbBundle\Form\View\Helper::LAYOUT_INLINE：内联

助手自动添加表单特定类和 form 角色属性。

按钮：TwbBundle\Form\View\Helper\TwbBundleFormButton

按钮助手可以使用视图助手服务 formButton(\Zend\Form\ElementInterface $oElement, $sButtonContent = null) 调用

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

此助手接受一个按钮元素作为第一个参数，以及可选的按钮内容作为第二个参数。它自动添加按钮特定类（btn和btn-default，如果没有定义按钮类）属性。

选项glyphicon（字符串或数组）和fontAwesome（字符串或数组）可以定义以在元素中渲染一个glyphicon或fontAwesome图标：glyphicon通过glyphicon渲染器渲染。fontAwesome通过fontAwesome渲染器渲染。

如果选项是字符串，则应该是图标的名称（例如："star"，"search"等），如果存在，则glyphicon将前置标签。如果选项是数组，则接受以下选项

• 字符串icon：图标的名称（例如："star"，"search"等）。
• 字符串position：可选的，表示将glyphicon前置或后置到按钮内容的相对位置，\TwbBundle\Form\View\Helper\TwbBundleFormButton::GLYPHICON_PREPEND（默认）和\TwbBundle\Form\View\Helper\TwbBundleFormButton::GLYPHICON_APPEND。
• 数组attributes：可选的，表示添加到glyphicon元素的额外属性

按钮可以通过定义元素选项dropdown（数组）来设置为下拉按钮：下拉菜单通过下拉渲染器渲染，它接受以下附加选项

• 布尔值split：按钮元素和箭头被分割。
• 布尔值dropup：渲染一个向上展开元素而不是下拉菜单。

可以通过将选项disable-twb传递给元素来禁用在div容器中渲染。

复选框：TwbBundle\Form\View\Helper\TwbBundleFormCheckbox

可以使用视图助手服务formCheckbox(\Zend\Form\Checkbox $oElement)在视图中调用复选框助手。

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

此助手接受一个复选框元素作为第一个参数。由于输入被渲染到标签元素中，可以通过选项传递标签位置（默认为追加）。可以将选项disable-twb（布尔值）传递给元素以禁用在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

可以在视图中使用视图助手服务formCollection(\Zend\Form\ElementInterface $oElement)调用表单集合助手。

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

此助手接受一个表单集合（字段集）元素作为第一个参数。

表单元素：TwbBundle\Form\View\Helper\TwbBundleFormElement

可以在视图中使用视图助手服务formElement(\Zend\Form\ElementInterface $oElement)调用表单元素助手。

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

此助手接受一个表单元素作为第一个参数。此助手可以通过将适当的选项add-on-prepend和/或add-on-append设置到元素中来渲染前置和/或后置附加组件。这些选项接受以下值

• Zend\Form\ElementInterface：元素将在附加组件中渲染
• scalar：值将被翻译并在附加组件中渲染
• array：数组接受以下键之一
  • text（标量）：值将被翻译并在附加组件中渲染
  • element（数组）：将通过\Zend\Form\Factory和给定的数组创建一个元素，然后在附加组件中渲染
  • element（Zend\Form\ElementInterface）：元素将在附加组件中渲染

表单元素错误：TwbBundle\Form\View\Helper\TwbBundleFormElementErrors

可以在视图中使用视图助手服务formElementErrors(\Zend\Form\ElementInterface $oElement)调用表单元素错误助手。

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

此助手接受一个表单元素作为第一个参数。此助手渲染元素的错误。

多选框：TwbBundle\Form\View\Helper\TwbBundleFormMultiCheckbox

可以在视图中使用视图助手服务formMultiCheckbox(\Zend\Form\ElementInterface $oElement)调用多选框助手。

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

此辅助函数接受一个元素作为第一个参数。可以将选项 inline（布尔值）传递给元素，以显示内联复选框（默认）或非内联。

单选按钮：TwbBundle\Form\View\Helper\TwbBundleFormRadio

可以在视图中使用视图辅助服务 formCheckbox(\Zend\Form\ElementInterface $oElement) 调用单选按钮辅助函数。

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

此辅助函数接受一个元素作为第一个参数。可以将选项 disable-twb（布尔值）传递给元素，以禁用在 div 容器中渲染它。

表单行：TwbBundle\Form\View\Helper\TwbBundleFormRow

可以在视图中使用视图辅助服务 formRow(\Zend\Form\ElementInterface $oElement) 调用表单元素辅助函数。

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

此辅助函数接受一个表单元素作为第一个参数。可以将选项 twb-layout（字符串）传递给元素，以使用定义的布局样式渲染行，如 表单辅助函数。可以将选项 validation-state（字符串）传递给元素，以使用定义的验证状态类属性（has-...）渲染行。如果元素有消息，则自动添加 has-error 类属性。可以将选项 column-size（整数）传递给元素，以使用定义的列大小类属性（col-lg-...）渲染行。可以将选项 help-block（字符串）传递给元素，以渲染一个帮助块并将其翻译后附加到元素。

如果您想将元素包装进一个

您可以在取消转义后允许标签 HTML 渲染

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

您还可以通过在传递给 formRow 的元素上传递 twb-form-group-size 选项来设置表单组的大小，例如 Twig 语法

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

静态：TwbBundle\Form\View\Helper\TwbBundleFormStatic

可以在视图中使用视图辅助服务 formStatic(\Zend\Form\ElementInterface $oElement) 调用静态辅助函数。

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

此辅助函数接受一个元素作为第一个参数。

混合

警报：TwbBundle\View\Helper\TwbBundleAlert

可以在视图中使用视图辅助服务 alert($sAlertMessage = null, $aAlertAttributes = null, $bDismissable = false) 调用警报辅助函数。

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

此辅助函数接受一条消息作为第一个参数，作为警报容器属性的第二个参数（可选），以及作为第三个参数的布尔值，以显示或隐藏警报消息的关闭操作（可选）。自动添加类属性 "alert" 到警报容器。

徽章：TwbBundle\View\Helper\TwbBundleBadge

可以在视图中使用视图辅助服务 badge($sBadgeMessage = null, array $aBadgeAttributes = null) 调用徽章辅助函数。

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

此辅助函数接受一条消息作为第一个参数，作为徽章容器属性的第二个参数（可选）。自动添加类属性 "badge" 到徽章容器。

按钮组：TwbBundle\View\Helper\TwbBundleButtonGroup

可以在视图中使用视图辅助服务 buttonGroup(array $aButtons = null, array $aButtonGroupOptions = null) 调用按钮组辅助函数。

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

此辅助函数接受一个按钮数组作为第一个参数，作为按钮组容器属性的第二个参数（可选）。按钮可以是 \Zend\Form\Element\Button 的实例或包含用于使用 \Zend\Form\Factory 构建元素的数据的数组。

图标字体：TwbBundle\View\Helper\TwbBundleGlyphicon

可以使用视图助手服务 glyphicon($sGlyphicon = null, array $aGlyphiconAttributes = null) 在视图中调用 Glyphicon 助手。

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

此助手接受一个图标名称作为第一个参数（例如 "star", "search" ...），以及作为第二个参数的 glyphicon 元素属性（可选）。自动将类属性 "glyphicon" 添加到 glyphicon 容器中。

FontAwesome : TwbBundle\View\Helper\TwbBundleFontAwesome

可以使用视图助手服务 fontAwesome($sFontAwesome = null, array $aFontAwesomeAttributes = null) 在视图中调用 FontAwesome 助手。

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

此助手接受一个图标名称作为第一个参数（例如 "star", "search" ...），以及作为第二个参数的 fontAwesome 元素属性（可选）。自动将类属性 "fa" 添加到 fontAwesome 容器中。

下拉菜单 : TwbBundle\View\Helper\TwbBundleDropDown

可以使用视图助手服务 dropdown(array $aDropdownOptions = null) 在视图中调用下拉菜单助手。

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

此助手接受下拉菜单配置作为第一个参数。

• attributes（数组）: 下拉菜单容器的属性（可选）
• label（标量）: 标签内容（将被翻译），可能为空（可选）
• toggle_attributes（数组）: 下拉切换容器的属性（可选）
• items（数组）: 项目列表，应包含
• 标量 :
• \TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_DIVIDER: 显示分隔符
• text: 在链接中显示文本（已翻译）(锚点属性与内容相同)
• array: 项目选项
• type（字符串）: 项目的类型 * \TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_HEADER: 将项目渲染为标题。需要以下选项
  • label（标量）: 项目内容的文本（已翻译）
  • \TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_DIVIDER: 渲染分隔符
  • \TwbBundle\View\Helper\TwbBundleDropDown::TYPE_ITEM_LINK: 将项目渲染为链接 <a ...> 需要以下选项
  • label（标量）: 项目内容的文本（已翻译）
  • item_attributes（数组）: 项目容器的属性（可选）
• attributes（数组）: 项目容器的属性
• list_attributes（数组）: 下拉列表容器的属性（可选）

标签 : TwbBundle\View\Helper\TwbBundleLabel

标签助手可以使用视图助手服务 label($sLabelMessage = null, array $aLabelAttributes = 'label-default') 在视图中调用。

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

此助手接受一个消息作为第一个参数，以及作为第二个参数的标签容器属性（可选）。自动将类属性 "label" 添加到标签容器中，且没有提供任何属性时默认为 "label-default"。默认的标签容器是一个 span，但可以通过在属性数组中传递标签名来更改。

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

忽略自定义视图助手

默认情况下，此模块尝试将 form-control 类添加到每个表单元素。有一些元素，如复选框、单选按钮和按钮，在 Bootstrap 中不使用该类。此配置允许您告诉渲染方法忽略您的自定义表单视图助手，并且不要添加该类。

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

元素

TwbBundle 提供新的元素以支持 Twitter Bootstrap 的潜力。

静态元素 : TwbBundle\Form\Element\StaticElement

静态元素是一个表单元素，提供 静态控制 并应由 静态表单助手 渲染

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

由 hamichen 修改