翻譯 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找到完整的源碼和一大堆的評論。

下一步

咱們剛剛建立了一個簡單的插件，徹底不包含認爲數據的，因此下一步，固然是建立一個使用聚合數據的插件啦。在下一章，咱們會建立一個簡單的標籤雲可視化插件。