Back to top

BS3ActiveForm

A lightweight utility to render Bootstrap 3 forms in Yii

Introduction

BS3ActiveForm is an enhanced version of CActiveForm which mainly adds the convenient group() method. It renders all sorts of Bootstrap 3 form groups. By default it creates the markup for stacked form elements.

Example 1: Default form
<?php $form = $this->beginWidget('Codemix\BS3ActiveForm') ?>
    <?= $form->group('textField', $model, 'demo'); ?>
    <?= $form->group('dropDownList', $model, 'demo', $opts); ?>
    <?= $form->group('checkBox', $model, 'demo'); ?>
    <?= $form->group('radioButtonList', $model, 'demo', $opts); ?>
<?php $this->endWidget() ?>

The arguments you can supply to group() depend on the type of input you want to render. For list type inputs like dropDownList, checkBoxList, etc. you need 5 arguments: 

BS3ActiveForm::group($method, $model, $attribute, $listOptions, $options=array());

For all other input elements it expects 4 arguments: 

BS3ActiveForm::group($method, $model, $attribute, $options=array());
Parameter Description
$method The method name from CActiveForm which will render the input element, for example textField or radioButtonList.
$model The model object that ist passed to the CActiveForm method.
$attribute The attribute name that ist passed to the CActiveForm method.
$listOptions The list options that are passed to the CActiveForm method. This is only required for list style elements.
$options The options that control how the form group is rendered. See below.

Note: This class does not include any Bootstrap 3 CSS or Javascript files. The idea was to keep this class very lightweight. Including Bootstrap 3 is very easy, though. For a start you can just drop the following lines into your layout file. 

<head>
    <?php 
        $cs = Yii::app()->clientScript;
        $cs->registerCoreScript('jquery');
        $cs->registerScriptFile('//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js',CClientScript::POS_END);
    ?>
        <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
        <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">

Of course you'll also have to modify the main layout markup to adhere to the Bootstrap 3 conventions.

Group Options

The markup that is created for a form group can be controlled through the $options argument. Let's look at some simple examples first.

Example 2: Group options

Help text

<?php $form = $this->beginWidget('Codemix\BS3ActiveForm') ?>
    <?= $form->group('textField', $model, 'demo', array(
        'inputOptions' => array(
            'placeholder' => 'Placeholder',
        ),
    )); ?>
    <?= $form->group('dropDownList', $model, 'demo', $opts, array(
        'template' => '{label} <div class="row"><div class="col-xs-4">{input}{error}{help}</div></div>',
    )); ?>
    <?= $form->group('checkBox', $model, 'demo',array(
        'helpText' => 'Help text',
    )); ?>
    <?= $form->group('radioButtonList', $model, 'demo', $opts,array(
        'inline' => 'true',
    )); ?>
<?php $this->endWidget() ?>

The following options can be used with group(). Note, that for some elements the options will be set to sane default values.

Option Description
template The template used to render the form group. This value is set automatically depending on the form layout (see below) and the input type. For the default layout the value is {label} {input} {error} {help}. The available placeholders are:
{label} The full label tag for the input element
{beginLabel} The opening label tag (if you need more control over the label than with {label}).
{labelTitle} The label tag, for use with {beginLabel} / {endLabel}.
{endLabel} The closing label tag.
{beginWrapper} The opening wrapper tag. This is only used for some elements and layouts.
{endWrapper} The closing wrapper tag. This is only used for some elements and layouts.
{input} The input element. This can also be a list of elements, e.g. for checkBoxList.
{error} The error element.
{help} The help element.
groupTag The container tag of rendered template. The default is div.
groupOptions The htmlOptions of the container tag. The default is array('class' => 'form-group').
labelOptions The htmlOptions of the label tag. The default for most input types is array('class' => 'control-label').
wrapperTag The tag to use for the (optional) wrapper. Default is div.
wrapperOptions The htmlOptions of the wrapper tag. The default for form layout horizontal (see form options below) is array('class' => 'col-sm-6').
inputTemplate An optional template for the input element. If set, this will be used to render the content of the {input} placeholder. This can be used to create input groups (see the examples). The default is none.
inputOptions The htmlOptions of the input element that are passed to the CActiveForm method. The default depends for most elements is array('class' => 'form-control'). Elements of type checkBox, checkBoxList and radioButtonlist add some more options to render the correct label markup.
errorTag The tag to use for the error element. Default is p.
errorOptions The htmlOptions of the error element. The default depends on the form layout. It's array('class' => 'help-block') for layout default and array('class' => 'help-block col-sm-3') for layout horizontal.
helpTag The tag to use for the help element. Default is p.
helpOptions The htmlOptions of the help element. The default depends on the form layout. It's array('class' => 'help-block') for layout default and array('class' => 'help-block col-sm-3') for layout horizontal.
inline This option can be used with radioButtonList and checkBoxList elements to render inline list items. If set to true, it will automatically set the appropriate template and inputOptions (i.e. labelOptions).
label If this is set to false, no label will be rendered (i.e. {label}, {beginLabel} and {endLabel} will be empty).
enableErrorBlock Whether to render the error block. This is mainly useful for inline forms. By default this is true for standard and horizontal layout and false for inline layout.

Form Options

Except for inline, all the above options can also be set on the BS3ActiveForm. The options set on the form will be used as default values for all form groups. If $options are provided in the call to group(), they will be override the default group options set here.

Example 3: Form options
<?php $form = $this->beginWidget('Codemix\BS3ActiveForm', array(
    'helpOptions' => array(
        'class' => 'help-block well',
    ),
)) ?>
    <?= $form->group('textField', $model, 'demo'); ?>
    <?= $form->group('dropDownList', $model, 'demo', $opts); ?>
    <?= $form->group('checkBox', $model, 'demo'); ?>
    <?= $form->group('radioButtonList', $model, 'demo', $opts); ?>
<?php $this->endWidget() ?>

Besides this you can also set some more options on the form to define the layout you want to use.

Option Description
layout The form layout, which can either be standard, horizontal or inline. If the layout is horizontal the following defaults are set:
template {label} {beginWrapper} {input} {error} {endWrapper} {help}
wrapperOptions array('class' => 'col-sm-6').
labelOptions array('class' => 'control-label col-sm-3').
errorOptions array('class' => 'help-block col-sm-3').
helpOptions array('class' => 'help-block col-sm-3').
So in order to modify the horizontal layout (e.g. adapt column width or change location of help and error element) you can configure your own values for the above parameters through the form options.
horizontalLabelClass The CSS class to add to the label in horizontal mode. Default is col-sm-3.
horizontalWrapperOffsetClass The CSS class to add to the wrapper in horizontal mode if no label is rendered. Default is col-sm-offset-3. This should match the width set through horizontalLabelClass.
horizontalWrapperClass The CSS class to add to the wrapper in horizontal mode. Default is col-sm-6.
horizontalErrorClass The CSS class to add to the error block in horizontal mode. Default is none.
horizontalHelpClass The CSS class to add to the help block in horizontal mode. Default is col-sm-3.