October cms-Backend （后端-widgets）

widgets 小部件

Generic Widgets 通用小部件

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

widgets//form/partials_form.htm     <=== Widget partial file/assets/jsform.js     <=== Widget JavaScript file/cssform.css    <=== Widget StyleSheet fileForm.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方法返回小部件的方法名。

<ahref="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/jsform.js     <=== Widget JavaScript file/cssform.css    <=== Widget StyleSheet fileForm.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 Birthtype: datepickermode: dateminDate: 1984-04-12maxDate: 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 namegoogleanalytics/          <=== Plugin namereportwidgets/          <=== Report widgets directorytrafficsources        <=== Widget files directorypartials_widget.htmTrafficSources.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><divclass="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上下文