【译】Tim Rose 的kibana插件教程-字段格式化插件

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

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

原文标题Writing Kibana 4 Plugins – Field Formatters

你须要先读基础篇，才能开始本章节的学习。

在前面章节的教程中，咱们专一于自定义可视化插件的编写。除了可视化插件，kibana还有其余的扩展点，其中一个就是字段格式化插件，任意一个索引pattern均可以被设置为使用该字段格式化插件来格式化任意一个字段，当显示该字段的时候，该字段格式化插件就能够将他显示为任意格式，而不只仅是直白的数据。

kibana也自带了一些字段格式化器（好比把数字显示为颜色），本章节的教程，会指导你怎么样写一个字段格式化插件。咱们会建立一个 Trend 格式化插件。他会在数字或者百分数字段的后面显示一个上箭头或者下箭头，根据数据是正或者负。这个字段格式化器能够被用在那些表明一个趋势的字段上面。和以前同样，插件的代码能够在GitHub上面找到：

timroes/tr-k4p-fieldformatters

注册一个新的字段格式化插件

注册一个字段格式化器，跟注册一个可视化插件是同样的。在插件中添加一个新的数组到index.js的uiExports下：

// Rest of file stripped (see GitHub for full file)
uiExports: {
  fieldFormats: ['plugins/tr-k4p-fieldformatters/trend']
}
复制代码

这就注册了trend.js到插件的public文件夹下

bug注意 在当前的kibana（ Kibana 4.4.1）发布版本中，fieldFormats数组尚未被正确使用，替代的办法是，须要把你的字段格式化插件放在visTypes数组下。因为trend.js只须要被合适的注册，因此index.js出如今哪一个数组并不重要。在issue #6040 查看他的解决进度。

建立字段格式化插件

咱们须要在插件public文件加下建立trend.js（跟可视化插件是同样的）。内容以下：

function TrendProvider(Private) {

  var _ = require('lodash');
  var FieldFormat = Private(require('ui/index_patterns/_field_format/FieldFormat'));

  _.class(Trend).inherits(FieldFormat);
  function Trend(params) {
    Trend.Super.call(this, params);
  }

  Trend.id = 'tr-trend';
  Trend.title = 'Trend';
  Trend.fieldType = [
    'number',
    'percentage'
  ];

  Trend.prototype._convert = function(value) {
    // TO BE DONE
  };

  return Trend;
}

require('ui/registry/field_formats').register(TrendProvider);
复制代码

文件包含了一个简单的provider函数，用来建立formatter类。在咱们的案例中，咱们叫他TrendProvider。这个函数在最后一行的地方被注册到了字段格式化注册处。

在provider函数的内部，咱们作了如下工做：

从ui/index_patterns/_field_format/FieldFormat继承了FieldFormat类，就是上面用lodash克隆的那几行。

给Trend类设置了一些属性，用来设置咱们的字段格式化插件：

• id，字段格式化插件的惟一标记，应当尽量惟一，由于kibana是经过这个字段来引用这个插件的，因此用一个带有前缀的id是百利无一害的，推荐使用我的或者公司的名称作id前缀。
• title， 是在kibana为字段设置字段格式化插件的时候，显示的名称。
• fieldType ，是一个数组，指明这个插件能格式化什么类型的字段。在kibana设置字段格式化插件的地方，若是该插件能格式化这个字段类型，那么就会被显示出来。这个数组合法的值有：number, boolean, date, ip, attachment, geo_point, geo_shape, string, murmur3 (Murmur3 插件哈希), unknown (unknown 字段类型).

实际进行类型转换的是在_convert函数，咱们很快就会到这一步了。

最后，provider须要把刚刚建立的字段格式化类返回。

格式化字段值

实际的字段格式化工做是在_convert函数中完成的，这个函数的第一个参数是这个字段的值，把你想显示的东西从函数中返回便可。在咱们Trend格式化插件的场景中，咱们作如下的格式化工做：

Trend.prototype._convert = function(value) {
  return (value > 0) ? value + ' ↑' : value + ' ↓';
};
复制代码

为了方便，咱们没有考虑0的状况，只是根据值的正负，简单的添加了上箭头或者下箭头。

若是你的插件如今被正确加载了，你能够去任意一个kibana的索引设置中，设置一个数字或者百分数，那你就能够看见你的Trend字段格式化插件出如今你的格式化可选项当中，若是你选了这个格式化插件做为这个字段的格式化插件，那任什么时候候这个字段显示的时候，就能够在值的后面看见上箭头或者下箭头了。

不管函数返回什么都会被当作文本显示，html片断是不被容许的。可是这是不够的，有些场景中须要渲染html，例如图片格式化插件，或者颜色格式化插件等，为了可以渲染html，咱们能够用一个对象来替代刚才的函数，这个对象有两个属性，html和text:

Trend.prototype._convert = {
  text: function(value) {
    // Return a textual representation of the value
  },
  html: function(value) {
    // The return value of this function can contain HTML, which will be rendered.
  }
};
复制代码

text函数和上面的直接把_convert声明成一个函数是同样的，html函数的返回值能够包含html片断，会被正确地渲染。

html函数在kibana可以渲染html的地方会被调用，（例如发现栏，可视化插件，等几乎任何地方），text函数在几个html不能被正确渲染的地方调用（好比在仪表盘上使用filter的时候，filter bar上显示的值就是文本）。

html函数的第二个参数是这个字段自己，这个参数能够用来获取一些这个字段自己的一些信息，当你在格式化的时候。例如field.type能够得到这个字段原来的类型（当你支持多种类型的时候）。值得注意的是，这个值可能会是null或者undefined，当kibana不能正确的获取他的字段类型的时候，例如在显示一个聚合数据的时候。这第二个参数对text函数来讲是不可用的。

查看完整的例子，参考GitHub上的trend.js 。

下一步

字段格式化能够更复杂多样。给用户提供了自定义字段的格式的功能。若是你想要建立一个更复杂的字段格式化插件，我建议你参考一下kibana现有的格式化插件。他们当中的一些包含了带有设置的很复杂的实现和（例如 Color 或者 Date 式化插件）。

若是你有任何问题，欢迎在评论区提出，联系我或者在elasticsearch的官方论坛上提出