Dashingのカスタムウィジェットを作成する

Dashing Preview

Dashingの紹介

Dashingというダッシュボード作成のフレームワークをご存知ですか? Dashingを使えば、上のようなダッシュボードを簡単に作ることができます。いいですよね?欲しいですよね?

この記事では、自分で一からウィジェットを作成する方法を解説していきます。Dashingの基本的な使い方は、公式ページ を見ればすぐわかると思うのでここでは割愛です。

目次

サンプルダッシュボードの作成

ウィジェットに必要なファイル

ジョブファイルを作成

ジョブのコードを書く

ウィジェットのコードを書く

ウィジェットを使う

ウィジェットを公開する

サンプルダッシュボードの作成

このチュートリアルで使うサンプルのダッシュボードをまず作成しましょう。サンプルダッシュボードは My Dashboard という名前にして、Fizz Buzz ウィジェットを作成しましょう。 FizzBuzzウィジェットは一定間隔で数字をインクリメントしていって、3で割り切れる数字の場合はFizzと、5で割り切れる場合はBuzzと、どちらでも割り切れる場合は、FizzBuzzと表示するウィジェットです。

Widget Preview

新しいダッシュボードを作成するのは以下のコマンドを実行するだけです。

1
2
3
4
5
6
7
8
9
$ dashing new my_dashboard
      create  my_dashboard
      create  my_dashboard/.gitignore
      create  my_dashboard/Gemfile
      create  my_dashboard/README.md
      .... 省略 ....
      create  my_dashboard/widgets/text/text.coffee
      create  my_dashboard/widgets/text/text.html
      create  my_dashboard/widgets/text/text.scss

これでカレントディレクトリにmy_dashboardというディレクトリが作成されます。このディレクトリがダッシュボードのベースとなるので、以降の作業はすべてmy_dashboardをrootディレクトリとして読んでください。

ウィジェットに必要なファイル

Dashingはフレームワークなので、ルール従って開発すれば簡単に自分のウィジェットを作成することができます。ルールの一つに必要なファイルを用意することと、Dashingの命名規則に従ってそれらのファイル/ディレクトリ名をつけることがあります。

新たにウィジェットを作成するために必要なファイルは主に2つに分かれます。

ひとつはウィジェットのメインとなるウィジェットファイルで/widgets ディレクトリ配下に作られます。

もう一つはウィジェットにデータを渡すためのジョブファイルで、/jobsディレクトリ配下に作られます。

まずは、ウィジェットファイルを作成しましょう。

ウィジェットファイルを作成

テンプレートとなるファイルをコマンドで作成します。

1
2
3
4
5
$ dashing generate widget fizz_buzz
      create  widgets
      create  widgets/fizz_buzz/fizz_buzz.coffee
      create  widgets/fizz_buzz/fizz_buzz.html
      create  widgets/fizz_buzz/fizz_buzz.scss

簡単に各ファイルの役割を説明すると

fizz_buzz.html はウィジェットのhtmlそのものです。ジョブから渡されたデータをこのhtml内でレンダリングします。

fizz_buzz.scss はウィジェットのスタイルを書く場所です。

fizz_buzz.coffee はウィジェットで使うjavascriptを書くための場所です。ファイル名からもわかる通り、単なるJSファイルではなくcoffee script形式で書かないといけません。(私は普通のJSで書かせてほしいのですが、、、)

ウィジェットの表示に効果をつけたり、ウィジェットの初期化動作などを書くことができます。

このファイルは見た目のそこまでこだわらなければ、ほぼ空っぽでも構いません。これはDashingのいいところの一つだと思います。つまり、javascirptを全然知らなくても、それなりのウィジェットを作ることができるからです。

ジョブファイルを作成

次にジョブファイルを作成します。

1
2
3
$ dashing generate job fizz_buzz
      create  jobs
      create  jobs/fizz_buzz.rb

fizz_buzz.rb はウィジェットに渡すためのデータを作るコードを書くファイルです。ジョブファイルの基本はcronのように定期的に実行されるRufus Schedulerで、 メインのコードをrufusによっての定期実行されるブロックの中に書いていきます。

1
2
3
4
SCHEDULER.every '2s' do
  # ここにメインのコードを書く
  # 2sなのでウィジェットのデータが2秒毎に更新されることになる
end

ジョブのコードを書く

まずはウィジェットにデータを提供するためのジョブのコーディングから始めましょう。以下のようなコードになります。

fizz_buzz.rb @ Gist

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
class FizzBuzz
  FIZZ=3
  BUZZ=5

  def initialize
    @current_num = 1
  end

  def fizzbuzz
    if fizzbuzz?
      out = "fizzbuzz"
    elsif fizz?
      out = "fizz"
    elsif buzz?
      out = "buzz"
    else
      out = @current_num
    end
    go_next
    out
  end

  private

  def go_next
    @current_num+=1
  end

  def fizz?
    (@current_num % 3) == 0
  end

  def buzz?
    (@current_num % 5) == 0
  end

  def fizzbuzz?
    (@current_num % (FIZZ*BUZZ)) == 0
  end

end

fb = FizzBuzz.new

SCHEDULER.every '5s', :first_in => 0 do
  send_event('fizz_buzz', { value: fb.fizzbuzz })
end

1 ~ 43行は普通のRubyで書いたFizzBuzzクラスとそれのインスタンスを作っているだけです。これらのコードは、SCHEDULERの外に書かれているので定期実行はされず、dashing startで ダッシュボードを起動した時の一度だけ実行されるので一度だけ初期化したい処理 (例えば、ステータスを保存する変数とか)を書きます。

46行目のsend_eventがジョブファイルのキモです。

send_eventは一つ目の引数にウィジェットの名前を指定します。この名前は、後述するレイアウトファイルに書くウィジェットのhtmlのdata-id属性で指定する名前とマッチしないといけません。

二つめの引数には、ウィジェットに渡すデータをハッシュ形式で指定します。ハッシュのキーはfizz_buzz.html内のdata-bind属性で指定している名前と同じにします。

fizz_buzz.html

1
<div data-bind="value"></div>

send_eventで送ったデータはdata-bind="value"属性をもっているdivタグの内容として挿入されます。

つまり、send_event('fizz_buzz', { value: "fizzbuzz" }) とすると、fizz_buzz.html は以下のように自動で変更されます。

1
<div data-bind="value">fizzbuzz</div>

この自動でhtmlの内容が更新される仕組みはbatman.jsdata bindingを使って実現しています。

ウィジェットのコードを書く

ジョブファイルでデータを更新できる準備は整ったので今度はそのデータをウィジェットとして表示するコードを書きます。

まずは、ウィジェットそのもののhtmlを担当するファイルです。今回はチュートリアルなのでシンプルにしています。

fizz_buzz.html @ Gist

1
2
<h1 class="title" data-bind="title"></h1>
<div data-bind="value"></div>

。1行目はウィジェットのタイトルを表示します。このタイトルは後述するレイアウトファイルのdata-title属性で指定した値が表示されます。

2行目は前述したように、send_eventから送られてくるデータを表示します。

次にウィジェットのスタイルを担当するファイルです。

fizz_buzz.scss @ Gist

1
2
3
.widget-fizz-buzz {
  background-color: #444;
}

ここでは、ウィジェットの背景色を指定しています。セレクタは.widgetで始めてその後に自分のウィジェットの名前をつなげた名前にします。そして、ブロック内にそのウィジェットに関わるスタイルを書いていきます。

ここで少し命名規則に注意です。 rubyのジョブファイルではウィジェットの名前はアンダースコア区切りのfizz_buzzでしたが、こっちはCSSファイルなので、ウィジェットの名前の単語をつなげるのは-にしないといけません。

最後にウィジェットにエフェクトをつけるcoffee scriptです。何もエフェクトを使わなければここはテンプレートのままでも構いませんが、せっかくなので少しだけエフェクトをつけてみます。

fizz_buzz.coffee @ Gist

1
2
3
4
5
6
7
class Dashing.FizzBuzz extends Dashing.Widget

  ready: ->
    # ここは初期化時に実行したいエフェクトを書く

  onData: (data) ->
    $(@node).fadeOut().fadeIn()

$(@node)でウィジェット全体のDOMを取得することができるので、これでデータが更新される度にエフェクトが効きます。

ウィジェットを使ってみる

これでFizzBuzzウィジェットは出来上がりました。あとはウィジェットを使うだけです。まずはレイアウトファイルを作成します。ここではレイアウトファイルの名前はfizz_buzz_displayとしましたが、なんでも構いません。

1
2
3
$ dashing generate dashboard fizz_buzz_display
      exist  dashboards
      create  dashboards/fizz_buzz_display.erb

レイアウトファイルができたら以下のように編集します。

fizz_buzz_display.erb @ Gist

1
2
3
4
5
6
7
<div class="gridster">
  <ul>
    <li data-row="1" data-col="1" data-sizex="1" data-sizey="1">
      <div data-id="fizz_buzz" data-view="FizzBuzz" data-title="Fizz Buzz"></div>
    </li>
  </ul>
</div>

data-id属性が一番重要な部分です。ここで表示するウィジェットを指定しています。fizz_buzz.rb内のsend_eventの第一引数でデータを送るウィジェットを指定しましたが、それはここの名前を指定しています。

data-view属性はウィジェットのcoffee scriptのクラスと一致しないといけません。coffee scriptはマッチするdata-view@nodeにマップします。

data-title属性で指定したタイトルがfizz_buzz.html内のdata-bind="title"を持つ要素の内容として表示されます。ここでは”Fizz Buzz”と指定しているので

1
<h1 class="title" data-bind="title">Fizz Buzz</h1>

となります。

これでFizzBuzzウィジェットが表示されるはずです。dashing startでダッシュボードを起動して、http://localhost:3030/fizz_buzz_displayにアクセスしてみてください。ちゃんと表示されたでしょうか?

今回は、チュートリアル用に個別でfizz_buzz_displayを作りましたが、FizzBuzzウィジェットは他のダッシュボードでも使えます。使いたければ、

1
2
3
<li data-row="1" data-col="1" data-sizex="1" data-sizey="1">
  <div data-id="fizz_buzz" data-view="FizzBuzz" data-title="Fizz Buzz"></div>
</li>

をレイアウトファイルに書くだけです。

ウィジェットを公開する

最後に作成したウィジェットは公開して使ってもらいましょう。

DashingはウィジェットをGistで管理しています。自分のGistページで新たにGistを作成して、ウィジェットに必要なファイル名と同じ名前でGistの内容に各ファイルのコードを書きます。

今回で言えば、以下の4つのファイルを一つのGistに作成します。

  • fizz_buzz.html
  • fizz_buzz.css
  • fizz_buzz.coffee
  • fizz_buzz.rb

Gistを作成したら、インストールできるか確認してください。

1
$ dashing install GIST_ID

GIST_IDは作成したGistのIDです。また必須ではありませんが、自分のウィジェットの使い方をGistにREADMEとして書いておくのが定番のようです。

正しく動けば、Additional WidgetsのWikiを修正して登録するのを忘れずに。

Comments

« Dockerfileを書く時の注意とかコツとかハックとか 「ライト、ついてますか」から学ぶ問題発見の心得 »