翻譯 Tim Rose 的kibana外掛教程-簡單視覺化外掛

atxiaoxian發表於2019-04-10
ROS視覺化

kibana官方沒有外掛的開發教程，Tim Rose的教程寫的十分詳盡，也是官方推薦的。由於這個系列的教程是英文版的，且基於kibana4，近日需要做kibana的開發，硬啃下這些教程之後，且根據kibana6.3.2版本做了些改進，記錄下來，留下個爪。由於本人水平有限，錯漏的地方歡迎大家指出。

原文連結：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是一個物件，我們可以讀到他的值

現在我們就完成了我們的時鐘外掛了：

翻譯 Tim Rose 的kibana外掛教程-簡單視覺化外掛
你可以在0.4.0找到完整的原始碼和一大堆的評論。

下一步

我們剛剛建立了一個簡單的外掛，完全不包含認為資料的，所以下一步，當然是建立一個使用聚合資料的外掛啦。在下一章，我們會建立一個簡單的標籤雲視覺化外掛。

相關文章