スタイルガイドジェネレータHologramとBrowserStackでクロスブラウザチェックをする

こんにちは、デザインチームの@_ringogirlです。

弊社では現在スタイルガイドの構築をHologramというgemを使って進めています。

構築の過程で機能の拡張が必要になりプラグインを作ることにしましたが、 Hologramのプラグインに関する記事が少ないため、作り方をまとめてみました。

今回はサンプルとしてBrowserStackを使って複数のブラウザからスクリーンショットを撮り、スタイルガイドに貼り付けるプラグインを作ってみます。

Hologram

Ruby製のスタイルガイドジェネレーターです。CSSに書いたコメントからスタイルガイドを生成してくれます。 SassやLESSにも対応しています。

trulia/hologram

Hologramのプラグイン

READMEには載っていませんがHologramはプラグインを作る機能を提供しています。このプルリクエストでプラグインを作る機能が追加されました。コメントにサンプルのプラグインもあるので、気になる方はぜひ参考にしてみてください。

BrowserStackを使ってスクリーンショットを撮るプラグインを作る

BrowserStackを使って複数ブラウザからCSSコンポーネントのスクリーンショットを撮り、ドキュメントに貼り付けるプラグインを作っていきます。

Hologramの初期設定や使い方については以下のブログ記事が参考になります。

プラグインファイルの準備

Hologramはrubyのファイルを直接指定してプラグインを読み込みます。今回は設定ファイルと同じディレクトリにhologram_screenshot.rbというファイルを作成しました。設定ファイルに以下のように追記します。

設定ファイル（hologram_config.yml）

plugins:
  - hologram_screenshot.rb

プラグインファイルの実装

プラグインにはフックできる場所いくつかあり、それらを使ってプラグインの処理を実装していくことになります。

まず、Hologram::pluginクラスを継承します。クラス名はファイル名をアッパーキャメルケースにしないと読み込まれないので注意してください。

class HologramScreenshot < Hologram::plugin
  def initialize(config, args)
    @name = 'screenshot'

    super(config, args)
  end
end

@nameはプラグイン名で、後ほど使用します。

block(comment_block, file_name, has_plugin)

CSSのドキュメントコメントがパースされた後に実行されるフックです。パースされた情報をもったcomment_blockや、コメントが書かれていたCSSのパスfile_nameが引数として与えられます。

スクリーンショットを撮るときにスタイルが適用されるように、ファイルを読み込みます。今回はscssでスタイルを書いたので、トランスパイルしておきます。

def block(comment_block, file_name, has_plugin)
  @sass = Sass::Engine.for_file(file_name, {}).render
end

plugin(plugin_data, comment_block, file_name)

ドキュメントコメントに以下のように書くとその内容がplugin_dataに渡されます。 initializeで定義した@nameと同じものを[[[plugin:PLUGIN_NAMEの形式で記述します。

[[[plugin:screenshot
<button class="btn btn-primary">Primary Button</button>
<a class="btn btn-primary" href="#">Primary Link Button</a>
]]]

[[[plugin:PLUGIN_NAME]]]コメントはplugin関数の戻り値に置き換えられます。今回はスクリーンショットを埋め込みたいので、<img>タグを文字列として返してみます。

def plugin(plugin_data, comment_block, file_name)
  # スクリーンショット用のhtmlを生成する
  build_html(plugin_data)

  # BrowserStack Screenshot APIでスクリーンショットを生成
  screenshots = @browserstack.screenshots

  # スクリーンショットから<img>タグを生成して返す
  # 内部で@sassを使ってスタイルを適用する
  build_styleguide_html(screenshots)
end

build_htmlではBrowserStackがスクリーンショットを撮るためのWebサーバーに表示するHTMLを作っています。長くなってしまったため具体的なコードはここでは省きますが、処理としては以下の様なことをしています。

WEBrickをlocalhost:3000で起動する
BrowserStackLocalを起動し、localhostにアクセスできるようにする
Servletで/にアクセスしたときにplugin_dataを含むHTMLをbuild_htmlで作る（その時に@sassも埋め込んでスタイルを適用する）
BrowserStack Screenshot APIでhttp://localhost:3000/のスクリーンショットを撮る

finalize

プラグインの最後で実行されます。 pagesにはドキュメントとして生成されたHTMLファイル名や、comment_blockと同じ値が渡されています。

def finalize(pages)
  p "Complete screenshot."
  p "Generated screenshots were in #{pages.keys.first}."
end

プラグインファイル

省いたところもありますが、プラグインは以下のようになりました。基本的にはこのような構成にするとプラグインが動作します。

require 'hologram'
require 'sass'

class HologramScreenshot < Hologram::plugin
  def initialize(config, args)
    @name = 'screenshot'

    super(config, args)
  end
  
  def block(comment_block, file_name, has_plugin)
    @sass = Sass::Engine.for_file(file_name, {}).render
  end
  
  def plugin(plugin_data, comment_block, file_name)
    # スクリーンショット用のhtmlを生成する
    build_html(plugin_data)

    # BrowserStack Screenshot APIでスクリーンショットを生成
    screenshots = @browserstack.screenshots

    # スクリーンショットから<img>タグを生成して返す
    # 内部で@sassを使ってスタイルを適用する
    build_styleguide_html(screenshots)
  end
  
  def finalize(pages)
    p "Complete screenshot."
    p "Generated screenshots were in #{pages.keys.first}."
  end
  
  ## WEBRickの起動
  
  ## WEBRickのServletで`/`アクセス時の処理
  
  ## BrowserStackLocalの起動
end

プラグインを実行してみる

ドキュメントの準備

ドキュメント用にbutton.scssを用意して以下のようにしました。 bootstrapを読み込んで、.btn-primaryの色を変えています。

button.scss

/*doc
---
title: Buttons
name: button
category: Components
---

ボタンの コンポーネントです。

```html_example
<button class="btn btn-primary">Primary Button</button>
<a class="btn btn-primary" href="#">Primary Link Button</a>
```

[[[plugin:screenshot
<button class="btn btn-primary">Primary Button</button>
<a class="btn btn-primary" href="#">Primary Link Button</a>
]]]

*/

.btn-primary {
  background-color: #e91e63;
  border-color: #c2185b;
}

本題からは逸れますが、上記のようにbootstrapのクラスを上書きするのは好ましくないので、bootstrap-sassなどを使ってSassの変数で上書きすると無駄にクラスを増やさないですみます。

プラグインの実行

実際にプラグインを動作させるには以下のコマンドを実行します。

hologram -c hologarm_config.yml --screenshot

@nameで設定した値をオプションとして渡すとプラグインがアクティブになります。

以下が実際にプラグインを動作させて生成されたドキュメントです。（HologramのテーマであるCortanaを使っています。）

f:id:ringo_girl:20151112135517p:plain

HTMLのコードの下にそれぞれスクリーンショットが貼り付けられているのがわかると思います。今回はWindows7 IE8.0、Windows7 firefox37.0でスクリーンショットを撮ってみました。コンポーネント単位ですが複数ブラウザでの見え方がわかるので、レイアウトの崩れなどが事前に発見できるかもしれません。

まとめ

Hologramは十分便利なのですが、プラグインで拡張していくことで、さらに便利で使いやすいスタイルガイドを作ることができるのではないでしょうか。