从AngularJS开始

前期:这份文件是工作草稿,远非完美。随着我们对AngularJS做更多的工作,我们将不断改进这一点。

通过使用AngularJS,我们试图实现不同的目标:

  • 从后端解耦Matomo(以前是Piwik) UI。理想情况下,在几年内,我们将拥有一个基于HTML、JavaScript和CSS(没有PHP)的完全独立的UI,它使用所有Matomo Reporting API。这带来了很多好处:
    • 减少前端和后端的复杂性
    • 降低复杂性带来更快的开发,更少的bug……
    • 该项目对非PHP开发人员很有吸引力
    • 提供离线版本(将来的某一天)
    • ...
  • AngularJS允许我们为JavaScript世界编写单元测试
  • 摆脱jQuery汤[0][1]减少前端的复杂性
  • 更多可重用代码(模型、服务、过滤器、指令……)
  • 将一些工作从服务器端转移到客户端
  • 更快的响应(特别是当我们可以使用AngularJS的路由和AMD).如果你不熟悉AMD ->请先忽略

在开始使用AngularJS之前

我建议你看一些AngularJS的好处和最佳实践的视频和资源。理解AngularJS的工作原理是很重要的,特别是要注意陷阱和最佳实践。

一些随机的笔记和技巧

  • 理解AngularJS作用域是非常重要的。

    提示:

    • 孤立的范围In指令是首选的
    • 一些指令,如ng-if和ng-repeat,会创建自己的作用域
    • 在使用ng-model时,所有绑定的数据都应该加点,否则你就做错了。您可能想知道为什么一个值没有更新,这将花费您数小时来解决这个问题。例子:< div ng-model = " model.searchfield " >而不是< div ng-model = " searchfield " >
  • 要理解的第二重要的事情可能是指令
  • 尽量减少数据绑定元素的数量(< 200)
  • AngularJS的ng-repeat指令在超过2500个双向数据绑定后变得很慢。
  • 有时候你只需要视图中的某些属性(HTML模板)。试着给它们加上前缀视图.例如< div ng-show = ' view.showPaginator ' >
  • 当Angular检测到页面中存在jQuery版本时,它会使用完整的jQuery实现来代替jqLite。
  • 这里有两个过滤器的规则:首先,如果可以通过修饰底层数据来达到同样的效果,比如添加一个'formattedValue'属性,那么就这样做。它总是更快,因为它只发生一次,而不是每个摘要周期发生多次。其次,当你有充分的理由编写一个过滤器时,要确保它的速度快得令人眼花缭乱。”如果可能的话,不要访问DOM,因为过滤器被调用了很多很多次。阅读更多
  • 不访问一个控制器内的DOM,只从指令和只有在需要的时候
  • AngularJS是独特的,因为它不强迫你使用一个模型,但它是绝对推荐的。没有类可以扩展来创建模型,但你应该总是使用模型,并保持控制器尽可能短。
  • 服务、工厂、供应商之间的区别:
    • 一个服务是一个单例,每当你请求一个服务相同的实例将返回
    • 每当您请求一个实例时,都会创建一个新实例工厂
    • 供应商优点是它们可以在模块配置阶段进行配置。服务和工厂都是提供者。阅读更多
  • 如果你还不了解承诺,那就读一读:https://www.sitepoint.com/overview-javascript-promises/
  • 当你用承诺工作时,你会注意到这一点.catch ()而且最后()不能在IE8中工作。使用承诺(“最后”)()代替。阅读更多

命名空间

代码组织/文件结构

关于最佳的文件结构有很多讨论。在过去,我们将一个特性划分为多个文件夹javascript样式表,……从现在开始,我们想要根据特性来组织文件推荐它也能在大型项目中发挥最好的作用。

基本上,我们在插件文件夹中为每个特性创建一个文件夹。假设我们想创建一个“站点选择器”,然后创建以下文件:+ CoreHome + angularjs + siteselector + siteselector.directive.js + siteselector.directive.less + siteselector.directive.html + siteselector.controller.js + siteselector.filter.js + siteselector-model.service.js + search.png + common + images + filters + corehomespecpic .js

有时候你的插件中可能有一些可重用的组件,在这种情况下,你可以把它们放到一个常见的文件夹中。这有什么好处呢?除此之外,当你打开一个插件文件夹时,你会立即注意到一个插件做了什么,而如果你只看到这个文件夹,情况就不是这样了javascript模板而且样式表文件夹。另一个优势是,理论上,我们可以将一个特性提取到一个单独的存储库中,并与其他人共享单个小部件。

一个模块总是以.module.js.服务或工厂总是以.service.js,控制器为.controller.js,指示为.directive.js还有一个滤镜.filter.js.文件名是小写的,单词之间应该用破折号分隔:site-selector.directive.js.如果有一个应用程序的配置文件必须命名为appname.config.js,如。piwikApp.config.js

目前有angularjs命名空间在插件中,这有点烦人,我们知道。长期来看,我们将删除此文件夹。中期来看——一旦我们有了更多的Angular组件——我们至少会给这个文件夹起一个更好、更有意义的名字。对于现有的jQuery代码资产结构,很难找到最不恼人的解决方案。

有关更详细的命名约定,请参阅Angular命名指南

如果一个组件,比如一个过滤器,可以在不同的插件中重用,并且不是特定于插件的,我们将它们放入CoreHome / angularjs常见

  • CoreHome
    • angularjs
    • 常见的
      • 过滤器
      • evolution.js
      • translate.js
      • 服务
      • piwik-api.js
      • 指令
      • focusif.js
      • focus-anywhere-but-here.js

文件名总是小写,单词之间用破折号分隔。通常,每种类型有一个文件。type - eg过滤器,指令或服务-在这种情况下不需要出现在文件名中,因为它已经放在相关文件夹中。

重要的如我们的指示总是以…开头piwik -例如< div piwik-onenter = " close ()" >

编码风格指南

  • 在AngularJS中,有很多方法来定义指令的属性(Class, HTML attributes, Elementname,…)我们使用的是HTML属性,因为我们的目标不是W3C标准,所以我们选择不给属性加上“data-”前缀来保持模板的整洁。
  • 看这里完整的风格指南:https://github.com/johnpapa/angularjs-styleguide。我们将此风格指南用于任何类型,只要在本文档中没有提到不同的类型。

例子

Matomo中的一些特性已经通过AngularJS实现了。

它们使用不同的组件

我们目前没有使用AngularJS的路由。我们的目标是长期使用它来摆脱piwikBroadcast和许多其他类。

测试

我们使用业力++ [Mocha] (https://mochajs.org/)来编写单元测试。点击这里阅读更多信息:https://github.com/matomo-org/matomo/blob/master/tests/angularjs/README.md

如何记录

TBD

可能是有趣的链接:Docular

插件体系结构

AngularJS依赖注入允许插件覆盖或扩展任何他们想要的东西,比如一个指令。因此,插件架构或多或少是开箱即用的。

例如,一个插件可以“挂钩”到某个指令,扩展/改变控制器行为等。这个视频可能会给你一些启发:https://www.youtube.com/watch?v=rzMrBIVuxgM

更多即将到来!

AngularJS模块

  • https://bower.io/search/?q=angularjs !% 2 fsearch fangular % 2
  • https://ngmodules.org/
Baidu