List Controller
Adds list management features to any backend page.
- Configuring the List Behavior
- Adding a Toolbar
- Filtering the List
- Defining List Columns
- Column Properties
- Custom Value Selection
- Nested Column Selection
- Direct SQL Selection
- Related Column Selection
- Displaying the List
- Multiple List Definitions
- Extending List Behavior
- Extending the List Configuration
- Overriding Controller Action
- Overriding Views
- Extending Column Definitions
- Inject CSS Row Class
- Overriding Column URL
- Extending Filter Scopes
- Extending the Model Query
- Extending the Records Collection
- Custom Column Types
The Backend\Behaviors\ListController
class is a controller behavior used for easily adding a record list to a page. The behavior provides the sortable and searchable list with optional links on its records. The behavior provides the controller action index
however the list can be rendered anywhere and multiple list definitions can be used.
List behavior depends on list column definitions and a model class. In order to use the list behavior you should add it to the $implement
property of the controller class. Also, the $listConfig
class property should be defined and its value should refer to the YAML file used for configuring the behavior properties.
namespace Acme\Blog\Controllers;
class Categories extends \Backend\Classes\Controller
{
public $implement = [
\Backend\Behaviors\ListController::class
];
public $listConfig = 'list_config.yaml';
}
Very often the list and form controller are used together in a same controller.
# Configuring the List Behavior
The configuration file referred in the $listConfig
property is defined in YAML format. The file should be placed into the controller's views directory. Below is an example of a typical list behavior configuration file.
# ===================================
## List Behavior Config
# ===================================
title: Blog Posts
list: ~/plugins/acme/blog/models/post/columns.yaml
modelClass: Acme\Blog\Models\Post
recordUrl: acme/blog/posts/update/:id
The following properties are required in the list configuration file.
Property | Description |
---|---|
title | a title for this list. |
list | a configuration array or reference to a list column definition file, see list columns. |
modelClass | a model class name, the list data is loaded from this model. |
The configuration properties listed below are optional.
Property | Description |
---|---|
filter | filter configuration, see list filters. |
recordUrl | link each list record to another page. Eg: users/update:id. The :id part is replaced with the record identifier. This allows you to link the list behavior and the form behavior. |
recordOnClick | custom JavaScript code to execute when clicking on a record. |
noRecordsMessage | a message to display when no records are found, can refer to a localization string. |
deleteMessage | a message to display when records are bulk deleted, can refer to a localization string. |
noRecordsDeletedMessage | a message to display when a bulk delete action is triggered, but no records were deleted, can refer to a localization string. |
recordsPerPage | records to display per page, use 0 for no pages. Default: 0 |
perPageOptions | options for number of items per page. Default: [20, 40, 80, 100, 120] |
showPageNumbers | displays page numbers with pagination. Disable this to improve list performance when working with large tables. Default: true |
toolbar | reference to a Toolbar Widget configuration file, or an array with configuration (see below). |
showSorting | displays the sorting link on each column. Default: true |
defaultSort | sets a default sorting column and direction when user preference is not defined. Supports a string or an array with keys column and direction . |
showCheckboxes | displays checkboxes next to each record. Default: false. |
showSetup | displays the list column set up button. Default: false. |
structure | enables a structured list, see the sorting records article for more details. |
customViewPath | specify a custom view path to override partials used by the list, optional. |
# Adding a Toolbar
To include a toolbar with the list, add the following configuration to the list configuration YAML file:
toolbar:
buttons: list_toolbar
search:
prompt: Find records
The toolbar configuration allows:
Property | Description |
---|---|
buttons | a reference to a controller partial file with the toolbar buttons. Eg: _list_toolbar.htm |
search | reference to a Search Widget configuration file, or an array with configuration. |
The search configuration supports the following properties:
Property | Description |
---|---|
prompt | a placeholder to display when there is no active search, can refer to a localization string. |
mode | defines the search strategy to either contain all words, any word or exact phrase. Supported options: all, any, exact. Default: all. |
scope | specifies a query scope method defined in the list model to apply to the search query. The first argument will contain the query object (as per a regular scope method), the second will contain the search term, and the third will be an array of the columns to be searched. |
searchOnEnter | setting this to true will make the search widget wait for the Enter key to be pressed before it starts searching (the default behavior is that it starts searching automatically after someone enters something into the search field and then pauses for a short moment). Default: false. |
The toolbar buttons partial referred above should contain the toolbar control definition with some buttons. The partial could also contain a scoreboard control (opens new window) with charts. Example of a toolbar partial with the New Post button referring to the create action provided by the form behavior:
<div data-control="toolbar">
<a href="<?= Backend::url('acme/blog/posts/create') ?>"
class="btn btn-primary oc-icon-plus">
New Post
</a>
</div>
When using list checkboxes, you may toggle a button's enabled state with the data-list-checked-trigger
attribute.
<button
type="button"
class="btn btn-primary"
data-list-checked-trigger>
Delete Selected
</button>
You may also pass the checked values to an AJAX request using the data-list-checked-request
attribute.
<button
type="button"
class="btn btn-primary"
data-request="onDelete"
data-list-checked-request>
Delete Selected
</button>
# Filtering the List
To filter a list by user defined input, add the following list configuration to the YAML file:
filter: $/acme/blog/models/post/scopes.yaml
The filter property should make reference to a filter configuration file path or supply an array with the configuration.
# Defining List Columns
List columns are defined with the YAML file. The column configuration is used by the list behavior for creating the record table and displaying model columns in the table cells. The file is placed to a subdirectory of the models directory of a plugin. The subdirectory name matches the model class name written in lowercase. The file name doesn't matter, but the columns.yaml and list_columns.yaml are common names. Example list columns file location:
├── plugins
| └── acme
| └── blog
| └── models
| ├── post ← Config Directory
| | └── columns.yaml ← Config File
| └── Post.php ← Model Class
The next example shows the typical contents of a list column definitions file.
# ===================================
# List Column Definitions
# ===================================
columns:
name: Name
email: Email
# Column Properties
For each column can specify these properties (where applicable):
Property | Description |
---|---|
label | a name when displaying the list column to the user. |
type | defines how this column should be rendered, see list column definitions. |
default | specifies the default value for the column if value is empty. |
searchable | include this column in the list search results. Default: false. |
invisible | specifies if this column is hidden by default. Default: false. |
sortable | specifies if this column can be sorted. Default: true. |
clickable | if set to false, disables the default click behavior when the column is clicked. Default: true. |
select | defines a custom SQL select statement to use for the value. |
valueFrom | defines a model attribute to use for the source value. |
displayFrom | defines a model attribute to use for the display value. |
relation | defines a model relationship column. |
relationCount | display the number of related records as the column value. Must be used with the relation option. Default: false |
cssClass | assigns a CSS class to the column container. |
headCssClass | assigns a CSS class to the column header container. |
width | sets the column width, can be specified in percents (10%) or pixels (50px). There could be a single column without width specified, it will be stretched to take the available space. |
align | specifies the column alignment. Possible values are left , right and center . |
permissions | the permissions that the current backend user must have in order for the column to be used. Supports either a string for a single permission or an array of permissions of which only one is needed to grant access. |
# Custom Value Selection
It is possible to change the source and display values for each column. If you want to source the column value from another column, do so with the valueFrom
option.
other_name:
label: Something Great
valueFrom: name
If you want to keep the source column value but display a different value from the model attribute, use the displayFrom
option.
status_code:
label: Status
displayFrom: status_label
This is mostly applicable when a model accessor is used to modify the display value. This is useful where you want to display a certain value, but sort and search by a different value.
public function getStatusLabelAttribute()
{
return title_case($this->status_code);
}
# Nested Column Selection
In some cases it makes sense to retrieve a column value from a nested data structure, such as a model relationship column or a jsonable array. The only drawback of doing this is the column cannot use searchable or sortable options.
content[title]:
name: Title
sortable: false
The above example would look for the value in PHP equivalent of $record->content->title
or $record->content['title']
respectively. To make the column searchable, and for performance reasons, we recommend duplicating its value on the local database table using model events.
# Direct SQL Selection
The select
property allows you to create a column using a custom select statement. Any valid SQL SELECT statement works here.
full_name:
label: Full Name
select: concat(first_name, ' ', last_name)
# Related Column Selection
The relation
property allows you to display related columns, you can provide a relationship option. The value of this option has to be the name of the Active Record relationship on your model. In the next example the name value will be translated to the name attribute found in the related model (eg: $model->name
).
group_name:
label: Group
relation: groups
select: name
To display a column that shows the number of related records, use the relationCount
property.
users_count:
label: Users
relation: users
relationCount: true
type: number
Be careful not to name relations the same as existing database columns. For example, using a name group_id
could break the group relation due to a naming conflict.
# Displaying the List
Usually lists are displayed in the index view file. Since lists include the toolbar, the view file will consist solely of the single listRender
method call.
<?= $this->listRender() ?>
# Multiple List Definitions
The list behavior can support multiple lists in the same controller using named definitions. The $listConfig
property can be defined as an array where the key is a definition name and the value is the configuration file.
public $listConfig = [
'templates' => 'config_templates_list.yaml',
'layouts' => 'config_layouts_list.yaml'
];
Each definition can then be displayed by passing the definition name as the first argument when calling the listRender
method.
<?= $this->listRender('templates') ?>
# Extending List Behavior
Sometimes you may wish to modify the default list behavior and there are several ways you can do this.
# Extending the List Configuration
You may extend the list configuration dynamically using the listGetConfig
method.
public function listGetConfig($definition)
{
$config = $this->asExtension('ListController')->listGetConfig($definition);
// Implement structure dynamically
$config->structure = [
'showTree' => true
];
return $config;
}
# Overriding Controller Action
You may use your own logic for the index
action method in the controller, then optionally call the List behavior index
parent method.
public function index()
{
//
// Do any custom code here
//
// Call the ListController behavior index() method
$this->asExtension('ListController')->index();
}
# Overriding Views
The ListController
behavior has a main container view that you may override by creating a special file named _list_container.php
in your controller directory. The following example will add a sidebar to the list:
<?php if ($toolbar): ?>
<?= $toolbar->render() ?>
<?php endif ?>
<?php if ($filter): ?>
<?= $filter->render() ?>
<?php endif ?>
<div class="row row-flush">
<div class="col-sm-3">
[Insert sidebar here]
</div>
<div class="col-sm-9 list-with-sidebar">
<?= $list->render() ?>
</div>
</div>
The behavior will invoke a Lists
widget that also contains numerous views that you may override. This is possible by specifying a customViewPath
property as described in the list configuration options. The widget will look in this path for a view first, then fall back to the default location.
# Custom view path
customViewPath: $/acme/blog/controllers/reviews/list
It is a good idea to use a sub-directory, for example called list
, to avoid conflicts.
For example, to modify the list body row markup, create a file called list/_list_body_row.php
in your controller directory.
<tr>
<?php foreach ($columns as $key => $column): ?>
<td><?= $this->getColumnValue($record, $column) ?></td>
<?php endforeach ?>
</tr>
# Extending Column Definitions
You may extend the columns of another controller from outside by calling the extendListColumns
static method on the controller class. This method can take two arguments, $list will represent the Lists widget object and $model represents the model used by the list. Take this controller for example.
class Categories extends \Backend\Classes\Controller
{
public $implement = [
\Backend\Behaviors\ListController::class
];
public $listConfig = 'list_config.yaml';
}
Using the extendListColumns
method you can add extra columns to any list rendered by this controller. It is a good idea to check the $model is of the correct type. Here is an example.
Categories::extendListColumns(function($list, $model) {
if (!$model instanceof MyModel) {
return;
}
// Add a new column
$list->addColumns([
'my_column' => [
'label' => 'My Column'
]
]);
// Modify an existing column
$list->getColumn('title')->useConfig([
'path' => 'column_title'
]);
});
You may also extend the list columns internally by overriding the listExtendColumns
method inside the controller class.
class Categories extends \Backend\Classes\Controller
{
// ...
public function listExtendColumns($list)
{
$list->addColumns([...]);
$list->getColumn(...);
}
}
The following methods are available on the $list object.
Method | Description |
---|---|
addColumns | adds new columns to the list |
removeColumn | removes a column from the list |
getColumn | returns an existing column definition |
Each method takes an array of columns similar to the list column configuration.
# Inject CSS Row Class
You may inject a custom css row class by adding a listInjectRowClass
method on the controller class. This method can take two arguments, $record will represent a single model record and $definition contains the name of the List widget definition. You may return any string value containing your row classes. These classes will be added to the row's HTML markup.
class Lessons extends \Backend\Classes\Controller
{
// ...
public function listInjectRowClass($lesson, $definition = null)
{
// Strike through past lessons
if ($lesson->lesson_date->lt(Carbon::today())) {
return 'strike';
}
}
}
A special CSS class nolink
is available to force a row to be unclickable, even if the recordUrl
or recordOnClick
properties are defined for the list widget. Returning this class in an event will allow you to make records unclickable - for example, for soft-deleted rows or for informational rows:
public function listInjectRowClass($record, $value)
{
if ($record->trashed()) {
return 'nolink';
}
}
# Overriding Column URL
You may specify the click action for a column record by overriding the listOverrideRecordUrl
method. This method can return a string for a new backend URL or an array with a complex definition.
public function listOverrideRecordUrl($record, $definition = null)
{
if ($record->is_active) {
return 'acme/test/services/preview/' . $record->id;
}
}
To override the onclick behavior return an array with the onclick
key and change the url
to null.
public function listOverrideRecordUrl($record, $definition = null)
{
if ($record->is_banned) {
return ['onclick' => "alert('Unable to click')", 'url' => null];
}
}
To make a column unclickable entirely return an array with the clickable
key set to false.
public function listOverrideRecordUrl($record, $definition = null)
{
if ($record->is_disabled) {
return ['clickable' => false];
}
}
# Extending Filter Scopes
You may extend the filter scopes of another controller from outside by calling the extendListFilterScopes
static method on the controller class. This method can take the argument $filter which will represent the Filter widget object. Take this controller for example:
Categories::extendListFilterScopes(function($filter) {
// Add custom CSS classes to the filter widget
$filter->cssClasses = array_merge(
$filter->cssClasses,
['my', 'array', 'of', 'classes']
);
$filter->addScopes([
'my_scope' => [
'label' => 'My Filter Scope'
]
]);
});
The array of scopes provided is the same as the list filters configuration.
You may also extend the filter scopes internally to the controller class, simply override the listFilterExtendScopes
method.
class Categories extends \Backend\Classes\Controller
{
// ...
public function listFilterExtendScopes($filter)
{
$filter->addScopes([...]);
}
}
The following methods are available on the $filter object.
Method | Description |
---|---|
addScopes | adds new scopes to filter widget |
removeScope | remove scope from filter widget |
getScope | returns an existing scope definition |
# Extending the Model Query
The lookup query for the list database model can be extended by overriding the listExtendQuery
method inside the controller class. This example will ensure that soft deleted records are included in the list data, by applying the withTrashed scope to the query:
public function listExtendQuery($query)
{
$query->withTrashed();
}
When dealing with multiple lists definitions in a same controller, you can use the second parameter of listExtendQuery
which contains the name of the definition :
public $listConfig = [
'inbox' => 'config_inbox_list.yaml',
'trashed' => 'config_trashed_list.yaml'
];
public function listExtendQuery($query, $definition)
{
if ($definition === 'trashed') {
$query->onlyTrashed();
}
}
You may also join other tables to aid with searching and sorting. The following will join the post_statuses
table and introduce the status_sort_order
and status_name
columns to the query.
public function listExtendQuery($query, $definition = null)
{
$query->leftJoin('post_statuses', 'posts.status_id', 'post_statuses.id');
$query->addSelect(
'post_statuses.sort_order as status_sort_order',
'post_statuses.name as status_name'
);
}
The list filter model query can also be extended by overriding the listFilterExtendQuery
method:
public function listFilterExtendQuery($query, $scope)
{
if ($scope->scopeName == 'status') {
$query->where('status', '<>', 'all');
}
}
# Extending the Records Collection
The collection of records used by the list can be extended by overriding the listExtendRecords
method inside the controller class. This example uses the sort
method on the record collection to change the sort order of the records.
public function listExtendRecords($records)
{
return $records->sort(function ($a, $b) {
return $a->computedVal() > $b->computedVal();
});
}
# Custom Column Types
Custom list column types can be registered in the back-end with the registerListColumnTypes
method of the plugin registration file. The method should return an array where the key is the type name and the value is a callable function. The callable function receives three arguments, the native $value
, the $column
definition object and the model $record
object.
public function registerListColumnTypes()
{
return [
// A local method, i.e $this->evalUppercaseListColumn()
'uppercase' => [$this, 'evalUppercaseListColumn'],
// Using an inline closure
'loveit' => function($value) { return 'I love '. $value; }
];
}
public function evalUppercaseListColumn($value, $column, $record)
{
return strtoupper($value);
}
Using the custom list column type is as simple as calling it by name using the type
property.
# ===================================
# List Column Definitions
# ===================================
columns:
secret_code:
label: Secret code
type: uppercase