From ac2e5937f04396d158f74e8b710c10a0d6f06e9d Mon Sep 17 00:00:00 2001
From: Luke Towers <github@luketowers.ca>
Date: Wed, 18 Oct 2017 10:57:17 -0600
Subject: [PATCH] Document list widget column value events

Documents `backend.list.overrideColumnValue` and adds and documents `backend.list.overrideColumnValueRaw`. See https://github.com/octobercms/october/issues/3180 for why this is necessary.
---
 modules/backend/widgets/Lists.php | 41 +++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/modules/backend/widgets/Lists.php b/modules/backend/widgets/Lists.php
index 0e42bbb80..f612b4b94 100644
--- a/modules/backend/widgets/Lists.php
+++ b/modules/backend/widgets/Lists.php
@@ -845,6 +845,28 @@ class Lists extends WidgetBase
                 $value = $record->{$columnName};
             }
         }
+        
+        /**
+         * @event backend.list.overrideColumnValueRaw
+         * Overrides the raw column value in a list widget. 
+         *
+         * If a value is returned from this event, it will be used as the raw value for the provided column.
+         * `$value` is passed by reference so modifying the variable in place is also supported. Example usage:
+         *
+         *     Event::listen('backend.list.overrideColumnValueRaw', function($record, $column, &$value) { 
+         *         $value .= '-modified';
+         *     });
+         *
+         * Or
+         *
+         *     $listWidget->bindEvent('list.overrideColumnValueRaw', function ($record, $column, $value) {
+         *         return 'No values for you!';
+         *     });
+         *
+         */
+        if ($response = $this->fireSystemEvent('backend.list.overrideColumnValueRaw', [$record, $column, &$value])) {
+            $value = $response;
+        }
 
         return $value;
     }
@@ -871,8 +893,23 @@ class Lists extends WidgetBase
             $value = $column->defaults;
         }
 
-        /*
-         * Extensibility
+        /**
+         * @event backend.list.overrideColumnValue
+         * Overrides the column value in a list widget. 
+         *
+         * If a value is returned from this event, it will be used as the value for the provided column.
+         * `$value` is passed by reference so modifying the variable in place is also supported. Example usage:
+         *
+         *     Event::listen('backend.list.overrideColumnValue', function($record, $column, &$value) { 
+         *         $value .= '-modified';
+         *     });
+         *
+         * Or
+         *
+         *     $listWidget->bindEvent('list.overrideColumnValue', function ($record, $column, $value) {
+         *         return 'No values for you!';
+         *     });
+         *
          */
         if ($response = $this->fireSystemEvent('backend.list.overrideColumnValue', [$record, $column, &$value])) {
             $value = $response;