Fix #847: Add new grid column EnumColumn

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 

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.

src/EnumColumn.php

@@ -0,0 +1,80 @@
+<?php
+
+/**
+ * @package   yii2-grid
+ * @author    Kartik Visweswaran <[email protected]>
+ * @copyright Copyright &copy; 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' => '<span class="text-muted">Unknown</span>',
+ *          'F' => '<span class="text-success">Female</span>',
+ *          'M' => '<span class="text-danger">Male</span>',
+ *      ],
+ *      'filter' => [  // will override the grid column filter
+ *          '0' => 'Unknown',
+ *          'F' => 'Female',
+ *          'M' => 'Male',
+ *      ],
+ * ]
+ * ```
+ *
+ * @author Kartik Visweswaran <[email protected]>
+ * @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);
+    }
+}