• Introduction
• Configuring the list behavior
  • Adding a toolbar
  • Filtering the list
• Defining list columns
  • Column options
• Available column types
• Displaying the list
• Multiple list definitions
• Using list filters
  • Scope options
  • Available scope types
• Extending list behavior
  • Overriding controller action
  • Overriding views
  • Extending column definitions
  • Extending filter scopes
  • Extending the model query
  • Extending the records collection
  • Custom column types

Introduction

List behavior is a controller modifier 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 options.

namespace Acme\Blog\Controllers;

class Categories extends \Backend\Classes\Controller
{
    public $implement = ['Backend.Behaviors.ListController'];

    public $listConfig = 'list_config.yaml';
}

Note: Very often the list and form behavior 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 fields are required in the list configuration file:

The configuration options listed below are 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:

The search configuration supports the following options:

The toolbar buttons partial referred above should contain the toolbar control definition with some buttons. The partial could also contain a scoreboard control 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>

Filtering the list

To filter a list by user defined input, add the following list configuration to the YAML file:

filter: config_filter.yaml

The filter option 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/                  <=== Plugin models directory
        post/                  <=== Model configuration directory
          list_columns.yaml    <=== Model list columns 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 options

For each column can specify these options (where applicable):

Available column types

There are various column types that can be used for the type setting, these control how the list column is displayed. In addition to the native column types specified below, you may also define custom column types.

Text

text - displays a text column, aligned left

full_name:
    label: Full Name
    type: text

Number

number - displays a number column, aligned right

age:
    label: Age
    type: number

Switch

switch - displays a on or off state for boolean columns.

enabled:
    label: Enabled
    type: switch

Date & Time

datetime - displays the column value as a formatted date and time. The next example displays dates as Thu, Dec 25, 1975 2:15 PM.

created_at:
    label: Date
    type: datetime

You can also specify a custom date format, for example Thursday 25th of December 1975 02:15:16 PM:

created_at:
    label: Date
    type: datetime
    format: l jS \of F Y h:i:s A

Date

date - displays the column value as date format M j, Y

created_at:
    label: Date
    type: date

Time

time - displays the column value as time format g:i A

created_at:
    label: Date
    type: time

Time since

timesince - displays a human readable time difference from the value to the current time. Eg: 10 minutes ago

created_at:
    label: Date
    type: timesince

Time tense

timetense - displays 24-hour time and the day using the grammatical tense of the current date. Eg: Today at 12:49, Yesterday at 4:00 or 18 Sep 2015 at 14:33.

created_at:
    label: Date
    type: timetense

Select

select - allows 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)

Relation

relation - allows 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:
    label: Group
    relation: groups
    select: name

If the relationship definition uses the count argument, you can display the number of related records using the valueFrom and default options.

users_count:
    label: Users
    relation: users_count
    valueFrom: count
    default: 0

Note: Using the relation option on a column will load the value from the selected column into the attribute specified by this column. It is recommended that you name the column displaying the relation data without conflicting with existing model attributes as demonstrated in the examples below:

Best Practice:

 group_name:
     label: Group
     relation: group
     select: name

Poor Practice:

# This will overwrite the value of $record->group_id which will break accessing relations from the list view
group_id:
    label: Group
    relation: group
    select: name

Partial

partial - renders a partial, the path value can refer to a partial view file otherwise the column name is used as the partial name. Inside the partial these variables are available: $value is the default cell value, $record is the model used for the cell and $column is the configured class object Backend\Classes\ListColumn.

content:
    type: partial
    path: ~/plugins/acme/blog/models/comments/_content_column.htm

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 mulitple 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') ?>

Using list filters

Lists can be filtered by adding a filter definition to the list configuration. Similarly filters are driven by their own configuration file that contain filter scopes, each scope is an aspect by which the list can be filtered. The next example shows a typical contents of the filter definition file.

# ===================================
# Filter Scope Definitions
# ===================================

scopes:

    category:
        label: Category
        modelClass: Acme\Blog\Models\Category
        conditions: category_id in (:filtered)
        nameFrom: name

    status:
        label: Status
        type: group
        conditions: status in (:filtered)
        options:
            pending: Pending
            active: Active
            closed: Closed

    published:
        label: Hide published
        type: checkbox
        conditions: is_published <> true

    approved:
        label: Approved
        type: switch
        conditions:
            - is_approved <> true
            - is_approved = true

    created_at:
        label: Date
        type: date
        conditions: created_at >= ':filtered'

    published_at:
        label: Date
        type: daterange
        conditions: created_at >= ':after' AND created_at <= ':before'

Scope options

For each scope you can specify these options (where applicable):

Available scope types

These types can be used to determine how the filter scope should be displayed.

Extending list behavior

Sometimes you may wish to modify the default list behavior and there are several ways you can do this.

• Overriding controller action
• Overriding views
• Extending column definitions
• Extending filter scopes
• Extending the model query
• Custom column types

Overriding controller action

You can 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.htm 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 option 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

Note: It is a good idea to use a sub-directory, for example list, to avoid conflicts.

For example, to modify the list body row markup, create a file called list/_list_body_row.htm in your controller directory.

<tr>
    <?php foreach ($columns as $key => $column): ?>
        <td><?= $this->getColumnValue($record, $column) ?></td>
    <?php endforeach ?>
</tr>

Extending column definitions

You can 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'];

    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;

        $list->addColumns([
            'my_column' => [
                'label' => 'My Column'
            ]
        ]);

    });

You can 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([...]);
    }
}

The following methods are available on the $list object.

Each method takes an array of columns similar to the list column configuration.

Extending filter scopes

You can 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) {
        $filter->addScopes([
            'my_scope' => [
                'label' => 'My Filter Scope'
            ]
        ]);
    });

The array of scopes provided is similar to the list filters configuration.

You can 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.

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();
}

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 class. 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 option.

# ===================================
#  List Column Definitions
# ===================================

columns:
    secret_code:
        label: Secret code
        type: uppercase