【譯】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的官方論壇上提出