在Matomo(以前的Piwik)中,an分析报告只是一组二维数据,存储为数据表对象,并由API方法返回。
控件可以显示这些报告ViewDataTable类:这叫做a报告显示.
报表可视化可以是任何格式。例如,sparkline可视化输出图像。然而,大多数可视化都会输出一个HTML小部件,允许用户在不同的可视化之间切换。
报表可视化是一个类扩展ViewDataTable.
每个可视化都有一个唯一的ID,该ID由类常量命名ID
.类名称中必须能够指定它们,因此它们由这个ID引用,而不是它们的类名viewDataTable
查询参数。使用完全限定的类名将过于冗长。
的viewDataTable
查询参数为ViewDataTable的相关JavaScript代码。它表示用户对视图的选择(通过单击可视化的页脚图标),因此将覆盖代码中指定的任何可视化类型。
用户可以通过单击可视化本身下方显示的图标之一来切换可视化:
这些图标叫做页脚的图标.并不是所有的可视化都必须以这种方式可用。例如,访问日志使用自己的可视化,但由于它只能使用来自一个报表的数据(Live.getLastVisitsDetails
)其他报告的页脚中没有。
要详细了解大多数报表显示中围绕可视化的控件,请阅读用户文档以获得报表可视化.
有两种方法可以在控制器中输出报表的可视化。
最简洁的方法是调用控制器:renderReport ()
方法:
类控制器{公共函数myReport(){返回$this->renderReport(__FUNCTION__);}}
此方法将创建一个新的ViewDataTable
实例化并渲染它。报表可以通过ViewDataTable.configure
事件(阅读更多有关事件).
另一种方法是手动创建和配置ViewDataTable
实例:
类控制器{公共函数myReport() {$view = \Piwik\ViewDataTable\Factory::build($defaultType = '表',//可视化类型$apiAction = 'MyPlugin. ')myReport', $controllerMethod = 'MyPlugin. MyPlugin. 'myReport”);$view->config->show_limit_control = false;$view->config->show_search = false;$view->config->show_goals = true;/ /……再做一些配置…返回视图- >渲染();}}
ViewDataTable:渲染()
将通过调用报告API检索报告并返回要显示的HTML。
注意:报表可视化将使用AJAX自我刷新,这意味着每个报告都必须有一个控制器方法(如上图所示)。你可以使用ViewDataTable
在控制器方法之外,但它仍然必须引用控制器方法。
ViewDataTable
通过设置以下属性来配置实例:
视图- >配置
(配置
对象):报告的显示方式视图- > requestConfig
(RequestConfig
对象):如何获得数据,以及在某种程度上显示什么一旦报表的控制器方法存在,将其显示在页面上是很简单的:
class Controller{//页面公共函数索引(){$view = new view ("@MyPlugin/index.twig");//生成报表可视化,在视图中使用$view->myReport = $this->myReport();返回视图- >渲染();} //报告方法公共函数myReport(){返回$this->renderReport(__FUNCTION__);}}
的index.twig
模板看起来像这样:
My Report
{{myReport}}
控件也可以将报表提供给仪表板WidgetsList.addWidgets
事件:
// WidgetsList的事件处理器。在MyPlugin/MyPlugin.php文件的公共函数addWidgets() {WidgetsList::add('我的类别名称','我的报告标题','MyPlugin', 'myReport');}
Matomo用户将能够看到和选择myReport在小部件选择器中。
注意:任何控制器方法都可以嵌入到仪表板中,而不仅仅是报表。因此,如果您有一个弹出窗口,您想使作为仪表板小部件可用,您可以使用WidgetsList.addWidgets这样做我们就是这么做的游客概要在仪表板中可用。
下面是一个可视化列表,称为核心可视化,默认情况下可用(由它们的viewDataTable ID):
表格
:行和列的表(用于查看报告的主要可视化)tableAllColumns
:与表格
但包括两个额外的处理指标tableGoals
:与表格
但包括目标指标和网站的目标graphVerticalBar
:垂直柱状图(使用jqPlot)graphPie
:饼图(使用jqPlot)graphEvolution
:显示一组报告随时间演变的线形图(指标以不同的系列显示)云
:报表标签的标签云。每个标签的字体大小与给定的度量成正比。sparkline
:表示某一指标随时间变化的折线图。输出一个图像,而不是HTML。您可以在创建时使用这些可视化ViewDataTable实例,而无需安装第三方插件。
插件可以提供它们自己的可视化,可以在插件内使用,也可以作为应用于任何报告的新可视化。
的Treemap可视化Plugin是一个提供可视化的插件的例子,可以用于任何报告。
若要创建不输出HTML的可视化,请直接从ViewDataTable
.
要创建HTML可视化,可以从可视化
代替。这个基类提供了在所有核心可视化中常见的行为:显示页脚图标、限制选择器、报告文档、搜索框……
在你的新类中,你要做的第一件事是使用类常量设置必要的可视化元数据:
ID
(必需)参数中设置的唯一IDviewDataTable
查询参数TEMPLATE_FILE
(必需):对树枝模板文件的引用,例如:“@MyPlugin / _myDataTableViz.twig”
FOOTER_ICON
:要显示在可视化页脚中的图标的相对路径FOOTER_ICON_TITLE
:当用户将鼠标悬停在页脚图标上时使用的工具提示(可以是翻译令牌)一个例子:
类MyVisualization扩展可视化{const ID = ' MyVisualization ';const TEMPLATE_FILE = '@MyPlugin/ _myvisualizer .twig';const FOOTER_ICON = 'plugins/MyPlugin/images/myvisualization.png';const FOOTER_ICON_TITLE = '我的可视化';}
可视化可以定义它们自己的显示属性(除了在配置)通过创造自己的配置
类。这个新类必须从配置并且可视化必须为getDefaultConfig ()
方法,该方法创建此新类的实例。例如:
class MyVisualizationConfig extends Config {public $showMagicWidget = true;public $ show免责声明= false;}类MyVisualization扩展可视化{//…公共静态函数getDefaultConfig(){返回新的MyVisualizationConfig();}}类控制器{公共函数myReport($fetch = false) {$view = \Piwik\ViewDataTable\Factory::build($defaultType = MyVisualization::ID, $apiAction = 'MyPlugin. ID ')myReport', $controllerMethod = 'MyPlugin. MyPlugin. 'myReport”);$view->config->showMagicWidget = false;返回视图- >渲染();}}
可视化也可以创建自己的RequestConfig类获取影响请求的属性。过程如上所示。
如果需要,自定义可视化可以改变基库加载的数据ViewDataTable
类。
进化图可视化这样做是为了获得最近N个时期的报告,这样它就可以随时间显示数据。的treemap可视化执行此操作以获取上一时期的数据,以便显示每行的变化百分比。
方法更改请求,以更改所加载的数据request_parameters_to_modify美元
财产。这可以在可视化:beforeLoadDataTable ()
方法。例如:
类MyVisualization扩展可视化{//…公共函数beforeLoadDataTable() {$date = Common::getRequestVar('date');$yesterday =日期::工厂($ Date)->subDay(1)->toString();$this->config->request_parameters_to_modify['date'] = $yesterday;}}
注意:如果更改加载的数据,可能还需要重写可视化:isThereDataToDisplay ()
方法。否则,即使您正在显示的报表没有数据,也可能不会出现“no data”消息。
可视化可以在加载报表数据后通过覆盖以下方法之一来修改报表数据:
beforeGenericFiltersAreAppliedToLoadedDataTable ()
:由可视化
中的优先级筛选器加载报表数据之后美元的过滤器
执行Display属性。前调用泛型过滤器执行。
如果您需要使用报告的完整数据(例如,在它被限制/截断/排序/等等之前),则重写此方法。
afterGenericFiltersAreAppliedToLoadedDataTable ()
:由可视化
在加载报表数据之后,在执行优先级筛选之后,以及在泛型过滤器执行。
如果您需要在报表数据被排序/过滤/限制等之后使用该方法。,但在应用表示过滤器之前。
afterAllFiltersAreApplied ()
:由可视化
在执行所有筛选器(优先级、泛型和队列)之后。
如果在报表数据准备好显示后需要使用该方法,则重写该方法。
控件也可以操作报表数据美元的过滤器
显示属性。
如果您希望允许Matomo用户在任何报告上使用可视化(通过单击适当的页脚图标),请将其添加到全局可用可视化列表中ViewDataTable.addViewDataTable
事件:
// ViewDataTable的事件处理程序addViewDataTable(&$visualizations) {$visualizations[] = 'Piwik\Plugins\MyPlugin\ visualizations \MyVisualization';}
以这种方式公开的可视化必须具有FOOTER_ICON
而且FOOTER_ICON_TITLE
ViewDataTable元数据集。
除非你的可视化非常简单,或者构建在另一个可视化(比如“表”可视化)上,否则你可能需要扩展ViewDataTable的客户端逻辑。
所有的ViewDataTable
客户机端逻辑封装在数据表
JavaScript类(位于dataTable.js文件)。如果你在扩展可视化
您应该直接进行扩展数据表添加您自己的客户端逻辑。如果您正在扩展另一个可视化,则必须扩展该可视化的JavaScript类。例如:
(function ($, require) {var exports = require('piwik/UI');/** *类,处理MyVisualization可视化的UI行为。* /出口。MyVisualization = function (element) {exports.DataTable。调用(这个元素);};.extend美元(exports.MyVisualization。原型,exports.DataTable。原型,{//…});} (jQuery,需要));
当扩展数据表
惟一需要重写的方法是init ()
方法。在这里,你应该放置可视化的初始化代码:
.extend美元(exports.MyVisualization。原型,exports.DataTable。prototype, {init: function () {exports.DataTable.prototype.init.call(this);this._bindEventCallbacks(这一点。元素美元);this._addSeriesPicker(这一点。元素美元);/ /……等……}})
扩展JavaScript类后,必须在datatable_js_type美元
可视化的属性:
类MyVisualization扩展可视化{//…公共函数beforeRender() {$this->config->datatable_js_type = 'MyVisualization';}}
一些可视化可能需要自定义UI控件。例如,默认值图可视化添加了一个名为选择器系列用户界面。
添加新控件有两种方式:
它们可以完全通过JavaScript添加(就像使用选择器系列)
为了实现这一点,在可视化的JavaScript类中动态创建HTML元素init ()
方法。看到系列拾取器源代码举个例子。
或者控件的HTML可以通过可视化来呈现,并且可视化的JavaScript类可以将一些逻辑附加到HTML上
为了实现这一点,将HTML添加到可视化的树枝模板中,然后在可视化的JavaScript中将逻辑绑定到HTML中。看到树图插件例如(缩小按钮是一个额外的控件)。
根< div >
的每个报表可视化都会有数据表
CSS类。它们还将有一个基于所使用的可视化的CSS类。它看起来就像dataTableViz *
在哪里*
可视化的未命名空间类名称(例如dataTableVizHtmlTable
).
控件选择所有报表可视化.dataTable
CSS选择器。可以使用可视化特定的CSS类选择特定类型的报表可视化,例如,.dataTableVizHtmlTable
或.dataTableVizHtmlTable > .dataTableWrapper
.
你也可以使用datatable_css_class美元
属性可以添加更多的CSS类。如果需要自定义可视化的外观,此属性可能很有用,但仅适用于特定的报表。