diff --git a/modules/backend/widgets/Lists.php b/modules/backend/widgets/Lists.php index b468813cf..91c862e2e 100644 --- a/modules/backend/widgets/Lists.php +++ b/modules/backend/widgets/Lists.php @@ -354,8 +354,22 @@ class Lists extends WidgetBase $joins = []; $withs = []; - /* - * Extensibility + /** + * @event backend.list.extendQueryBefore + * Provides an opportunity to modify the `$query` object before the List widget applies its scopes to it. + * + * Example usage: + * + * Event::listen('backend.list.extendQueryBefore', function($listWidget, $query) { + * $query->whereNull('deleted_at'); + * }); + * + * Or + * + * $listWidget->bindEvent('list.extendQueryBefore', function ($query) { + * $query->whereNull('deleted_at'); + * }); + * */ $this->fireSystemEvent('backend.list.extendQueryBefore', [$query]); @@ -530,8 +544,23 @@ class Lists extends WidgetBase */ $query->addSelect($selects); - /* - * Extensibility + /** + * @event backend.list.extendQuery + * Provides an opportunity to modify and / or return the `$query` object after the List widget has applied its scopes to it and before it's used to get the records. + * + * Example usage: + * + * Event::listen('backend.list.extendQuery', function($listWidget, $query) { + * $newQuery = MyModel::newQuery(); + * return $newQuery; + * }); + * + * Or + * + * $listWidget->bindEvent('list.extendQuery', function ($query) { + * $query->whereNull('deleted_at'); + * }); + * */ if ($event = $this->fireSystemEvent('backend.list.extendQuery', [$query])) { return $event; @@ -564,8 +593,24 @@ class Lists extends WidgetBase $records = $model->get(); } - /* - * Extensibility + /** + * @event backend.list.extendRecords + * Provides an opportunity to modify and / or return the `$records` Collection object before the widget uses it. + * + * Example usage: + * + * Event::listen('backend.list.extendRecords', function($listWidget, $records) { + * $model = MyModel::where('always_include', true)->first(); + * $records->prepend($model); + * }); + * + * Or + * + * $listWidget->bindEvent('list.extendRecords', function ($records) { + * $model = MyModel::where('always_include', true)->first(); + * $records->prepend($model); + * }); + * */ if ($event = $this->fireSystemEvent('backend.list.extendRecords', [&$records])) { $records = $event; @@ -692,8 +737,58 @@ class Lists extends WidgetBase $this->addColumns($this->columns); - /* - * Extensibility + /** + * @event backend.list.extendColumns + * Provides an opportunity to modify the columns of a List widget + * + * Example usage: + * + * Event::listen('backend.list.extendColumns', function($listWidget) { + * // Only for the User controller + * if (!$listWidget->getController() instanceof \Backend\Controllers\Users) { + * return; + * } + * + * // Only for the User model + * if (!$listWidget->model instanceof \Backend\Models\User) { + * return; + * } + * + * // Add an extra birthday column + * $listWidget->addColumns([ + * 'birthday' => [ + * 'label' => 'Birthday' + * ] + * ]); + * + * // Remove a Surname column + * $listWidget->removeColumn('surname'); + * }); + * + * Or + * + * $listWidget->bindEvent('list.extendColumns', function () use ($listWidget) { + * // Only for the User controller + * if (!$listWidget->getController() instanceof \Backend\Controllers\Users) { + * return; + * } + * + * // Only for the User model + * if (!$listWidget->model instanceof \Backend\Models\User) { + * return; + * } + * + * // Add an extra birthday column + * $listWidget->addColumns([ + * 'birthday' => [ + * 'label' => 'Birthday' + * ] + * ]); + * + * // Remove a Surname column + * $listWidget->removeColumn('surname'); + * }); + * */ $this->fireSystemEvent('backend.list.extendColumns'); @@ -814,10 +909,25 @@ class Lists extends WidgetBase { $value = Lang::get($column->label); - /* - * Extensibility + /** + * @event backend.list.overrideHeaderValue + * Overrides the column header 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.overrideHeaderValue', function($listWidget, $column, &$value) { + * $value .= '-modified'; + * }); + * + * Or + * + * $listWidget->bindEvent('list.overrideHeaderValue', function ($column, $value) { + * return 'Custom header value'; + * }); + * */ - if ($response = $this->fireSystemEvent('backend.list.overrideHeaderValue', [$column, $value])) { + if ($response = $this->fireSystemEvent('backend.list.overrideHeaderValue', [$column, &$value])) { $value = $response; } @@ -882,7 +992,7 @@ class Lists extends WidgetBase * 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) { + * Event::listen('backend.list.overrideColumnValueRaw', function($listWidget, $record, $column, &$value) { * $value .= '-modified'; * }); * @@ -929,7 +1039,7 @@ class Lists extends WidgetBase * 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) { + * Event::listen('backend.list.overrideColumnValue', function($listWidget, $record, $column, &$value) { * $value .= '-modified'; * }); * @@ -956,10 +1066,25 @@ class Lists extends WidgetBase { $value = ''; - /* - * Extensibility + /** + * @event backend.list.injectRowClass + * Provides opportunity to inject a custom CSS row class + * + * If a value is returned from this event, it will be used as the value for the row class. + * `$value` is passed by reference so modifying the variable in place is also supported. Example usage: + * + * Event::listen('backend.list.injectRowClass', function($listWidget, $record, &$value) { + * $value .= '-modified'; + * }); + * + * Or + * + * $listWidget->bindEvent('list.injectRowClass', function ($record, $value) { + * return 'strike'; + * }); + * */ - if ($response = $this->fireSystemEvent('backend.list.injectRowClass', [$record])) { + if ($response = $this->fireSystemEvent('backend.list.injectRowClass', [$record, &$value])) { $value = $response; }