ActiveForm Widget ActiveForm.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.

Generates a vertical form orientation. You need to set the type parameter to ActiveForm::TYPE_HORIZONTAL.

NOTE

This is the default orientation if type is not set.

You can set formConfig additionally as:

  • showLabels Whether to show field labels
<?php 
    $form = ActiveForm::begin([
        'id' => 'login-form-vertical', 
        'type' => ActiveForm::TYPE_VERTICAL
    ]); 
?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <?= $form->field($model, 'rememberMe')->checkbox() ?>
    <div class="form-group">
        <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?>
        <?= Html::resetButton('Reset', ['class' => 'btn btn-default']) ?>
    </div>
<?php ActiveForm::end(); ?>

Generates a horizontal form orientation as set in type. You need to set the type parameter to ActiveForm::TYPE_HORIZONTAL.

NOTE

For horizontal forms, you need to set formConfig appropriately as per your user interface needs.

The available formConfig options are:

  • labelSpan The numeric grid width of the label part (integer between 1 to 12)
  • deviceSize Applicable device size (one of the ActiveForm size constants below). Check the bootstrap grid class prefix for more details.
    • SIZE_TINY = 'xs'
    • SIZE_SMALL = 'sm'
    • SIZE_MEDIUM = 'md'
    • SIZE_LARGE = 'lg'
The formConfig parameters are used to generate the grid layout with the correct offsets required for the horizontal layout. This is of the form: .col-{deviceSize}-{labelSpan}. For example .col-md-2 will be generated if labelSpan is 2 and deviceSize = ActiveForm::SIZE_MEDIUM.

<?php 
    $form = ActiveForm::begin([
        'id' => 'login-form-horizontal', 
        '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']) ?>
            <?= Html::resetButton('Reset', ['class' => 'btn btn-default']) ?>
        </div>
    </div>
<?php ActiveForm::end(); ?>

Generates an inline form orientation. You need to set the type parameter to ActiveForm::TYPE_INLINE.

<?php 
    $form = ActiveForm::begin([
        'id' => 'login-form-inline', 
        'type' => ActiveForm::TYPE_INLINE
    ]); 
?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <?= $form->field($model, 'rememberMe')->checkbox() ?>
    <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?>
    <?= Html::resetButton('Reset', ['class' => 'btn btn-default']) ?>	
<?php ActiveForm::end(); ?>

Note

You cannot typically configure the template property through the fieldConfig property nor the active field's template property for this widget when using different orientation other than vertical. The formConfig property allows you to overcome this, by adding ability to control display of labels and validation errors, and controlling input offsets for horizontal forms.

All settings and properties for \yii\widgets\ActiveForm can be used in this widget. In addition the additional properties available with \kartik\widgets\ActiveForm are:

  • type: string form orientation type as supported for Bootstrap 3 styling. Must be one of the following values:

    • 'vertical' or ActiveForm::TYPE_VERTICAL

    • 'horizontal' or ActiveForm::TYPE_HORIZONTAL

    • 'inline' or ActiveForm::TYPE_INLINE

  • fullSpan: int the Bootstrap full span grid width. Defaults to 12. You can override for custom grid layouts.

  • formConfig: array the additional configuration for the form widget. The following properties are supported

    • labelSpan: int the grid width for the label part when the form type is of ActiveForm::TYPE_HORIZONTAL orientation. Should be a number between 1 and fullSpan. Defaults to 2. This is useful in HORIZONTAL forms for setting the label width and offsetting the input.

    • deviceSize: int the device size to render the grid columns for. Should be one of the bootstrap size modifiers below. Defaults to ActiveForm::SIZE_MEDIUM.

      • 'xs' or ActiveForm::SIZE_TINY

      • 'sm' or ActiveForm::SIZE_SMALL

      • 'md' or ActiveForm::SIZE_MEDIUM

      • 'lg' or ActiveForm::SIZE_LARGE

      This is useful again in HORIZONTAL forms for setting the device size.
    • showLabels: boolean whether to show field labels. Defaults to true. This is useful in INLINE forms, where it defaults to false. The autoPlaceholder property for INLINE forms in fieldConfig is defaulted to true.

    • showErrors: boolean whether to show yii field validation errors. Defaults to true, except for INLINE forms where it defaults to false.

For example, compare the inline form in the previous section above and the one below.

No validation error messages are shown on the inline-form in the previous section (the default behavior). While in the inline-form below, with showErrors set to true in formConfig, the validation errors are displayed.

TIP To easily display a validation error just click in and out of the username or password fields.

<?php 
    $form = ActiveForm::begin([
        'id' => 'login-form-inline', 
        'type' => ActiveForm::TYPE_INLINE,
        'formConfig' => ['showErrors' => true]
    ]); 
?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <?= $form->field($model, 'rememberMe')->checkbox() ?>
    <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?>
    <?= Html::resetButton('Reset', ['class' => 'btn btn-default']) ?>	
<?php ActiveForm::end(); ?>