diff --git a/CHANGE.md b/CHANGE.md index db9c8871..4b55313e 100755 --- a/CHANGE.md +++ b/CHANGE.md @@ -5,6 +5,7 @@ Change Log: `yii2-grid` **Date:** 03-Nov-2018 +- (enh #847): Add new grid column `EnumColumn`. - (enh #846): Enhance Grid Grouping to better parse multi level group footers. - (enh #843, #844): Add ability to have different exportConversions for specific export type. - For example `from_pdf` and `to_pdf` will be used instead of `from` and `to`. If diff --git a/README.md b/README.md index 6031335e..d59c58ec 100755 --- a/README.md +++ b/README.md @@ -144,6 +144,10 @@ This extension (with v2.3.0) adds ability to toggle between viewing **all grid d ### \kartik\grid\DataColumn The default Yii data column has been enhanced with various additional parameters. Refer [documentation](http://demos.krajee.com/grid#data-column) for details. +## Enum Column (New) +### \kartik\grid\EnumColumn +This is a new grid column class available from release v3.2.7 that extends the `\kartik\grid\DataColumn` class. It allows you to configure and display a dynamic content / markup for each of the cell attribute values based on enumerated `$value => $content` pairs. + ## Expand Row Column (New) ### \kartik\grid\ExpandRowColumn An enhanced data column that allows one to expand a grid row and display additional/detail content in a new row below it either directly or via ajax. Refer [documentation](http://demos.krajee.com/grid#expand-row-column) for details. @@ -154,13 +158,15 @@ An enhanced data column that allows you to edit the cell content using [kartik\e ## 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 +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](http://demos.krajee.com/grid#formula-column) for details. +Refer [documentation](http://demos.krajee.com/grid#enum-column) 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). +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](http://demos.krajee.com/grid#boolean-column) 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. diff --git a/src/EnumColumn.php b/src/EnumColumn.php new file mode 100644 index 00000000..a6b18ac0 --- /dev/null +++ b/src/EnumColumn.php @@ -0,0 +1,80 @@ + + * @copyright Copyright © Kartik Visweswaran, Krajee.com, 2014 - 2018 + * @version 3.2.7 + */ + +namespace kartik\grid; + +use yii\helpers\ArrayHelper; + +/** + * The [[EnumColumn]] allows you to configure and display a dynamic content / markup for each of the cell attribute + * values based on enumerated `$value => $content` pairs. An example of the usage: + * + * ```php + * // Example 1 + * [ + * 'class' => 'kartik\grid\EnumColumn', + * 'attribute' => 'role', + * 'enum' => User::getRoles(), + * 'loadEnumAsFilter' => true, // optional - defaults to `true` + * ], + * // Example 2 + * [ + * 'class' => 'kartik\grid\EnumColumn', + * 'attribute' => 'gender', + * 'enum' => [ + * '0' => 'Unknown', + * 'F' => 'Female', + * 'M' => 'Male', + * ], + * 'filter' => [ // will override the grid column filter + * '0' => 'Unknown', + * 'F' => 'Female', + * 'M' => 'Male', + * ], + * ] + * ``` + * + * @author Kartik Visweswaran + * @since 1.0 + */ +class EnumColumn extends DataColumn +{ + /** + * @var array the `$value => $content` pairs that will be used for conversion of the attribute values to your own + * predefined markup. The `$content` markup will not be HTML coded. If [[loadEnumAsFilter]] is set to `true`, and + * `filter` property is not set, then the `filter` property will automatically default to this property's value. + */ + public $enum = []; + + /** + * @var bool whether to automatically set the `filter` property to the `enum` property value, if `filter` property + * is not set + */ + public $loadEnumAsFilter = true; + + /** + * @inheritdoc + */ + public function init() + { + parent::init(); + if ($this->loadEnumAsFilter && !isset($this->filter)) { + $this->filter = $this->enum; + } + } + + /** + * @inheritdoc + */ + public function getDataCellValue($model, $key, $index) + { + $value = parent::getDataCellValue($model, $key, $index); + return $value === null ? null : ArrayHelper::getValue($this->enum, $value, $value); + } +} \ No newline at end of file