ActiveField Widget ActiveField.php

Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

The enhanced ActiveForm and ActiveField widget allows you to control specific Bootstrap 3 features for Horizontal Forms, Input Groups, and includes more customized inputs.

Important

This widget can be also installed in isolation outside this bundle if needed. In addition to using via \kartik\widgets namespace, this widget can be also installed from the yii2-widget-activeform repository and can also be accessed via \kartik\form\ActiveForm or \kartik\form\ActiveField namespaces.

Pre-Requisites

The kartik\widgets\ActiveForm widget requires the extended kartik\widgets\ActiveField widget to provide all functionality. Ensure, this pre-requisite is complied with in your widget calls. Any customization should be done by extending these kartik\widgets\ActiveForm or kartik\widgets\ActiveField classes.

NOTE

No additional client assets or scripts (except a 1KB CSS file) are registered with this extension. So there is virtually no performance overhead due to additional Javascript or Cascading Style Sheets. The widget requires the default bootstrap 3.0 assets that are automatically registered with your Yii 2.0 install.

For explanation on using complex form layouts (e.g. inline form fields with bootstrap horizontal form), you can refer this web-tip.

Extend form controls by adding text or buttons before, after, or on both sides of any text-based input. You can configure addons by passing the addon property to your field's inputOptions. You can set the following parameters for the addon property:

  • prepend: array the prepend addon configuration, where you set the following keys:

    • content: string the prepend addon content

    • asButton: boolean whether the addon is a button or button group. Defaults to false.

    • options: array HTML attributes for the prepend addon

  • append: array the append addon configuration, where you set the following keys:

    • content: string the append addon content

    • asButton: boolean whether the addon is a button or button group. Defaults to false.

    • options: array HTML attributes for the append addon

  • groupOptions: array HTML options for the input group

  • contentBefore: string content placed before addon. This is not HTML encoded.

  • contentAfter: string content placed after addon. This is not HTML encoded.

@
echo $form->field($model, 'email', [
    'addon' => ['prepend' => ['content'=>'@']]
]);
.00
echo $form->field($model, 'amount_paid', [
    'addon' => ['append' => ['content'=>'.00']],
]);
echo $form->field($model, 'phone', [
    'addon' => ['prepend' => ['content'=>'<i class="glyphicon glyphicon-phone"></i>']]
]);
echo $form->field($model, 'include_text', [
    'addon' => ['prepend' => ['content'=>'<input type="checkbox">']]
]);
echo $form->field($model, 'username', [
    'addon' => [
        'append' => [
            'content' => Html::button('Go', ['class'=>'btn btn-primary']), 
            'asButton' => true
        ]
    ]
]);
echo $form->field($model, 'username', [
    'addon' => [
        'append' => [
            'content' => \yii\bootstrap\ButtonDropdown::widget([
                'label' => 'Action',
                'dropdown' => [
                    'items' => [
                        ['label' => 'Another action', 'url' => '#'],
                        ['label' => 'Something else', 'url' => '#'],
                        '<li class="divider"></li>',
                        ['label' => 'Separated link', 'url' => '#'],
                    ],
                ],
                'options' => ['class'=>'btn-default']
            ]),
            'asButton' => true
        ]
    ]
]);
echo $form->field($model, 'username', [
    'addon' => [
        'append' => [
            'content' => 
                \yii\bootstrap\Button::widget([
                    'label'=>'Car', 
                    'options'=>['class'=>'btn btn-default']
                ]) . PHP_EOL .
                \yii\bootstrap\Button::widget([
                    'label'=>'Bus', 
                    'options'=>['class'=>'btn btn-default']
                ]) . PHP_EOL .
                \yii\bootstrap\ButtonDropdown::widget([
                    'label' => 'Air',
                    'dropdown' => [
                        'items' => [
                            ['label' => 'Another action', 'url' => '#'],
                            ['label' => 'Something else', 'url' => '#'],
                            '<li class="divider"></li>',
                            ['label' => 'Separated link', 'url' => '#'],
                        ],
                    ],
                    'options' => ['class'=>'btn-default']
                ]),
            'asButton' => true
        ]
    ]
]);
echo $form->field($model, 'date_1', [
    'addon' => [
        'prepend' => ['content'=>'<i class="glyphicon glyphicon-calendar"></i>'],
        'append' => ['content'=>'<button class="btn btn-default">Go</button>', 'asButton'=>true]
    ]
]);

You can control the following settings for the input group addons by passing the following additional properties to the addon configuration:

  • groupOptions: array the HTML attributes of the input group container enclosing the addons

  • contentBefore: string any content you want to place before the addon (this is not HTML encoded)

  • contentAfter: string any content you want to place after the addon (this is not HTML encoded)

You can also control the HTML attributes of your prepend and append addons by setting the options within the prepend and append configuration.

$.00
to
// Controlling addon HTML options
echo $form->field($model, 'amount_paid', [
    'addon' => [ 
        'prepend' => ['content' => '$', 'options'=>['class'=>'alert-success']],
        'append' => ['content' => '.00', 'options'=>['style' => 'font-family: Monaco, Consolas, monospace;']],
    ]
]);

// Displaying a LARGE input
echo $form->field($model, 'date_3', [
    'addon' => [
        'append' => ['content' => 'to'],
        'groupOptions' => ['class'=>'input-group-lg'],
        'contentAfter' => '<input type="text" id="date-to" class="form-control" placeholder="End Date">'
    ]
]);

These form inputs have been specifically extended for Bootstrap 3.0 and also include the new HTML 5 inputs.

View a complete demo on HTML5 inputs.

Handle automatic offsetting of checkbox inputs for Horizontal Forms. As an example, check the Remember Me input below.

<?php 
    $form = ActiveForm::begin([
        'id' => 'login-form', 
        'type' => ActiveForm::TYPE_HORIZONTAL,
        'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL]
    ]); 
?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <?= $form->field($model, 'rememberMe')->checkbox() ?>
    <div class="form-group">
        <div class="col-sm-offset-3 col-sm-9">
            <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?>
        </div>
    </div>
<?php ActiveForm::end(); ?>

Handle automatic offsetting of radio inputs for Horizontal Forms. As an example, check the Yes and No inputs below.

<?php 
    $form = ActiveForm::begin([
        'id' => 'login-form', 
        'type' => ActiveForm::TYPE_HORIZONTAL,
        'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL]
    ]); 
?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <?= $form->field($model, 'yes')->radio() ?>
    <?= $form->field($model, 'no')->radio() ?>
    <div class="form-group">
        <div class="col-sm-offset-3 col-sm-9">
            <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?>
        </div>
    </div>
<?php ActiveForm::end(); ?>

Use this to generate a stacked checkbox list or an inline checkbox list. For an inline checkbox list set the inline option to true.

Stacked Checkbox List
Inline Checkbox List
$form = ActiveForm::begin([
    'id' => 'login-form', 
    'type' => ActiveForm::TYPE_HORIZONTAL,
    'formConfig' => ['labelSpan' => 3, 'spanSize' => ActiveForm::SIZE_SMALL]
]); 

$list = [0 => 'Morning', 1 => 'Noon', 2 => 'Evening'];

/* Display a stacked checkbox list */
echo $form->field($model, 'contact')->checkboxList($list);

/* Display an inline checkbox list */
echo $form->field($model, 'contact')->checkboxList($list, ['inline'=>true]);

ActiveForm::end();

Use this to generate a stacked radio list or an inline radio list. For an inline radio list set the inline option to true.

Stacked Radio List
Inline Radio List
$form = ActiveForm::begin([
    'id' => 'login-form', 
    'type' => ActiveForm::TYPE_HORIZONTAL,
    'formConfig' => ['labelSpan' => 3, 'spanSize' => ActiveForm::SIZE_SMALL]
]); 

$list = [0 => 'Morning', 1 => 'Noon', 2 => 'Evening'];

/* Display a stacked checkbox list */
echo $form->field($model, 'contact')->checkboxList($list);

/* Display an inline checkbox list */
echo $form->field($model, 'contact')->checkboxList($list, ['inline'=>true]);

ActiveForm::end();

Use this when you need to place plain text with a form label within a vertical or horizontal form. As an example, check the Email Address control below for a horizontal form.

email@example.com

?php 
    $form = ActiveForm::begin([
        'id' => 'login-form', 
        'type' => ActiveForm::TYPE_HORIZONTAL,
        'formConfig' => ['labelSpan' => 3, 'spanSize' => ActiveForm::SIZE_SMALL]
    ]); 
?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'email')->staticInput() ?>
<?php ActiveForm::end(); ?>

Allows the new HTML 5 inputs to be displayed and offset for horizontal form orientation. The range input (slider control) is handled separately through the rangeInput function.

Browser Support

Not all major browsers support all the new HTML 5 input types. However, you can already start using them. If they are not supported, they will behave as regular text fields. For example, if you are currently using the Google Chrome browser you should be able to see the color and date controls in the example below. For more information on HTML 5 inputs click here.

View a complete demo on HTML5 inputs.

$form = ActiveForm::begin([
    'id' => 'login-form', 
    'type' => ActiveForm::TYPE_HORIZONTAL,
    'formConfig' => ['labelSpan' => 6, 'spanSize' => ActiveForm::SIZE_SMALL]
]); 

/* Color input - works with Firefox, Google Chrome & Opera*/
echo $form->field($model, 'color')->input('color');

/* Number input - works with Firefox, Google Chrome, Safari & Opera*/
$form->field($model, 'rating')->input('number', ['min'=>1, 'max'=>5, 'placeholder' => 'Enter a rating between 1 and 5...']) ?>

/* Email input - works with Google Chrome & Opera*/
echo $form->field($model, 'email_1')->input('email', ['placeholder'=>'Enter a valid email...'])

/* Date selector input - works with Google Chrome & Opera */
echo $form->field($model, 'birthday')->input('date');

ActiveForm::end();

The multi select is special control extending the Yii checkboxList and radioList. It generates a scrolling multi select list box with checkboxes or radio for selection. The list array can be populated just like any Yii dropDownList. The advantage of this multi-select is that it allows the labels to be HTML formatted. For the usage examples in this demo, the following HTML formatted values are used to populate this multi-select list.
use kartik\helpers\Html;
$model->icons = [
    'align-left' => Html::icon('align-left') . ' Align Left',
    'align-center' => Html::icon('align-center') . ' Align Center',
    'align-right' => Html::icon('align-right') . ' Align Right',
    'align-justify' => Html::icon('align-justify') . ' Align Justify',
    'arrow-down' => Html::icon('arrow-down') . ' Direction Down',
    'arrow-up' => Html::icon('arrow-up') . ' Direction Up',
    'arrow-left' => Html::icon('arrow-left') . ' Direction Left',
    'arrow-right' => Html::icon('arrow-right') . ' Direction Right',
];

Call the multi select like any other dropdown or text control for a vertical form orientation. Note that by default the control displays checkboxes to select values.

$form = ActiveForm::begin([
    'id' => 'login-form', 
    'type' => ActiveForm::TYPE_VERTICAL
]); 
echo $form->field($model, 'select_data')->multiselect($model->icons);
ActiveForm::end();

The multi select control is automatically offset for the horizontal form type. Note that by default the control displays checkboxes to select values.

$form = ActiveForm::begin([
    'id' => 'login-form', 
    'type' => ActiveForm::TYPE_HORIZONTAL,
    'formConfig' => ['labelSpan' => 3, 'spanSize' => ActiveForm::SIZE_SMALL]
]);
echo $form->field($model, 'select_data')->multiselect($model->icons);
ActiveForm::end();

Change the multi select to show radios instead of checkboxes by setting the selector property.

$form = ActiveForm::begin([
    'id' => 'login-form'
]); 
echo $form->field($model, 'select_data')->multiselect($model->icons, ['selector'=>'radio']);
ActiveForm::end();

By default the control displays a height of 145px. You can override this by setting the height property under the control options. You can also set additional html options by configuring container within the control options array.

$form = ActiveForm::begin([
    'id' => 'login-form', 
    'type' => ActiveForm::TYPE_VERTICAL
]); 
echo $form->field($model, 'select_data')->multiselect($model->icons, [
    'height' => '225px',
    'container' => ['class' => 'bg-white']
]);
ActiveForm::end();