Class yii\bootstrap\ActiveField

Inheritanceyii\bootstrap\ActiveField » yii\widgets\ActiveField
Available since extension's version2.0
Source Code https://github.com/yiisoft/yii2-bootstrap/blob/master/src/ActiveField.php

A Bootstrap 3 enhanced version of \yii\widgets\ActiveField.

This class adds some useful features to \yii\widgets\ActiveField to render all sorts of Bootstrap 3 form fields in different form layouts:

There are also some new placeholders that you can use in the template configuration:

  • {beginLabel}: the opening label tag
  • {labelTitle}: the label title for use with {beginLabel}/{endLabel}
  • {endLabel}: the closing label tag
  • {beginWrapper}: the opening wrapper tag
  • {endWrapper}: the closing wrapper tag

The wrapper tag is only used for some layouts and form elements.

Note that some elements use slightly different defaults for template and other options. You may want to override those predefined templates for checkboxes, radio buttons, checkboxLists and radioLists in the \yii\widgets\ActiveForm::fieldConfig of the \yii\widgets\ActiveForm:

Example:

use yii\bootstrap\ActiveForm;

$form = ActiveForm::begin(['layout' => 'horizontal']);

// Form field without label
echo $form->field($model, 'demo', [
    'inputOptions' => [
        'placeholder' => $model->getAttributeLabel('demo'),
    ],
])->label(false);

// Inline radio list
echo $form->field($model, 'demo')->inline()->radioList($items);

// Control sizing in horizontal mode
echo $form->field($model, 'demo', [
    'horizontalCssClasses' => [
        'wrapper' => 'col-sm-2',
    ]
]);

// With 'default' layout you would use 'template' to size a specific field:
echo $form->field($model, 'demo', [
    'template' => '{label} <div class="row"><div class="col-sm-4">{input}{error}{hint}</div></div>'
]);

// Input group
echo $form->field($model, 'demo', [
    'inputTemplate' => '<div class="input-group"><span class="input-group-addon">@</span>{input}</div>',
]);

ActiveForm::end();

See also:

Public Properties

Hide inherited properties

Property Type Description Defined By
$checkboxTemplate string The template for checkboxes in default layout yii\bootstrap\ActiveField
$enableError boolean Whether to render the error. yii\bootstrap\ActiveField
$enableLabel boolean Whether to render the label. yii\bootstrap\ActiveField
$horizontalCheckboxTemplate string The template for checkboxes in horizontal layout yii\bootstrap\ActiveField
$horizontalCssClasses null|array CSS grid classes for horizontal layout. yii\bootstrap\ActiveField
$horizontalRadioTemplate string The template for radio buttons in horizontal layout yii\bootstrap\ActiveField
$inline boolean Whether to render checkboxList() and radioList() inline. yii\bootstrap\ActiveField
$inlineCheckboxListTemplate string The template for inline checkboxLists yii\bootstrap\ActiveField
$inlineRadioListTemplate string The template for inline radioLists yii\bootstrap\ActiveField
$inputTemplate string|null Optional template to render the {input} placeholder content yii\bootstrap\ActiveField
$radioTemplate string The template for radios in default layout yii\bootstrap\ActiveField
$wrapperOptions array Options for the wrapper tag, used in the {beginWrapper} placeholder yii\bootstrap\ActiveField

Property Details

Hide inherited properties

$checkboxTemplate public property

The template for checkboxes in default layout

public string $checkboxTemplate "<div class=\"checkbox\">\n{beginLabel}\n{input}\n{labelTitle}\n{endLabel}\n{error}\n{hint}\n</div>"
$enableError public property

Whether to render the error. Default is true except for layout inline.

public boolean $enableError true
$enableLabel public property

Whether to render the label. Default is true.

public boolean $enableLabel true
$horizontalCheckboxTemplate public property

The template for checkboxes in horizontal layout

public string $horizontalCheckboxTemplate "{beginWrapper}\n<div class=\"checkbox\">\n{beginLabel}\n{input}\n{labelTitle}\n{endLabel}\n</div>\n{error}\n{endWrapper}\n{hint}"
$horizontalCssClasses public property

CSS grid classes for horizontal layout. This must be an array with these keys:

  • 'offset' the offset grid class to append to the wrapper if no label is rendered
  • 'label' the label grid class
  • 'wrapper' the wrapper grid class
  • 'error' the error grid class
  • 'hint' the hint grid class
$horizontalRadioTemplate public property

The template for radio buttons in horizontal layout

public string $horizontalRadioTemplate "{beginWrapper}\n<div class=\"radio\">\n{beginLabel}\n{input}\n{labelTitle}\n{endLabel}\n</div>\n{error}\n{endWrapper}\n{hint}"
$inline public property

Whether to render checkboxList() and radioList() inline.

public boolean $inline false
$inlineCheckboxListTemplate public property

The template for inline checkboxLists

public string $inlineCheckboxListTemplate "{label}\n{beginWrapper}\n{input}\n{error}\n{endWrapper}\n{hint}"
$inlineRadioListTemplate public property

The template for inline radioLists

public string $inlineRadioListTemplate "{label}\n{beginWrapper}\n{input}\n{error}\n{endWrapper}\n{hint}"
$inputTemplate public property

Optional template to render the {input} placeholder content

public string|null $inputTemplate null
$radioTemplate public property

The template for radios in default layout

public string $radioTemplate "<div class=\"radio\">\n{beginLabel}\n{input}\n{labelTitle}\n{endLabel}\n{error}\n{hint}\n</div>"
$wrapperOptions public property

Options for the wrapper tag, used in the {beginWrapper} placeholder

public array $wrapperOptions = []

Method Details

Hide inherited methods

__construct() public method

public void __construct ( $config = [] )
$config

                public function __construct($config = [])
{
    $layoutConfig = $this->createLayoutConfig($config);
    $config = ArrayHelper::merge($layoutConfig, $config);
    parent::__construct($config);
}

            
checkbox() public method

public void checkbox ( $options = [], $enclosedByLabel true )
$options
$enclosedByLabel

                public function checkbox($options = [], $enclosedByLabel = true)
{
    if ($enclosedByLabel) {
        if (!isset($options['template'])) {
            $this->template = $this->form->layout === 'horizontal' ?
                $this->horizontalCheckboxTemplate : $this->checkboxTemplate;
        } else {
            $this->template = $options['template'];
            unset($options['template']);
        }
        if (isset($options['label'])) {
            $this->parts['{labelTitle}'] = $options['label'];
        }
        if ($this->form->layout === 'horizontal') {
            Html::addCssClass($this->wrapperOptions, $this->horizontalCssClasses['offset']);
        }
        $this->labelOptions['class'] = null;
    }
    return parent::checkbox($options, false);
}

            
checkboxList() public method

public void checkboxList ( $items, $options = [] )
$items
$options

                public function checkboxList($items, $options = [])
{
    if ($this->inline) {
        if (!isset($options['template'])) {
            $this->template = $this->inlineCheckboxListTemplate;
        } else {
            $this->template = $options['template'];
            unset($options['template']);
        }
        if (!isset($options['itemOptions'])) {
            $options['itemOptions'] = [
                'labelOptions' => ['class' => 'checkbox-inline'],
            ];
        }
    } elseif (!isset($options['item'])) {
        $itemOptions = isset($options['itemOptions']) ? $options['itemOptions'] : [];
        $encode = ArrayHelper::getValue($options, 'encode', true);
        $options['item'] = function ($index, $label, $name, $checked, $value) use ($itemOptions, $encode) {
            $options = array_merge([
                'label' => $encode ? Html::encode($label) : $label,
                'value' => $value
            ], $itemOptions);
            return '<div class="checkbox">' . Html::checkbox($name, $checked, $options) . '</div>';
        };
    }
    parent::checkboxList($items, $options);
    return $this;
}

            
createLayoutConfig() protected method

protected array createLayoutConfig ( $instanceConfig )
$instanceConfig array

The configuration passed to this instance's constructor

return array

The layout specific default configuration for this instance

                protected function createLayoutConfig($instanceConfig)
{
    $config = [
        'hintOptions' => [
            'tag' => 'p',
            'class' => 'help-block',
        ],
        'errorOptions' => [
            'tag' => 'p',
            'class' => 'help-block help-block-error',
        ],
        'inputOptions' => [
            'class' => 'form-control',
        ],
    ];
    $layout = $instanceConfig['form']->layout;
    if ($layout === 'horizontal') {
        $config['template'] = "{label}\n{beginWrapper}\n{input}\n{error}\n{endWrapper}\n{hint}";
        $cssClasses = array_merge([
            'offset' => 'col-sm-offset-3',
            'label' => 'col-sm-3',
            'wrapper' => 'col-sm-6',
            'error' => '',
            'hint' => 'col-sm-3',
        ], $this->horizontalCssClasses);
        if (isset($instanceConfig['horizontalCssClasses'])) {
            $cssClasses = ArrayHelper::merge($cssClasses, $instanceConfig['horizontalCssClasses']);
        }
        $config['horizontalCssClasses'] = $cssClasses;
        $config['wrapperOptions'] = ['class' => $cssClasses['wrapper']];
        $config['labelOptions'] = ['class' => 'control-label ' . $cssClasses['label']];
        $config['errorOptions']['class'] = 'help-block help-block-error ' . $cssClasses['error'];
        $config['hintOptions']['class'] = 'help-block ' . $cssClasses['hint'];
    } elseif ($layout === 'inline') {
        $config['labelOptions'] = ['class' => 'sr-only'];
        $config['enableError'] = false;
    }
    return $config;
}

            
inline() public method

public $this inline ( $value true )
$value boolean

Whether to render a inline list

return $this

The field object itself Make sure you call this method before checkboxList() or radioList() to have any effect.

                public function inline($value = true)
{
    $this->inline = (bool) $value;
    return $this;
}

            
label() public method

public void label ( $label null, $options = [] )
$label
$options

                public function label($label = null, $options = [])
{
    if (is_bool($label)) {
        $this->enableLabel = $label;
        if ($label === false && $this->form->layout === 'horizontal') {
            Html::addCssClass($this->wrapperOptions, $this->horizontalCssClasses['offset']);
        }
    } else {
        $this->enableLabel = true;
        $this->renderLabelParts($label, $options);
        parent::label($label, $options);
    }
    return $this;
}

            
radio() public method

public void radio ( $options = [], $enclosedByLabel true )
$options
$enclosedByLabel

                public function radio($options = [], $enclosedByLabel = true)
{
    if ($enclosedByLabel) {
        if (!isset($options['template'])) {
            $this->template = $this->form->layout === 'horizontal' ?
                $this->horizontalRadioTemplate : $this->radioTemplate;
        } else {
            $this->template = $options['template'];
            unset($options['template']);
        }
        if (isset($options['label'])) {
            $this->parts['{labelTitle}'] = $options['label'];
        }
        if ($this->form->layout === 'horizontal') {
            Html::addCssClass($this->wrapperOptions, $this->horizontalCssClasses['offset']);
        }
        $this->labelOptions['class'] = null;
    }
    return parent::radio($options, false);
}

            
radioList() public method

public void radioList ( $items, $options = [] )
$items
$options

                public function radioList($items, $options = [])
{
    if ($this->inline) {
        if (!isset($options['template'])) {
            $this->template = $this->inlineRadioListTemplate;
        } else {
            $this->template = $options['template'];
            unset($options['template']);
        }
        if (!isset($options['itemOptions'])) {
            $options['itemOptions'] = [
                'labelOptions' => ['class' => 'radio-inline'],
            ];
        }
    }  elseif (!isset($options['item'])) {
        $itemOptions = isset($options['itemOptions']) ? $options['itemOptions'] : [];
        $encode = ArrayHelper::getValue($options, 'encode', true);
        $options['item'] = function ($index, $label, $name, $checked, $value) use ($itemOptions, $encode) {
            $options = array_merge([
                'label' => $encode ? Html::encode($label) : $label,
                'value' => $value
            ], $itemOptions);
            return '<div class="radio">' . Html::radio($name, $checked, $options) . '</div>';
        };
    }
    parent::radioList($items, $options);
    return $this;
}

            
render() public method

public void render ( $content null )
$content

                public function render($content = null)
{
    if ($content === null) {
        if (!isset($this->parts['{beginWrapper}'])) {
            $options = $this->wrapperOptions;
            $tag = ArrayHelper::remove($options, 'tag', 'div');
            $this->parts['{beginWrapper}'] = Html::beginTag($tag, $options);
            $this->parts['{endWrapper}'] = Html::endTag($tag);
        }
        if ($this->enableLabel === false) {
            $this->parts['{label}'] = '';
            $this->parts['{beginLabel}'] = '';
            $this->parts['{labelTitle}'] = '';
            $this->parts['{endLabel}'] = '';
        } elseif (!isset($this->parts['{beginLabel}'])) {
            $this->renderLabelParts();
        }
        if ($this->enableError === false) {
            $this->parts['{error}'] = '';
        }
        if ($this->inputTemplate) {
            $input = isset($this->parts['{input}']) ?
                $this->parts['{input}'] : Html::activeTextInput($this->model, $this->attribute, $this->inputOptions);
            $this->parts['{input}'] = strtr($this->inputTemplate, ['{input}' => $input]);
        }
    }
    return parent::render($content);
}

            
renderLabelParts() protected method

protected void renderLabelParts ( $label null, $options = [] )
$label string|null

The label or null to use model label

$options array

The tag options

                protected function renderLabelParts($label = null, $options = [])
{
    $options = array_merge($this->labelOptions, $options);
    if ($label === null) {
        if (isset($options['label'])) {
            $label = $options['label'];
            unset($options['label']);
        } else {
            $attribute = Html::getAttributeName($this->attribute);
            $label = Html::encode($this->model->getAttributeLabel($attribute));
        }
    }
    if (!isset($options['for'])) {
        $options['for'] = Html::getInputId($this->model, $this->attribute);
    }
    $this->parts['{beginLabel}'] = Html::beginTag('label', $options);
    $this->parts['{endLabel}'] = Html::endTag('label');
    if (!isset($this->parts['{labelTitle}'])) {
        $this->parts['{labelTitle}'] = $label;
    }
}

            
staticControl() public method (available since version 2.0.5)

Renders Bootstrap static form control.

See also http://getbootstrap.com/css/#forms-controls-static.

public $this staticControl ( $options = [] )
$options array

The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. There are also a special options:

  • encode: bool, whether value should be HTML-encoded or not.
return $this

The field object itself

                public function staticControl($options = [])
{
    $this->adjustLabelFor($options);
    $this->parts['{input}'] = Html::activeStaticControl($this->model, $this->attribute, $options);
    return $this;
}