翻译 Tim Rose 的kibana插件教程-简单可视化插件

kibana官方没有插件的开发教程，Tim Rose的教程写的十分详尽，也是官方推荐的。因为这个系列的教程是英文版的，且基于kibana4，近日须要作kibana的开发，硬啃下这些教程以后，虽然这些教程比较古老，不少代码不能用了，可是开发思想仍是通用的。记录下来，留下个爪。因为本人水平有限，错漏的地方欢迎你们指出。

原文连接：www.timroes.de/writing-kib…

原文标题：Writing Kibana 4 Plugins – Simple Visualizations

简单可视化插件

你须要先阅读基础篇，才能阅读本文。 在本章中，咱们会介绍如何定义一个简单的可视化插件。这个简单的插件不须要来自elasticsearch的数据，只展现静态内容（就像markdown 可视化插件同样）。在后面的章节再构建消费动态数据的可视化插件。本文将介绍一个简单的时钟插件，以后你能够在仪表盘中添加一个时间。

做者版的代码能够在GitHub上面找到： timroes/tr-k4p-clock

整个编码工做会分红以及版本，会在各个阶段分别给出对应的tag，读者能够自行查看不一样的版本。

注册你的可视化插件

首先建立package.json和index.js，如咱们前面讲到的。另外目录名称也要选择合适的。

若是你想要为你的插件建立一个可视化图形，你须要添加一个js文件，咱们暂时把他叫作clock.js，放在插件根目录的public文件夹下。

在咱们为插件添加内容以前，咱们须要注册这个插件，添加以下代码到clock.js:

module.exports = function(kibana) {
  return new kibana.Plugin({
    uiExports: {
      visTypes: [ 'plugins/<plugin-name>/clock' ]
    }
  });
};
复制代码

在<plugin-name>的地方换成你的插件名称（接下来的代码片断也是这样作）。

uiExports对象描述了你的插件将从何种扩展点来为用户接口添加功能。在本例中，咱们只是用了visTypes数组来注册了一个可视化功能（实际上你能够注册多个）。你定义的字符串会被传递给webpack是用来解决依赖问题，会把plugins/<plugin-name>映射到插件的public文件夹下。这样你就能够获得任意你想要的文件的引用了（本例中，clock会被定义成引用clock.js）。

目前就已经把插件成功注册到kibana了。

定义你的可视化插件

在你注册完插件以后，下一步就是定义他了。往clock.js里面添加点内容，经过一个简单的html片断来定义可视化插件。

define(function(require) {
  function ClockProvider(Private) {
    var TemplateVisType = Private(require('ui/template_vis_type/TemplateVisType'));
    return new TemplateVisType({
      name: 'trClock', // the internal id of the visualization
      title: 'Clock', // the name shown in the visualize list
      icon: 'fa-clock-o', // the class of the font awesome icon for this
      description: 'Add a digital clock to your dashboards.', // description shown to the user
      requiresSearch: false, // Cannot be linked to a search
      template: require('plugins/<plugin-name>/clock.html') // Load the template of the visualization
    });
  }

  require('ui/registry/vis_types').register(ClockProvider);

  return ClockProvider;
});
复制代码

如你所见，public下的所有js文件都是符合requirejs（AMD规范）的，所有都被包裹在define函数里面。

更新

这个教程是好久以前写的了，如今的话是用webpack打包的，因此如今不须要符合AMD规范了。你能够直接require进来。由于库里面的文件就是按照amd规范写的，在这里我就不修改了，后面的教程会抛弃amd的写法。

首先，咱们须要写一个provider函数，就是一个基于angularjs的provider函数，参数是由angular主动注入的，在本例中咱们只需注入Private服务。 Private服务是kibana的一个angular服务，用来从angular的providers实例化或者加载服务。从下一行能够看出，咱们用requirejs来加载ui/template_vis_type/TemplateVisType服务（这是一个angular provider，用private服务来实例化TemplateVisType这个provider），这个requirejs加载angular服务的一个通用模式。

你获得了实例化的TemplateVisType（这是一个你的每一个可视化插件都须要的基础的类型，这个类型自带一个html模板展现给kibana用户），你的插件须要返回一个新的TemplateVisType的实例，这个实例存储这全部关于你的可视化插件的信息。

下面是模板字段的介绍：

• name 是一个kibana内部的id，用来识别你的插件，应该是全局惟一的（就跟插件的文件夹名称同样），你最好加上一个前缀，就像我加上tr。
• title & description 将展现在kibana的可视化界面上
• requiesearch 默认为true，像本例这样的不须要数据的静态插件
• icon 一个类名，表示FontAwsome中的一个图标。会在kibana的好几处地方使用到
• template 插件的html片断，准确的说是插件实际内容片断（不是编辑片断或者其余东西）。咱们仍是使用require把clock.html从public文件夹下引入进来，咱们等一下再来往里面写入内容。

完成provider函数以后，你还须要把这个provider注册到vistypes中去。嗯，尽管你已经在index.js中定义了他，可是这里还有一个open issue，须要解决。就像你上面作的同样，须要获取注册函数，而后调用他的注册函数。

最后，你能够从模块中返回provider函数，就算不这么作你的可视化插件也能工做，可是若是你这么作，就能够在其余地方使用这个provider了。kibana的插件都是这样作的，因此我也推荐你这么作。

写一个简单的模板

下一步就是在public文件夹下建立clock.html文件了，咱们在上面写到，咱们的插件须要这个模板。咱们就从一个很是简单的html开始：

<div class="clockVis"> 15:00:00 </div>
复制代码

这是咱们插件的第一个里程碑，若是你在kibana中加载这个插件，你能够从可视化列表中找到这个插件，而后把他保存为一个图表，添加到仪表盘，像其余插件同样。你能够找到这个代码在GitHub0.1.0

在html片断中，你须要把全部的东西都放在一个根元素下，若是你最直接把文本放在根目录下，这个是不会显示的。

添加样式

为了添加一些样式，咱们来建立一个clock.css文件，并放在public文件夹下。只是添加一点居中样式，和一点字体样式：

.clockVis {
  width: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  color: #555;
  font-weight: bold;
  font-size: 2.5em;
}
复制代码

如今咱们要作的就是把样式文件在clock.js中引入进来，而后咱们就添加下面一行代码（注：必定要在provider函数以外）。

require('plugins/<plugin-name>/clock.css');
复制代码

你也能够用less，只要改一下文件后缀便可

为时钟插件加逻辑

为了提高咱们插件，咱们须要为咱们的时钟加点逻辑代码。所以咱们须要把angular的控制器和模板关联到一块儿。 angular模块已经通过了kibana的包装了，因此为了给咱们的插件（咱们应该为插件建立一个新的模块），建立一个新的控制器，咱们能够在clock.js中添加如下代码：

var module = require('ui/modules').get('<module-name>');
module.controller('ClockController', function($scope) {
  // ...
});
复制代码

ui/modules模块有一个get方法，能够用来建立或者获取一个angular模块，把模块的名字（惟一）看成参数传进去，能够用你的插件名称做为模块名称。get方法的第二个参数是一个你所依赖的模块组成的数组（就像你调用angular.module同样），第二个参数不写就是不依赖任何模块。一个最重要的模块你可能会须要的就是kibana模块，就是上面提供private服务的模块。可是本例中，咱们用不到这些。

在本例中，咱们直接把这些代码写在clock.js中，在大些的插件，你可能想要把他放在一个单独的文件下，只要在主文件下把这个文件引入就能够了（本例中，主文件就是clock.js）。

咱们来完成控制器函数，使用$timeout服务来每分钟刷新如下当前时间：

module.controller('ClockController', function($scope, $timeout) {
  var setTime = function() {
    $scope.time = Date.now();
    $timeout(setTime, 1000);
  };
  setTime();
});
复制代码

如今咱们就能够把控制器和模板关联起来，显示咱们的时间了，如日常咱们在angular下作的同样：

<div class="clockVis" ng-controller="ClockController">
  {{ time | date:'HH:mm:ss' }}
</div>
复制代码

若是你如今把这个插件添加到仪表盘，那你就有了一个真正能工做的时钟了。代码能够在0.3.0找到

可视化选项

这里还能够作一个优化，让用户本身去选择时间的显示格式。也就是给咱们的插件添加一些参数，当用户编辑的时候，显示出来。

咱们首先添加一个名字叫clock-deitor.html（public文件夹下），来在侧边栏展现选项的参数。

<div class="form-group">
  <label>Time Format</label>
  <input type="text" ng-model="vis.params.format" class="form-control">
</div>
复制代码

一样，这里也是一个简单的angular文档片断，在咱们的编辑器html片断中，（从上面能够看出，也是一个普通的模板），有一个vis变量。这是可视化对象自带的，包含自身信息的一个对象，在这个对象中有一个params对象，能够用来存储咱们插件的参数选项。这就是咱们为何要绑定vis.params.format到咱们的输入框中（format只是设置的名称）。

咱们须要来修改一下，传递给TemplateVisType构造函数的对象，来注册咱们的编辑器文档片断。咱们添加一个params对象以下，完成的片断请参考GitHub：

{
  // ...
  params: {
    editor: require('plugins/<plugin-name>/clock-editor.html'),
    defaults: {
      format: 'HH:mm:ss'
    }
  }
  // ...
}
复制代码

咱们注册完上面所些的片断（经过require）以后，咱们同时给咱们的参数设置一个默认值。

咱们须要作的最后一件事就是，在咱们的主文档片断（clock.html）中，使用这个设置：

<div class="clockVis" ng-controller="ClockController">
  {{ time | date:vis.params.format }}
</div>
复制代码

如上面提到的，在这个模板中vis是一个对象，咱们能够读到他的值

如今咱们就完成了咱们的时钟插件了：

你能够在 0.4.0找到完整的源码和一大堆的评论。

下一步

咱们刚刚建立了一个简单的插件，彻底不包含认为数据的，因此下一步，固然是建立一个使用聚合数据的插件啦。在下一章，咱们会建立一个简单的标签云可视化插件。