ActiveForm Widget ActiveForm.php   Tips

Latest Stable Version Latest Unstable Version Total Downloads Monthly Downloads Daily Downloads
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 widget and ActiveField component 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 component 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.

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: boolean | string. Whether to show field labels. Should be one of the following values:

    • true: show labels for fields

    • false: hide labels for fields

    • ActiveForm::SCREEN_READER: show in screen reader only (hide from normal display)

<?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 | string. Whether to show field labels. Should be one of the following values:

      • true: show labels for fields

      • false: hide labels for fields

      • ActiveForm::SCREEN_READER: show in screen reader only (hide from normal display)

      Defaults to true. This is useful in INLINE forms, where it defaults to ActiveForm::SCREEN_READER. 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.

    • showHints: boolean whether to show hints for each field. Defaults to true. The hint will be rendered only if a valid hint has been set through the hint() method.

  • staticOnly: boolean whether all inputs in form are to be set as static only. Defaults to false. This property takes precedence over disabled or readonly.

  • disabled: boolean whether all inputs in form are to be disabled. Defaults to false.

  • readonly: boolean whether all inputs in form are to be readonly. 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.

Active Field Configuration

The following properties of the ActiveField will help configure the layout specially in combination with and/or without the settings above:

  • horizontalCssClasses: array, 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

    These options are compatible and similar to \yii\bootstrap\ActiveForm and provide a complete flexible container. If labelSpan is set in ActiveForm::formConfig and wrapper is also set, then both css options are concatenated. If wrapper contains a 'col-' class wrapper, it overrides the tag from labelSpan.

  • template: string, inherits and overrides values from parent class. This defaults to {label} {beginWrapper} {input} {hint} {error} {endWrapper}. The following tokens are supported:

    • {beginLabel}: Container begin tag for labels (to be used typically along with {labelTitle} token, when you do not wish to directly use the {label} token).

    • {labelTitle}: Label content without tags (to be used typically when you do not wish to directly use the {label} token).

    • {endLabel}: Container end tag for labels (to be used typically with {labelTitle} token, when you do not wish to directly use the {label} token).

    • {label}: Full label content enclosed within the label tag.

    • {beginWrapper}: Container for input,error and hint start tag. Uses a <div> tag if there is a input wrapper CSS detected, else defaults to empty string.

    • {input}: placeholder for input control

    • {hint}: placeholder for hint/help text including sub container

    • {error}: placeholder for error text including sub container

    • {endWrapper}: end tag for {beginWrapper}. Defaults to </div>, if there is a input wrapper CSS detected, else defaults to empty string.

A few examples of configuring a custom template for your bootstrap horizontal active form could look like:

// with labelSpan and deviceSize
echo $form->->field($model, 'email', ['labelSpan' => 2, 'deviceSize' => ActiveForm::SIZE_SMALL]]);

// using horizontalCssClasses
echo $form->->field($model, 'amount_paid', ['horizontalCssClasses' => ['wrapper' => 'hidden-xs']]);
echo $form->->field($model, 'phone', [
    'horizontalCssClasses' => ['label' => 'col-md-2 col-sm-3 col-xs-12 myRedClass']
]);

// using template 
echo $form->->field($model, 'special', [
    'template' => '{beginLabel}For: {labelTitle}{endLabel}\n{beginWrapper}\n{input}\n{hint}\n{error}\n{endWrapper}'
]);
 

<?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(); ?>