如果你想知道,请阅读这篇指南
Matomo使用以下JavaScript库:
只有当新的JS库对你的插件至关重要时,才包含它们,并确保使用TypeScript工作流,这样当同一个库的不同版本被用于其他插件时,就不会发生冲突。如果许多插件决定使用自定义库,UI将变慢。
插件可以告诉Matomo加载JS和CSS资产文件。
这是通过AssetManager.getStylesheetFiles
而且AssetManager.getJavaScriptFiles
事件。如果你是活动的新手,请查看我们的活动指南.这些事件定义在你的插件文件中(如果你的插件名是YourPluginName
然后它们就被定义在$ matomoDir /插件/ YourPluginName / YourPluginName.php
).
要在UI中加载一个文件,只需将应该加载的路径附加到给定的文件中美元的文件
数组:
//这些方法需要在你的插件php文件中的公共函数registerEvents(){返回数组('AssetManager. php ')getStylesheetFiles' => 'getStylesheetFiles', '资产管理器。getJavaScriptFiles' => 'getJavaScriptFiles',);}公共函数getStylesheetFiles(&$files) {$files[] = "plugins/MyPlugin/stylesheets/ mystylesheetfiles .less";$files[] = "plugins/MyPlugin/stylesheets/myCssStylesheet.css";}公共函数getJavaScriptFiles(&$files) {$files[] = "plugins/MyPlugin/javascripts/myJavaScript.js";}
在生产环境中,Matomo会将所有JavaScript文件连接成一个文件并缩小它。少文件将被编译成CSS并合并成一个CSS文件。Matomo不会在每个请求上合并和缩小JavaScript和CSS文件,因为这样做需要很长时间。它们只在某些事件上合并,比如启用一个新插件时。
为了确保您的更改将实际可见和执行,您需要启用开发模式,以防您还没有这样做:
/控制台开发:启用
这样JavaScript文件就不会被合并,并且您可以调试原始的JavaScript源代码。
从4.5.0版本开始,可以使用Vue和TypeScript为UI创建组件(尽管注意,你不必同时使用两者;你可以使用Vue和ESnext (EcmaScript最先进的版本)一起使用,或者不使用Vue只编写普通的TypeScript)。
Vue和TypeScript文件通过webpack使用Vue CLI服务进行处理,该服务在Matomo中全局配置。要利用这一点,就要创造vue
而且vue / src
插件中的子文件夹。然后将您的代码(TypeScript, ES, Vue)添加到src
子文件夹。确保添加一个index.ts
或index.js
文件到子文件夹,并导出您想要在浏览器中以编程方式访问的所有内容(例如,通过其他插件)。
有关使用Matomo的Vue代码示例,请参见ExampleVue
插件源代码。
编写完代码后,必须将其构建到UMD文件中。运行./console vue:构建MyPlugin
命令来构建Vue/TypeScript代码。编译后的UMD将在vue / dist
文件夹,并且应该与插件的其余部分一起分发(因为我们不希望所有用户都能访问node或有技术能力手动编译我们的JavaScript)。
在开发时,建议使用——看
选项vue:构建
因此,您不必不断地重新运行命令。
注意:没有必要将生成的UMD文件添加到“AssetManager.getJavaScriptFiles”
事件。Matomo将自动检测是否有一个并使用它(如果插件被激活)。
eslint
Vue CLI被配置为在构建umd时在文件上运行ESlint。如果ESlint基于我们配置的规则之一发现了一个样式问题,它将在的输出中打印出来vue:构建
.有时,从错误消息中不清楚实际问题或修复方法。
在这种情况下,最简单的方法是在搜索引擎中搜索规则名称。每个规则都有相关的在线文档,描述了错误的含义、规则存在的原因以及如何修复错误。
Eslint在构建Vue umd时会自动运行,但如果你想直接从命令行运行它,可以运行如下命令:
$ NPM运行eslint -- --ext .js,.ts,。vue插件/并且
不推荐使用AngularJS,请改用Vue.js 3。
下面是一个特殊元素的列表,你应该知道当你开发你的插件或贡献:
#根
:对用户显示和可见的所有内容的根元素。
#内容
:根元素,包含在主报告菜单下显示的所有内容和“选择器”控件行(即,周期选择器,段选择器等)。
.top_controls
:包含“selector”控件的元素。这些元素中只有一个。
.widgetContent
:每个小部件的根元素。事件被发布到这个特定的元素。
Matomo定义了几个全局变量window.piwik
)有关目前的要求。以下是它们的含义以及使用方法:
piwik.token_auth
:token_auth当前用户的。应该在AJAX请求中使用,但不应该出现在URL中。piwik.piwik_url
:这个Matomo实例的URL。piwik.userLogin
:当前用户的登录句柄(如果有当前用户)。piwik.idSite
:当前选择的网站ID。piwik.siteName
:当前选择的网站名称。piwik.siteMainUrl
:当前选择网站的URL。piwik.language
:当前选择的语言代码(例如,在
).在为你的贡献或插件编写JavaScript时,你最好遵守以下的编码约定。
Matomo Core定义了许多应该被新插件和贡献重用的类。这些类可以用来改变UI显示的页面,加载弹出窗口,从CSS中获取主题颜色值。
该类被认为已弃用,仅由于历史原因存在,因为一些组件仍在使用它。只要有可能,你应该使用angularjs的组件,比如美元的位置.在不可能的情况下,广播
可以使用。
的广播
对象直接存储在窗口
对象,应该用来解析当前URL,在菜单下面的区域加载一个页面,并加载持久弹窗。
注意:虽然对象存储在窗口
而不是JS命名空间,它仍然可以使用需要
通过调用要求(广播)
.
广播
包含几个解析Matomo URL的方法。Matomo的主UI在URL的哈希值中存储二级查询参数集。这是在菜单下面加载的URL。广播
的URL解析函数将在散列中查找查询参数值以及主查询字符串,因此使用它们而不是直接访问是很重要的window.location.href
.
广播
提供以下功能:
isHashExists ()
:如果URL存在,则返回该URL的哈希值。假
否则如果。getHashFromUrl ()
:返回URL的哈希值。可以是空字符串。getSearchFromUrl ()
:返回查询字符串。extractKeyValuePairsFromQueryString ()
:将查询字符串转换为查询参数名称与查询参数值的对象映射。getValuesFromUrl ()
:返回对象映射查询参数名称和当前URL的查询参数值。getValueFromUrl ()
:按名称返回当前URL的一个查询参数值。getValueFromHash ()
:按名称返回当前URL散列中的一个查询参数值。getHash ()
:返回URL的哈希值。方法中的方法文档,以了解有关单个函数的更多信息插件/ CoreHome / javascript / broadcast.js
文件。
要在Matomo主菜单下面加载新页面,请使用propagateNewPage ()
函数带有指向控制器方法的URL,其输出应该显示:
(函数(require) {var broadcast = require('broadcast');broadcast.propagateNewPage (' index . php ?模块= MyPlugin&action = mySpecialPage’,真正的);})(需要);
AJAX请求在非vue,香草JavaScript应该使用ajaxHelper
全球。
的ajaxHelper
类应该在需要创建AJAX请求时使用。不应该使用插件. ajax美元
直接。ajaxHelper
做了一些额外的事情,使得编写不安全的代码更加困难。它还跟踪当前正在进行的AJAX请求,这对用户界面测试.
使用ajaxHelper
,创建一个实例,配置它,然后调用send ()
方法。要了解更多信息,请阅读源代码中的文档(位于插件/睡眠/ javascript / ajaxHelper.js
).
例如:
(function (require, $) {var ajaxHelper = require('ajaxHelper');var ajax = new ajaxHelper();ajax.setUrl (index . php ?模块= Actions&action = getPageUrls&idSite = 1和日期= today&period =天');ajax。setCallback(function (response) {$('#myReportContainer').html(response);});ajax.setFormat (html);//期望的响应格式ajax.setLoadingElement('#myReportContainerLoading');ajax.send ();})(需要,jQuery);
以下是开发过程中可能出现的一些常见问题的解决方案:
vue:构建——手表
正在运行,但JavaScript没有正确构建,请尝试重新启动该命令。在内部,它会在再次观看之前清除webpack缓存,这可以解决一些问题。npm test -- --clearCache
命令。