October cms-Backend （后端-widgets）_october 文件标签-优快云博客

文章目录

widgets 小部件

widgets 小部件

Generic Widgets 通用小部件

小部件是后端用的
其作用跟前端的Component组件功能一致
它们十分相似，因为它们是功能性的模块化捆绑包，提供partials，并使用别名进行命名。
关键区别在于后端窗口小部件使用YAML标记进行配置并将其自身绑定到后端页面。
窗口小部件类位于plugin目录的widgets目录内。
目录名就是widget类名的小写
widgets支持assets和partials
目录结构如下所示

widgets/
  /form
    /partials
      _form.htm     <=== Widget partial file
    /assets
      /js
        form.js     <=== Widget JavaScript file
      /css
        form.css    <=== Widget StyleSheet file
  Form.php          <=== Widget class

类定义

通用widget类必须继承自Backend\Classes\WidgetBase类
与任何其他插件类一样，通用窗口小部件控制器应属于插件名称空间。小部件控制器类定义示例：

<?php namespace Backend\Widgets;

use Backend\Classes\WidgetBase;

class Lists extends WidgetBase
{
    /**
     * @var string A unique alias to identify this widget.
     */
    protected $defaultAlias = 'list';

    // ...
}

小部件类必须包含render（）方法，以通过渲染小部件partial来生成小部件标记。例：

public function render()
{
    return $this->makePartial('list');
}

要将变量传递给partials，可以将其添加到$ vars属性。

public function render()
{
    $this->vars['var'] = 'value';

    return $this->makePartial('list');
}

或者，您可以将变量传递给makePartial（）方法的第二个参数：

public function render()
{
    return $this->makePartial('list', ['var' => 'value']);
}

AJAX handlers

窗口小部件实现与后端控制器相同的AJAX方法。 AJAX处理程序是窗口小部件类的公共方法，其名称以on前缀开头
小部件AJAX处理程序和后端控制器的AJAX处理程序之间的唯一区别是，当您在小部件partial中引用小部件的方法时，应使用小部件的getEventHandler方法返回小部件的方法名。

<a
    href="javascript:;"
    data-request="<?= $this->getEventHandler('onPaginate') ?>"
    title="Next page">Next</a>

当从窗口小部件类或partial调用时，ajax方法将调用它自己
例如，如果窗口小部件使用mywidget的别名，则将使用mywidget :: onName作为处理程序的目标。上面将输出以下属性值：

data-request="mywidget::onPaginate"

绑定小部件到controllers

在开始在后端页面或partial页面中使用小部件之前，应将其绑定到后端控制器。
使用小部件的bindToController方法将其绑定到控制器。
初始化小部件的最佳位置是控制器的构造函数。例：

public function __construct()
{
    parent::__construct();

    $myWidget = new MyWidgetClass($this);
    $myWidget->alias = 'myWidget';
    $myWidget->bindToController();
}

绑定窗口小部件后，您可以在控制器的视图或partial中通过别名访问它

<?= $this->widget->myWidget->render() ?>

表单小部件

使用表单小部件，您可以将新的控件类型添加到后端表单。它们提供了为模型提供数据所共有的功能。表单窗口小部件必须在插件注册文件（Plugin registration file）中注册。
表单窗口小部件类位于插件目录的formwidgets目录内。
目录名就是widget类名的小写
widgets支持assets和partials
目录结构如下所示

formwidgets/
  /form
    /partials
      _form.htm     <=== Widget partial file
    /assets
      /js
        form.js     <=== Widget JavaScript file
      /css
        form.css    <=== Widget StyleSheet file
  Form.php          <=== Widget class

类定义

表单窗口小部件类必须扩展Backend\Classes\FormWidgetBase类。
与其他任何插件类一样，通用小部件控制器应属于插件命名空间plugin namespace.
可以在后端表单字段定义（form field definition）文件中使用注册的窗口小部件。
表单小部件类定义示例：

namespace Backend\Widgets;

use Backend\Classes\FormWidgetBase;

class CodeEditor extends FormWidgetBase
{
    /**
     * @var string A unique alias to identify this widget.
     */
    protected $defaultAlias = 'codeeditor';

    public function render() {}
}

属性

表单小部件的属性可以用 form field configuration来设定
只需在类上定义可配置属性，然后调用fillFromConfig方法以将它们填充在init方法定义中。

class DatePicker extends FormWidgetBase
{
    //
    // Configurable properties
    //

    /**
     * @var bool Display mode: datetime, date, time.
     */
    public $mode = 'datetime';

    /**
     * @var string the minimum/earliest date that can be selected.
     * eg: 2000-01-01
     */
    public $minDate = null;

    /**
     * @var string the maximum/latest date that can be selected.
     * eg: 2020-12-31
     */
    public $maxDate = null;

    //
    // Object properties
    //

    /**
     * {@inheritDoc}
     */
    protected $defaultAlias = 'datepicker';

    /**
     * {@inheritDoc}
     */
    public function init()
    {
        $this->fillFromConfig([
            'mode',
            'minDate',
            'maxDate',
        ]);
    }

    // ...
}

然后，在使用小部件时，可以从表单字段定义中设置属性值。

born_at:
    label: Date of Birth
    type: datepicker
    mode: date
    minDate: 1984-04-12
    maxDate: 2014-04-23

表单部件注册

插件应通过覆盖插件注册类中的registerFormWidgets方法来注册表单小部件
该方法返回一个包含键中的小部件类和小部件短代码作为值的数组。例：

public function registerFormWidgets()
{
    return [
        'Backend\FormWidgets\CodeEditor' => 'codeeditor',
        'Backend\FormWidgets\RichEditor' => 'richeditor'
    ];
}

短代码是可选的，可在引用“表单”字段定义( Form field definitions)中的窗口小部件时使用，它应该是唯一值，以避免与其他表单字段发生冲突。

加载表单数据

表单小部件的主要目的是与您的model进行交互，这意味着在大多数情况下是通过数据库加载和保存值。
呈现表单小部件时，它将使用getLoadValue方法请求其存储的值。
getId和getFieldName方法将为表单中使用的HTML元素返回唯一的标识符和名称。
这些值通常在渲染时传递给窗口小部件partial。

public function render()
{
    $this->vars['id'] = $this->getId();
    $this->vars['name'] = $this->getFieldName();
    $this->vars['value'] = $this->getLoadValue();

    return $this->makePartial('myformwidget');
}

在基本级别上，表单小部件可以使用input元素将用户input值发送回。
从上面的示例中，可以在myformwidget partial 内部使用准备好的变量来呈现元素。

<input id="<?= $id ?>" name="<?= $name ?>" value="<?= e($value) ?>" />

保持表单数据

用getSaveValue方法来获取并存储得到的input数据
可以override这个方法来修改行为

public function getSaveValue($value)
{
     return $value;
}

在某些情况下，您有意不希望提供任何值，例如，表单小部件在不保存任何内容的情况下显示信息。
返回从Backend\Classes\FormField类派生的特殊常量FormField::NO_SAVE_DATA，以使该值被忽略

public function getSaveValue($value)
{
     return \Backend\Classes\FormField::NO_SAVE_DATA;
}

报告小部件

报表小部件可以在后端仪表板和其他后端报表容器中使用。
报表窗口小部件必须在插件注册文件中注册。

类定义

报表小部件类应扩展Backend \ Classes \ ReportWidgetBase类。与任何其他插件类一样，通用窗口小部件控制器应属于插件名称空间。
该类应重写render方法，以便呈现窗口小部件本身。
与所有后端窗口小部件类似，报表窗口小部件使用partial和特殊的目录布局。目录布局示例：

plugins/
  rainlab/                    <=== Author name
    googleanalytics/          <=== Plugin name
      reportwidgets/          <=== Report widgets directory
        trafficsources        <=== Widget files directory
          partials
            _widget.htm
        TrafficSources.php    <=== Widget class file

报告窗口小部件类定义：

namespace RainLab\GoogleAnalytics\ReportWidgets;

use Backend\Classes\ReportWidgetBase;

class TrafficSources extends ReportWidgetBase
{
    public function render()
    {
        return $this->makePartial('widget');
    }
}

小部件partial可以包含您要在小部件中显示的任何HTML标记。
标记(markup)应与report-widget类一起包装在DIV元素中。
使用H3元素输出小部件标题是可取的。
示例小部件部分：

<div class="report-widget">
    <h3>Traffic sources</h3>

    <div
        class="control-chart"
        data-control="chart-pie"
        data-size="200"
        data-center-text="180">
        <ul>
            <li>Direct <span>1000</span></li>
            <li>Social networks <span>800</span></li>
        </ul>
    </div>
</div>

在报表小部件内，您可以使用任何图表或指标(charts or indicators)，列表或任何其他想要的标记。
请记住，报告小部件扩展了通用后端小部件，并且您可以在报告小部件中使用任何小部件功能。
下一个示例显示了列表报告窗口小部件标记

<div class="report-widget">
    <h3>Top pages</h3>

    <div class="table-container">
        <table class="table data" data-provides="rowlink">
            <thead>
                <tr>
                    <th><span>Page URL</span></th>
                    <th><span>Pageviews</span></th>
                    <th><span>% Pageviews</span></th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>/</td>
                    <td>90</td>
                    <td>
                        <div class="progress">
                            <div class="bar" style="90%"></div>
                            <a href="/">90%</a>
                        </div>
                    </td>
                </tr>
                <tr>
                    <td>/docs</td>
                    <td>10</td>
                    <td>
                        <div class="progress">
                            <div class="bar" style="10%"></div>
                            <a href="/docs">10%</a>
                        </div>
                    </td>
                </tr>
            </tbody>
        </table>
    </div>
</div>

属性

报表小部件可能具有用户可以使用检查器管理的属性：
在这里插入图片描述
这些属性应在小部件类的defineProperties方法中定义。这些属性在组件文章（components article.）中进行了描述。例：

public function defineProperties()
{
    return [
        'title' => [
            'title'             => 'Widget title',
            'default'           => 'Top Pages',
            'type'              => 'string',
            'validationPattern' => '^.+$',
            'validationMessage' => 'The Widget Title is required.'
        ],
        'days' => [
            'title'             => 'Number of days to display data for',
            'default'           => '7',
            'type'              => 'string',
            'validationPattern' => '^[0-9]+$'
        ]
    ];
}

注册

插件可以通过覆盖插件注册类中的registerReportWidgets方法来注册报告窗口小部件。
该方法应返回一个数组，
该数组的键为窗口小部件类，值为窗口小部件配置（标签，上下文和所需的权限）。
例：

public function registerReportWidgets()
{
    return [
        'RainLab\GoogleAnalytics\ReportWidgets\TrafficOverview' => [
            'label'   => 'Google Analytics traffic overview',
            'context' => 'dashboard',
            'permissions' => [
                'rainlab.googleanalytics.widgets.traffic_overview',
            ],
        ],
        'RainLab\GoogleAnalytics\ReportWidgets\TrafficSources' => [
            'label'   => 'Google Analytics traffic sources',
            'context' => 'dashboard',
            'permissions' => [
                'rainlab.googleanaltyics.widgets.traffic_sources',
            ],
        ]
    ];
}

label元素为“添加小部件”弹出窗口定义小部件名称。
context元素定义了可以使用小部件的上下文。
October的报表小部件系统允许在任何页面上托管报表容器，并且容器上下文名称是唯一的。
“仪表板”页面上的窗口小部件容器使用仪表板content上下文