后端列表

• 简介
• 配置列表行为
  • 添加工具栏
  • 过滤列表
• 定义列表列
  • 列选项
• 可用列类型
• 显示列表
• 多个列表定义
• 使用列表过滤器
  • 范围选项
  • 可用范围类型
• 扩展列表行为
  • 覆盖控制器动作
  • 覆盖视图
  • 扩展列定义
  • 注入CSS class
  • 扩展过滤器范围
  • 扩展模型查询
  • 扩展记录集
  • 自定义列类型

简介

列表行为是一个控制器修饰符，用于轻松地将记录列表添加到页面。 该行为提供可排序和可搜索的列表，其列表中包含可选链接。 该行为提供了控制器操作index，但是列表可以在任何地方呈现，并且可以使用多个列表定义。

列表行为取决于列表列定义和模型类。 为了使用列表行为，您应该将它添加到控制器类的$implement属性中。 此外，应定义$listConfig类属性，其值应引用用于配置行为选项的YAML文件。

namespace Acme\Blog\Controllers;
class Categories extends \Backend\Classes\Controller
{
    public $implement = ['Backend.Behaviors.ListController'];
    public $listConfig = 'list_config.yaml';
}

注意:通常，列表和表单行为在同一个控制器中一起使用。

配置列表行为

$listConfig属性中引用的配置文件以YAML格式定义。 该文件应放入控制器的views目录。 以下是典型列表行为配置文件的示例:

# ===================================
#  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

列表配置文件中需要以下字段:

下面列出的配置选项是可选的。

添加工具栏

要在列表中包含工具栏，请将以下配置添加到列表配置YAML文件中:

toolbar:
    buttons: list_toolbar
    search:
        prompt: Find records

工具栏配置允许:

搜索配置支持以下选项:

上面提到的工具栏按钮部分应该包含带有一些按钮的工具栏控件定义。 部分还可以包含带有图表的记分板控件。 使用New Post按钮引用由form behavior提供的create操作的工具栏部分示例:

<div data-control="toolbar">
    <a
        href="<?= Backend::url('acme/blog/posts/create') ?>"
        class="btn btn-primary oc-icon-plus">New Post</a>
</div>

过滤列表

要按用户定义的输入过滤列表，请将以下列表配置添加到YAML文件:

filter: config_filter.yaml

filter选项应引用filter configuration file路径或提供带有配置的数组。

定义列表列

列列是使用YAML文件定义的。 列配置使用列配置来创建记录表并在表格单元格中显示模型列。 该文件放在插件的models目录的子目录中。 子目录名称与以小写字母书写的模型类名称匹配。 文件名无关紧要，但columns.yaml和list_columns.yaml是常用名称。 示例列表列文件位置:

plugins/
  acme/
    blog/
      models/                 <=== Plugin models directory
        post/                 <=== Model configuration directory
          list_columns.yaml    <=== Model list columns config file
        Post.php               <=== model class

下一个示例显示了列列定义文件的典型内容。

# ===================================
#  List Column Definitions
# ===================================
columns:
    name: Name
    email: Email

列选项

对于每列，可以指定这些选项(如果适用):

可用的列类型

有许多列类型可用于类型设置，它们控制列表列的显示方式。 除了下面指定的本机列类型之外，您还可以定义自定义列类型。

• Text
• Number
• Switch
• Date & Time
• Date
• Time
• Time since
• Time tense
• Select
• Relation
• Partial
• Colorpicker

Text

text - 显示一个左对齐的文本列

full_name:
    label: Full Name
    type: text

Number

number - 显示一个数字列，右对齐

age:
    label: Age
    type: number

Switch

switch - 显示布尔列的开启或关闭状态。

enabled:
    label: Enabled
    type: switch

Date & Time

datetime - 将列值显示为格式化的日期和时间。 下一个示例将日期显示为Thu，1975年12月25日下午2:15。

created_at:
    label: Date
    type: datetime
    # Display datetime exactly as it is stored, ignores October's and the backend user's specified timezones.
    ignoreTimezone: true

您还可以指定自定义日期格式，例如1975年12月25日星期四02:15:16 PM:

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

Date

date - 将列值显示为日期格式M j,Y

created_at:
    label: Date
    type: date
    # Display datetime exactly as it is stored, ignores October's and the backend user's specified timezones.
    ignoreTimezone: true

Time

time - 将列值显示为时间格式g:i A

created_at:
    label: Date
    type: time
    # Display datetime exactly as it is stored, ignores October's and the backend user's specified timezones.
    ignoreTimezone: true

Time since

timesince - 显示从值到当前时间的人类可读时间差。 例如:10分钟前

created_at:
    label: Date
    type: timesince
    # Display datetime exactly as it is stored, ignores October's and the backend user's specified timezones.
    ignoreTimezone: true

Time tense

timetense - 使用当前日期的语法时态显示24小时时间和日期。 例如:今天12:49，昨天4:00或2015年9月18日14:33。

created_at:
    label: Date
    type: timetense
    # Display datetime exactly as it is stored, ignores October's and the backend user's specified timezones.
    ignoreTimezone: true

Select

select - 允许使用自定义select语句创建列。 任何有效的SQL SELECT语句都适用于此处。

full_name:
    label: Full Name
    select: concat(first_name, ' ', last_name)

Relation

relation - 允许显示相关列，可以提供关系选项。 此选项的值必须是模型上Active Record relationship的名称。 在下一个示例中，name值将转换为相关模型中的name属性(例如:$model-> name)。

group:
    label: Group
    relation: groups
    select: name

要显示显示相关记录数的列，请使用useRelationCount选项。

users_count:
    label: Users
    relation: users
    useRelationCount: true

注意:使用列上的relation选项会将selected列中的值加载到此列指定的属性中。 建议您将显示关系数据的列命名为名称，而不与现有模型属性冲突，如以下示例所示:

最佳实践:

 group_name:
     label: Group
     relation: group
     select: name

糟糕的做法:

# 这将覆盖$record-> group_id的值，这将破坏从列表视图访问关系
group_id:
    label: Group
    relation: group
    select: name

Partial

partial - 渲染partial，path值可以引用partial视图文件，否则列名称用作partial名称。 在partial内部，这些变量是可用的:$value是默认单元格值，$record是用于单元格的模型，$column是配置的类对象Backend::Classes::ListColumn。

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

Color Picker

colorpicker - 显示colorpicker列的颜色

color:
    label: Background
    type: colorpicker

显示列表

通常列表显示在索引view文件中。 由于列表包含工具栏，因此视图文件将仅包含单个listRender方法调用。

<?= $this->listRender() ?>

多个列表定义

列表行为可以使用命名定义在同一控制器中支持多个列表。 $listConfig属性可以定义为一个数组，其中键是定义名称，值是配置文件。

public $listConfig = [
    'templates' => 'config_templates_list.yaml',
    'layouts' => 'config_layouts_list.yaml'
];

然后，通过在调用listRender方法时将定义名称作为第一个参数传递，可以显示每个定义:

<?= $this->listRender('templates') ?>

使用列表过滤器

可以通过添加过滤器定义过滤列表配置来过滤列表。 类似地，过滤器由它们自己的包含过滤器范围的配置文件驱动，每个范围是可以过滤列表的方面。 下一个示例显示了过滤器定义文件的典型内容。

# ===================================
# 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
        default: 1
        conditions: is_published <> true
    approved:
        label: Approved
        type: switch
        default: 2
        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'

范围选项

对于每个范围，您可以指定这些选项(如果适用):

可用范围类型

这些类型可用于确定如何显示过滤器范围。

• Group
• Checkbox
• Switch
• Date
• Date range
• Number
• Number range
• Text

Group

group - 通过一组项过滤列表，通常是通过相关模型，并且需要nameFrom或options定义。 例如:状态名称为打开，关闭等。

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

Checkbox

checkbox - 用作二进制复选框，以将预定义条件或查询应用于列表，可以打开也可以关闭。 使用0表示关闭，使用1表示打开默认值

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

Switch

switch - 用作切换器在两个预定义条件或查询列表之间切换，不确定，打开或关闭。 使用0表示关闭，1表示不确定，2表示默认值

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

Date

date - 显示要选择的单个日期的日期选择器。

created_at:
    label: Date
    type: date
    minDate: '2001-01-23'
    maxDate: '2030-10-13'
    yearRange: 10
    conditions: created_at >= ':filtered'

Date Range

daterange - 显示要选择作为日期范围的两个日期的日期选择器。 条件参数以:before和:after传递。

published_at:
    label: Date
    type: daterange
    minDate: '2001-01-23'
    maxDate: '2030-10-13'
    yearRange: 10
    conditions: created_at >= ':after' AND created_at <= ':before'

使用日期和日期范围的默认值

 myController::extendListFilterScopes(function($filter) {
                'Date Test' => [
                    'label' => 'Date Test',
                    'type' => 'daterange',
                    'default' => $this->myDefaultTime(),
                    'conditions' => "created_at >= ':after' AND created_at <= ':before'"
                ],
            ]);
        });
 //return value must be instance of carbon
  public function myDefaultTime() {
        return [
            0 => Carbon::parse('2012-02-02'),
            1 => Carbon::parse('2012-04-02'),
        ];
    }

Number

number - 显示要输入的单个数字的输入。

age:
    label: Age
    type: number
    default: 14
    conditions: age >= ':filtered'

Number Range

numberrange - 显示要输入的两个数字的输入作为数字范围。 条件参数以:min和:max传递。

visitors:
    label: Visitor Count
    type: numberrange
    default: 
        0:10
        1:20
    conditions: vistors >= ':min' and visitors <= ':max'

Text

text - 显示要输入的字符串的文本输入。 您可以指定将在输入大小属性中注入的size属性(默认值:10)。

username:
    label: Username
    type: text
    conditions: username = :value
    size: 2

扩展列表行为

有时您可能希望修改默认列表行为，有几种方法可以执行此操作。

• 覆盖控制器方法
• 覆盖视图
• 扩展列定义
• 注入CSS行类
• 扩展过滤器范围
• 扩展模型查询
• 自定义列类型

覆盖控制器方法

您可以将自己的逻辑用于控制器中的index操作方法，然后可选地调用List behaviorindex父方法。

public function index()
{
   //
   //Do any custom code here
   //
   //Call the ListController behavior index() method
    $this->asExtension('ListController')->index();
}

覆盖视图

ListController行为有一个主容器视图，您可以通过在控制器目录中创建名为_list_container.htm的特殊文件来覆盖它。 以下示例将向列表添加侧栏:

<?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>

该行为将调用Lists小部件，该小部件还包含您可以覆盖的众多视图。 这可以通过指定列出配置选项中描述的customViewPath选项来实现。 窗口小部件将首先在此路径中查找视图，然后回退到默认位置。

# Custom view path
customViewPath: $/acme/blog/controllers/reviews/list

注意: 最好使用子目录，例如list，以避免冲突。

例如，要修改列表正文行标记，请在控制器目录中创建名为list/_list_body_row.htm的文件。

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

扩展列定义

您可以通过在控制器类上调用extendListColumns静态方法从外部扩展另一个控制器的列。 此方法可以采用两个参数，$list表示Lists小部件对象，$model表示列表使用的模型。 以此控制器为例:

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

使用extendListColumns方法，您可以将额外的列添加到此控制器呈现的任何列表中。 检查$model的类型是否正确是个好主意。 这是一个例子:

    Categories::extendListColumns(function($list, $model) {
        if (!$model instanceof MyModel)
            return;
        $list->addColumns([
            'my_column' => [
                'label' => 'My Column'
            ]
        ]);
    });

您还可以通过覆盖控制器类中的listExtendColumns方法在内部扩展列表列。

class Categories extends \Backend\Classes\Controller
{
    [...]
    public function listExtendColumns($list)
    {
        $list->addColumns([...]);
    }
}

$list对象提供以下方法。

每个方法都采用类似于列列配置的列数组。

注入CSS行 class

您可以通过在控制器类上添加listInjectRowClass方法来注入自定义css行类。 此方法可以采用两个参数，$record表示单个模型记录，$definition包含List窗口小部件定义的名称。 您可以返回包含行类的任何字符串值。 这些类将添加到行的HTML标记中。

class Lessons extends \Backend\Classes\Controller
{
    [...]
    public function listInjectRowClass($lesson, $definition)
    {
       //Strike through past lessons
        if ($lesson->lesson_date->lt(Carbon::today())) {
            return 'strike';
        }
    }
}

扩展过滤范围

您可以通过在控制器类上调用extendListFilterScopes静态方法，从外部扩展另一个控制器的过滤器作用域。 此方法可以使用参数$filter来表示Filter小部件对象。 以此控制器为例:

    Categories::extendListFilterScopes(function($filter) {
        $filter->addScopes([
            'my_scope' => [
                'label' => 'My Filter Scope'
            ]
        ]);
    });

提供的作用域数组类似于列出过滤器配置。

您还可以在内部将过滤器范围扩展到控制器类，只需覆盖listFilterExtendScopes方法。

class Categories extends \Backend\Classes\Controller
{
    [...]
    public function listFilterExtendScopes($filter)
    {
        $filter->addScopes([...]);
    }
}

$filter对象提供了以下方法。

扩展模型查询

可以通过覆盖控制器类中的listExtendQuery方法来扩展列表数据库模型的查询查询。 此示例将通过将withTrashed作用域应用于查询来确保列表数据中包含软删除的记录:

public function listExtendQuery($query)
{
    $query->withTrashed();
}

列表过滤器模型查询也可以通过覆盖listFilterExtendQuery方法进行扩展:

public function listFilterExtendQuery($query, $scope)
{
    if ($scope->scopeName == 'status') {
        $query->where('status', '<>', 'all');
    }
}

扩展记录集

可以通过覆盖控制器类中的listExtendRecords方法来扩展列表使用的记录集合。 此示例使用记录集合上的sort方法更改记录的排序顺序。

public function listExtendRecords($records)
{
    return $records->sort(function ($a, $b) {
        return $a->computedVal() > $b->computedVal();
    });
}

自定义列类型

自定义列表列类型可以使用插件注册类的“registerListColumnTypes”方法在后端注册。 该方法应返回一个数组，其中键是类型名称，值是可调用函数。 可调用函数接收三个参数，原生$value，$column定义对象和模型$record对象。

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

使用自定义列表列类型就像使用type选项按名称调用它一样简单。

# ===================================
#  List Column Definitions
# ===================================
columns:
    secret_code:
        label: Secret code
        type: uppercase