yii2-grid

Yii2 GridView on steroids. A module with various modifications and enhancements to one of the most used widgets by Yii developers. The widget contains new additional Grid Columns with enhanced settings for Yii Framework 2.0. The widget also incorporates various Bootstrap 3.x styling options. Refer detailed documentation and/or a complete demo.

Latest Release

The latest version of the module is v2.6.0 released on 20-Nov-2014. Refer the CHANGE LOG for details.

Release 2.6.0 has changes that would break backward compatibility. These changes have been done to make the templates more efficient, configurable, and enable developers to setup the grid layout better.

BC Breaking Changes (from v2.6.0)

1. Removed showFooter from panel array configuration. This can be now configured with footer option within the panel.
2. Removed layout from panel array configuration. This can be now configured with panelTemplate at the GridView level.
3. Renamed beforeTemplate property to panelBeforeTemplate.
4. Renamed afterTemplate property to panelAfterTemplate.
5. Renamed beforeContent tag used in panelBeforeTemplate to before.
6. Renamed afterContent tag to panelAfterTemplate to after.
7. EditableColumn attribute naming convention has changed. Developers do not need to use Model::loadMultiple method anymore and have the ability to directly use the $model->load method.

Additions (in v2.6.0)

1. Templates have been simplified and consolidated to the following configurable properties:
   • panelTemplate: Template to render the complete grid panel.
   • panelHeadingTemplate: Template to render the heading block part of the panel.
   • panelBeforeTemplate: Template to render the before block part of the panel.
   • panelAfterTemplate: Template to render the after block part of the panel.
   • panelFooterTemplate: Template to render the footer block part of the panel.
2. The heading, footer, before, and after properties in the panel typically accepts a string to render in that particular block. All of these can be set to boolean false to hide them.
3. HTML attributes for each of the above containers are now configurable i.e via headingOptions, footerOptions, beforeOptions, and afterOptions properties in the panel array configuration.
4. Vast enhancements to CSS styling when using Float Table Header wrapper. This now ensures tables auto fits and expand rightly to fit inside the panel.

NOTE: This extension depends on other yii2 extensions based on the functionality chosen by you. It will not install such dependent packages by default, but will prompt through an exception, if accessed. For example, if you choose to enable PDF export, then the yii2-mpdf will be mandatory and exception will be raised if yii2-mpdf is not installed. Check the composer.json for other extension dependencies.

Module

The extension has been created as a module to enable access to advanced features like download actions (exporting as csv, text, html, or xls). You should configure the module with a name of gridview as shown below:

'modules' => [
   'gridview' =>  [
        'class' => '\kartik\grid\Module'
    ]
],

GridView

\kartik\grid\GridView

The following functionalities have been added/enhanced:

Table Styling (Enhanced)

Control various options to style your grid table. Added containerOptions to customize your grid table container. Enhancements for grid and columns to work with yii\widgets\Pjax.

Pjax Settings (New)

Inbuilt support for Pjax. Enhancements for grid and columns to work with yii\widgets\Pjax. Auto-reinitializes embedded javascript plugins when GridView is refreshed via Pjax. Added pjax property to enable pjax and pjaxSettings to customize the pjax behavior.

Custom Header & Footer (New)

Add custom header or footer rows, above / below your default grid header and footer.

Floating Header (New)

Allows the grid table to have a floating table header. Uses the JQuery Float THead plugin to display a seamless floating table header.

Panel (New)

Allows configuration of GridView to be enclosed in a panel that can be styled as per Bootstrap 3.x. The panel will enable configuration of various sections to embed content/buttons, before and after header, and before and after footer.

Toolbar (New)

The grid offers ability to configure toolbar for adding various actions. The default templates place the toolbar in the before section of the panel. The toolbar is by default styled using Bootstrap button groups. Some of the default actions like the export button is by default appended to the toolbar. With version v2.1.0, if you are using the yii2-dynagrid extension it automatically displays the personalize, sort, and filter buttons in the toolbar. The toolbar can be configured as a simple array. Refer the docs and demos for details.

Grid Plugins (New)

The grid now offers ability to plugin dynamic content to your grid at runtime. A new property replaceTags has been added with v2.3.0. This allows you to specify tags which will be replaced dynamically at grid rendering time and wherever you set these tags in any of the grid layout templates.

Page Summary (New)

This is a new feature added to the GridView widget. The page summary is an additional row above the footer - for displaying the summary/totals for the current GridView page. The following parameters are applicable to control this behavior:

• showPageSummary: boolean whether to display the page summary row for the grid view. Defaults to false.
• pageSummaryRowOptions: array, HTML attributes for the page summary row. Defaults to ['class' => 'kv-page-summary warning'].

Export Grid Data (New)

This is a new feature added to the GridView widget. It allows you to export the displayed grid content as HTML, CSV, TEXT, EXCEL, PDF, & JSON. It uses the rendered grid data on client to convert to one of the format specified using JQuery. This is supported across all browsers. The PDF rendering is achieved through a separate extension yii2-mpdf.

Features offered by yii2-grid export:

• Ability to preprocess and convert column data to your desired value before exporting. There is a new property exportConversions that can be setup in GridView. For example, this currently is set as a default to convert the HTML formatted icons for BooleanColumn to user friendly text like Active or Inactive after export.
• Hide any row or column in the grid by adding one or more of the following CSS classes:
  • skip-export: Will skip this element during export for all formats (html, csv, txt, xls, pdf, json).
  • skip-export-html: Will skip this element during export only for html export format.
  • skip-export-csv: Will skip this element during export only for csv export format.
  • skip-export-txt: Will skip this element during export only for txt export format.
  • skip-export-xls: Will skip this element during export only for xls (excel) export format.
  • skip-export-pdf: Will skip this element during export only for pdf export format.
  • skip-export-json: Will skip this element during export only for json export format. These CSS can be set virtually anywhere. For example headerOptions, contentOptions, beforeHeader etc.
• With release v2.1.0, you can now merge additional action items to the export button dropdown.
• With release v2.3.0 the export functionality includes these additional features:
  • A separate export popup progress window is now shown for download.
  • Asynchronous export process on the separate window - and avoid any grid refresh
  • Set export mime types to be configurable
  • Includes support for exporting new file types:
    • JSON export
    • PDF export (using yii2-mpdf extension)
  • Adds functionality for full data export
  • Enhance icons formatting for export file types (and beautify optionally using font awesome)
  • Ability to hide entire column from export using hiddenFromExport property, but show them in normal on screen display.
  • Ability to do reverse of above. Hide column in display but show on export using hidden property.
• Adds ability to integrate a separate extension for full data export i.e. yii2-export.

Toggle Grid Data (New)

This extension (with v2.3.0) adds ability to toggle between viewing all grid data and paginated data. By default the grid displays paginated data. This can be used for exporting complete grid data.

Data Column (Enhanced)

\kartik\grid\DataColumn

The default Yii data column has been enhanced with various additional parameters. Refer documentation for details.

Editable Column (New)

\kartik\grid\EditableColumn

An enhanced data column that allows you to edit the cell content using kartik\editable\Editable widget. Refer documentation for details.

Formula Column (New)

\kartik\grid\FormulaColumn

This is a new grid column class that extends the \kartik\grid\DataColumn class. It allows calculating formulae just like in spreadsheets - based on values of other columns in the grid. The formula calculation is done at grid rendering runtime and does not need to query the database. Hence you can use formula columns within another formula column. Refer documentation for details.

Boolean Column (New)

\kartik\grid\BooleanColumn

This is a new grid column class that extends the \kartik\grid\DataColumn class. It automatically converts boolean data (true/false) values to user friendly indicators or labels (that are configurable). Refer documentation for details. The following are new features added since release v1.6.0:

• BooleanColumn icons have been setup as ICON_ACTIVE and ICON_INACTIVE constants in GridView.

Action Column (Enhanced)

\kartik\grid\ActionColumn

Enhancements of \yii\grid\ActionColumn to include optional dropdown Action menu and work with the new pageSummary and a default styling to work for many scenarios. Refer documentation for details. The following are new features added since release v1.6.0:

• ActionColumn content by default has been disabled to appear in export output. The skip-export CSS class has been set as default in headerOptions and contentOptions.

Serial Column (Enhanced)

\kartik\grid\SerialColumn

Enhancement of \yii\grid\SerialColumn to work with the new pageSummary and a default styling to work for many scenarios. Refer documentation for details.

Checkbox Column (Enhanced)

\kartik\grid\CheckboxColumn

Enhancements of \yii\grid\CheckboxColumn to work with the new pageSummary and a default styling to work for many scenarios. Refer documentation for details.

Demo

You can see detailed documentation and demonstration on usage of the extension.

Installation

The preferred way to install this extension is through composer.

Pre-requisites

Note: Check the composer.json for this extension's requirements and dependencies. You must set the minimum-stability to dev in the composer.json file in your application root folder before installation of this extension OR if your minimum-stability is set to any other value other than dev, then set the following in the require section of your composer.json file

kartik-v/yii2-grid: "@dev",
kartik-v/yii2-krajee-base: "@dev"

Read this web tip /wiki on setting the minimum-stability settings for your application's composer.json.

Install

Either run

$ php composer.phar require kartik-v/yii2-grid "dev-master"

or add

"kartik-v/yii2-grid": "dev-master"

to the require section of your composer.json file.

Usage

use kartik\grid\GridView;
$gridColumns = [
    ['class' => 'kartik\grid\SerialColumn'],
    [
        'class' => 'kartik\grid\EditableColumn',
        'attribute' => 'name',
        'pageSummary' => 'Page Total',
        'vAlign'=>'middle',
        'headerOptions'=>['class'=>'kv-sticky-column'],
        'contentOptions'=>['class'=>'kv-sticky-column'],
        'editableOptions'=>['header'=>'Name', 'size'=>'md']
    ],
    [
        'attribute'=>'color',
        'value'=>function ($model, $key, $index, $widget) {
            return "<span class='badge' style='background-color: {$model->color}'> </span>  <code>" . 
                $model->color . '</code>';
        },
        'filterType'=>GridView::FILTER_COLOR,
        'vAlign'=>'middle',
        'format'=>'raw',
        'width'=>'150px',
        'noWrap'=>true
    ],
    [
        'class'=>'kartik\grid\BooleanColumn',
        'attribute'=>'status', 
        'vAlign'=>'middle',
    ],
    [
        'class' => 'kartik\grid\ActionColumn',
        'dropdown' => true,
        'vAlign'=>'middle',
        'urlCreator' => function($action, $model, $key, $index) { return '#'; },
        'viewOptions'=>['title'=>$viewMsg, 'data-toggle'=>'tooltip'],
        'updateOptions'=>['title'=>$updateMsg, 'data-toggle'=>'tooltip'],
        'deleteOptions'=>['title'=>$deleteMsg, 'data-toggle'=>'tooltip'], 
    ],
    ['class' => 'kartik\grid\CheckboxColumn']
];
echo GridView::widget([
    'dataProvider' => $dataProvider,
    'filterModel' => $searchModel,
    'columns' => $gridColumns,
    'containerOptions' => ['style'=>'overflow: auto'], // only set when $responsive = false
    'beforeHeader'=>[
        [
            'columns'=>[
                ['content'=>'Header Before 1', 'options'=>['colspan'=>4, 'class'=>'text-center warning']], 
                ['content'=>'Header Before 2', 'options'=>['colspan'=>4, 'class'=>'text-center warning']], 
                ['content'=>'Header Before 3', 'options'=>['colspan'=>3, 'class'=>'text-center warning']], 
            ],
            'options'=>['class'=>'skip-export'] // remove this row from export
        ]
    ],
    'toolbar' =>  [
        ['content'=>
            Html::button('&lt;i class="glyphicon glyphicon-plus">&lt;/i>', ['type'=>'button', 'title'=>Yii::t('kvgrid', 'Add Book'), 'class'=>'btn btn-success', 'onclick'=>'alert("This will launch the book creation form.\n\nDisabled for this demo!");']) . ' '.
            Html::a('&lt;i class="glyphicon glyphicon-repeat">&lt;/i>', ['grid-demo'], ['data-pjax'=>0, 'class' => 'btn btn-default', 'title'=>Yii::t('kvgrid', 'Reset Grid')])
        ],
        '{export}',
        '{toggleData}'
    ],
    'pjax' => true,
    'bordered' => true,
    'striped' => false,
    'condensed' => false,
    'responsive' => true,
    'hover' => true,
    'floatHeader' => true,
    'floatHeaderOptions' => ['scrollingTop' => $scrollingTop],
    'showPageSummary' => true,
    'panel' => [
        'type' => GridView::TYPE_PRIMARY
    ],
]);

License

yii2-grid is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.