翻译 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找到完整的源码和一大堆的评论。

下一步

我们刚刚创建了一个简单的插件，完全不包含认为数据的，所以下一步，当然是创建一个使用聚合数据的插件啦。在下一章，我们会创建一个简单的标签云可视化插件。