Krajee

Builder Details Form Grid Builder

Thankful to Krajee! BUY A COFFEEor to get more out of us.

The yii2-builder package provides a couple of great form builder utilities for Yii Framework 2.0. The extension allows you to build both single-row and multi-row/tabular forms for Yii Framework 2.0. It also offers good compatibility with the grid system, form layouts, and table styles of Bootstrap 5.x / 4.x / 3.x.

Tip

Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)

FormGrid supports configuration of the bootstrap library version so that you can use this either with any Bootstrap version 3.x and above. For setting up the bootstrap version for your extension, you can configure the FormGrid::bsVersion property to one of the following.

  • To use with bootstrap 3 library - you can set FormGrid::bsVersion property to any string starting with 3 (e.g. 3 or 3.3.7 or 3.x)

  • To use with bootstrap 4 library - you can set FormGrid::bsVersion property to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)

  • To use with bootstrap 5 library - you can set FormGrid::bsVersion property to any string starting with 5 (e.g. 5 or 5.1.0 or 5.x)

The following sections describe the pre-requisites for enabling Bootstrap library specific version support in your application and other related controls/overrides.

Global Bootstrap Version


Generally, you may also want to set a default version globally for all Krajee Extensions (instead of setting it for each widget or extension separately). In order to do this, you can setup the bsVersion property within Yii 2 application params (i.e. Yii::$app->params['bsVersion']). To set this up, add this section of code to your application params configuration file (e.g. config/params.php):

'params' => [
    'bsVersion' => '5.x', // this will set globally `bsVersion` to Bootstrap 5.x for all Krajee Extensions
    // other settings
    // 'adminEmail' => 'admin@example.com'
]

If FormGrid::bsVersion property is set, in addition to Yii::$app->params['bsVersion'], the extension level setting (FormGrid::bsVersion property) will override the Yii::$app->params['bsVersion']. If FormGrid::bsVersion property is not set, and Yii::$app->params['bsVersion'] is also not set, FormGrid::bsVersion property will default to 3.x (i.e. Bootstrap 3.x version will be assumed as default).

Yii2 Bootstrap Dependency


You need to install one of yiisoft/yii2-bootstrap or yiisoft/yii2-bootstrap4 or yiisoft/yii2-bootstrap5 extensions manually in your application to enable Bootstrap 3.x or 4.x or 5.x functionality respectively. This dependency has not been pre-built into the composer configuration for Krajee extensions, to allow better control to the developers in configuring their bootstrap library version. If bsVersion is set to 5.x and yiisoft/yii2-bootstrap5 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap5 extension. If bsVersion is set to 4.x and yiisoft/yii2-bootstrap4 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap4 extension. Similarly, if bsVersion is set to 3.x and yiisoft/yii2-bootstrap is not installed, an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap extension.

To install yiisoft/yii2-bootstrap5, add the repo to the require section of your application's composer.json.

"yiisoft/yii2-bootstrap5": "@dev"

To install yiisoft/yii2-bootstrap4, add the repo to the require section of your application's composer.json.

"yiisoft/yii2-bootstrap4": "@dev"

To install yiisoft/yii2-bootstrap, add the repo to the require section of your application's composer.json.

"yiisoft/yii2-bootstrap": "@dev"

Override Bootstrap CSS/JS


The Krajee extension asset bundle(s) by default depend on one of the following asset bundles to load the Bootstrap CSS and JS:

  • yii\bootstrap\BootstrapAsset and/or yii\bootstrap\BootstrapPluginAsset for bootstrap 3.x (bsVersion = 3 setting)

  • yii\bootstrap4\BootstrapAsset and/or yii\bootstrap4\BootstrapPluginAsset for bootstrap 4.x ( bsVersion = 4 setting)

  • yii\bootstrap5\BootstrapAsset and/or yii\bootstrap5\BootstrapPluginAsset for bootstrap 5.x (bsVersion = 5 setting)

This is controlled by the property bsDependencyEnabled within the asset bundle (which defaults to true). One can override this and prevent the default yii2 bootstrap assets (CSS & JS) from loading by doing one or all of the following:

  • Global Override: Set Yii::$app->params['bsDependencyEnabled'] to false in your Yii 2 application config params.php. This setting will be applied for all Krajee Extension Asset Bundles that depend on Bootstrap assets.

    'params' => [
        'bsDependencyEnabled' => false, // this will not load Bootstrap CSS and JS for all Krajee extensions
        // you need to ensure you load the Bootstrap CSS/JS manually in your view layout before Krajee CSS/JS assets
        //
        // other params settings below
        // 'bsVersion' => '5.x',
        // 'adminEmail' => 'admin@example.com'
    ]
    
  • Asset Bundle Specific Override: Set bsDependencyEnabled to false for the specific asset bundle within Yii2 Asset Manager component in your Yii 2 application config file.

    // ...
    'components' => [
        'assetManager' => [
            'bundles' => [
                'kartik\form\ActiveFormAsset' => [
                    'bsDependencyEnabled' => false // do not load bootstrap assets for a specific asset bundle
                ],
            ],
        ],
    ],
    

Note

When setting bsDependencyEnabled to false, you need to ensure that your app code/view layout loads the Bootstrap CSS and JS on your view before the Krajee CSS/JS are loaded to ensure that the Krajee extension JS plugins and CSS styles do not get broken.

Icons for Bootstrap


Bootstrap 5.x / 4.x does not include glyphicons or any other icons framework bundled with the library. Krajee extensions therefore will use Font Awesome 5.x icons instead of glyphicons when working with Bootstrap 5.x / 4.x. You can download Font Awesome 5.x icons from the icons website. Alternatively, you can load the free version of Font Awesome from their CDN.

For Krajee extensions and demos, the Font Awesome Free version is used and loaded as the Icons Display Package on all the Yii2 demo layouts. To include font awesome assets on your page, include the following markup on the HEAD section of your view layout file, when bsVersion is set to 4.x or 5.x.

  • Option 1: Font CSS version of Font Awesome:

    <!-- on your view layout file HEAD section -->
    <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.3.1/css/all.css">
    
  • Option 2: SVG / JS version of Font Awesome (recommended for cleaner scaling vector icons and features like icon layers):

    <!-- on your view layout file HEAD section -->
    <script defer src="https://use.fontawesome.com/releases/v5.3.1/js/all.js" crossorigin="anonymous"></script>
    

    Alternatively, you can use the FontAwesomeAsset from the kartik-v/yii2-icons package to load the SVG/JS version.

    // on your view layout file
    use kartik\icons\FontAwesomeAsset;
    FontAwesomeAsset::register($this);
    
The Form Grid Builder widget accepts similar settings to a Form widget, with some easier configuration and options to avoid code repetition. You basically can setup the rows for each bootstrap grid row and the grid columns can be auto generated, based on attribute settings for each row. The following settings are important:
  • bsVersion: string | int, the bootstrap library version to be used for the extension. Refer the Bootstrap Info section for details and pre-requisites on setting this property.

    • To use with Bootstrap library - you can set this to any string starting with 3 (e.g. 3 or 3.3.7 or 4.x / 3.x)

    • To use with bootstrap 4 - you can set this to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)

    • To use with bootstrap 5 - you can set this to any string starting with 4 (e.g. 5 or 5.1.0 or 5.x)

  • bsColCssPrefixes: array, the bootstrap grid column css prefixes mapping, the key is the bootstrap versions, and the value is an array containing the sizes and their corresponding grid column css prefixes. The class using this trait, must implement kartik\base\BootstrapInterface. If not set will default to:.

    [
       3 => [
          self::SIZE_X_SMALL => 'col-xs-',
          self::SIZE_SMALL => 'col-sm-',
          self::SIZE_MEDIUM => 'col-md-',
          self::SIZE_LARGE => 'col-lg-',
          self::SIZE_X_LARGE => 'col-lg-',
          self::SIZE_XX_LARGE => 'col-lg-',
       ],
       4 => [
          self::SIZE_X_SMALL => 'col-',
          self::SIZE_SMALL => 'col-sm-',
          self::SIZE_MEDIUM => 'col-md-',
          self::SIZE_LARGE => 'col-lg-',
          self::SIZE_X_LARGE => 'col-xl-',
          self::SIZE_XX_LARGE => 'col-xl-',
       ],
       5 => [
          self::SIZE_X_SMALL => 'col-',
          self::SIZE_SMALL => 'col-sm-',
          self::SIZE_MEDIUM => 'col-md-',
          self::SIZE_LARGE => 'col-lg-',
          self::SIZE_X_LARGE => 'col-xl-',
          self::SIZE_XX_LARGE => 'col-xxl-',
       ],
    ];
    
  • model Model, or ActiveRecord, model instance extending from yii\base\Model or yii\db\ActiveRecord. This is mandatory.

  • form ActiveForm, the ActiveForm instance extending from kartik orm\ActiveForm. You normally would call it as \$form = \kartik orm\ActiveForm::begin();. This is mandatory.

  • formName string, the form name to be provided if not using with model and ActiveForm. One of form and model OR formName is mandatory.

  • attributeDefaults array, the default settings that will be applied for all attributes. The array will be configured similar to a single attribute setting value in the \$attributes array. One will typically default markup and styling like type, container, prepend, append etc. For example:

    // settings for horizontal form used without active form
    'attributeDefaults' => [
        'type' => Form::INPUT_TEXT,
        'labelOptions' => ['class'=>'col-md-2'],
        'inputContainer' => ['class'=>'col-md-10'],
    ]
    

    Note: The settings at the \$attributes level will override these default settings.

  • rows array, the most important part of your form grid builder configuration. This is mandatory. Each row (item) in this array, will be an array itself, that will consist of the widget properties required for the Form widget. Typically you can just pass the attributes for each row, and others can be defaulted from the FormGrid settings.

  • columns integer, the number of columns in which to split the fields horizontally. If not set, defaults to 1 column. This property can be overridden at the rows configuration level for each row.

  • autoGenerateColumns boolean, whether to auto calculate and generate the columns based on the count of attributes for each row. If not set, Defaults to true. If the count of attributes is > FormGrid::GRID_WIDTH (12) then no further columns will be generated. This property can be overridden at the rows configuration level for each row.

  • columnSize string, the bootstrap device size for rendering each Bootstrap grid column. Applicable Defaults to `Form::SIZE_SMALL`. Can take in one of these options:

    • 'xs' or Form::SIZE_X_SMALL

    • 'sm' or Form::SIZE_SMALL

    • 'md' or Form::SIZE_MEDIUM

    • 'lg' or Form::SIZE_LARGE

    • 'xl' or Form::SIZE_X_LARGE

  • columnOptions array, the HTML attributes for the grid columns. Applicable only if columns is greater than 1. The following special options are recognized:

    • colspan integer, the customized grid column span to use if you need assymmetric field columns in your layout. For the default bootstrap grid this is a number between 1 to 12.

  • rowOptions integer, the HTML attributes for the grid rows. Applicable only if columns is greater than 1.

  • options integer, the HTML attributes for the field/attributes container. The following options are additionally recognized:

    • tag: string, the HTML tag for the container. Defaults to fieldset.

Rendering a complex grid layout with FormGrid easily. In this you can have single, double or multi columns within the same form. You may also be planning to use various input types for your design and place as you want on your layouts. In order to achieve these, you can call the Form::widget multiple times with different settings as described below.

Note

This example contains usage of various input types, including the INPUT_RAW example at the end. Note you can use INPUT_RAW type to define your own custom attributes. It also shows an example of how you can add hints to your active field attributes.
Scenario 3 Output
Account Info
Profile Info
Enter birthday (mm/dd/yyyy)
Type and select state
Choose your color
use kartik\form\ActiveForm;
use kartik\builder\Form;
use kartik\builder\FormGrid;
$form = ActiveForm::begin(['type'=>ActiveForm::TYPE_VERTICAL]);
echo FormGrid::widget([
    'model'=>$model,
    'form'=>$form,
    'autoGenerateColumns'=>true,
    'rows'=>[
        [
            'contentBefore'=>'<legend class="text-info"><small>Account Info</small></legend>',
            'attributes'=>[       // 2 column layout
                'username'=>['type'=>Form::INPUT_TEXT, 'options'=>['placeholder'=>'Enter username...']],
                'password'=>['type'=>Form::INPUT_PASSWORD, 'options'=>['placeholder'=>'Enter password...']],
            ]
        ],
        [
            'attributes'=>[       // 1 column layout
                'notes'=>['type'=>Form::INPUT_TEXTAREA, 'options'=>['placeholder'=>'Enter notes...']],
            ],
        ],
        [
            'contentBefore'=>'<legend class="text-info"><small>Profile Info</small></legend>',
            'columns'=>3,
            'autoGenerateColumns'=>false, // override columns setting
            'attributes'=>[       // colspan example with nested attributes
                'address_detail' => [ 
                    'label'=>'Address',
                    'labelOptions' => ['class' => 'is-required'], // displays the required asterisk
                    'columns'=>6,
                    'attributes'=>[
                        'address'=>[
                            'type'=>Form::INPUT_TEXT, 
                            'options'=>['placeholder'=>'Enter address...'],
                            'columnOptions'=>['colspan'=>3],
                        ],
                        'zip_code'=>[
                            'type'=>Form::INPUT_TEXT, 
                            'options'=>['placeholder'=>'Zip...'],
                            'columnOptions'=>['colspan'=>2],
                        ],
                        'phone'=>[
                            'type'=>Form::INPUT_TEXT, 
                            'options'=>['placeholder'=>'Phone...']
                        ],
                    ]
                ]
            ],
        ],
        [
            'attributes'=>[
                'birthday'=>['type'=>Form::INPUT_WIDGET, 'widgetClass'=>'\kartik\widgets\DatePicker', 'hint'=>'Enter birthday (mm/dd/yyyy)'],
                'state_1'=>['type'=>Form::INPUT_DROPDOWN_LIST, 'items'=>$model->typeahead_data, 'hint'=>'Type and select state'],
                'color'=>['type'=>Form::INPUT_WIDGET, 'widgetClass'=>'\kartik\color\ColorInput', 'hint'=>'Choose your color'],
            ]
        ],
        [
            'attributes'=>[       // 3 column layout
                'rememberMe'=>[   // radio list
                    'type'=>Form::INPUT_RADIO_LIST, 
                    'items'=>[true=>'Yes', false=>'No'], 
                    'options'=>['inline'=>true]
                ],
                'brightness'=>[   // uses widget class with widget options
                    'type'=>Form::INPUT_WIDGET, 
                    'label'=>Html::label('Brightness (%)'), 
                    'widgetClass'=>'\kartik\range\RangeInput',
                    'options'=>['width'=>'80%']
                ],
                'actions'=>[    // embed raw HTML content
                    'type'=>Form::INPUT_RAW, 
                    'value'=>  '<div style="text-align: right; margin-top: 20px">' . 
                        Html::resetButton('Reset', ['class'=>'btn btn-secondary btn-default']) . ' ' .
                        Html::submitButton('Submit', ['class'=>'btn btn-primary']) . 
                        '</div>'
                ],
            ],
        ],
    ]
    ]
]);
ActiveForm::end();

Note

You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.

The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.

 
visitors to Krajee Yii2 Demos since 22-May-2017