JS stanza wrapper

=== JavaScript 版の TogoStanza を Ruby 版でラッピングする TogoStanza ===

JavaScript 版の TogoStanza はブラウザの [http://webcomponents.org/ Web Components] 対応状況により、
現状では埋め込み先で表示が崩れたりすることがあるため、アドホックなワークアラウンドとして
Ruby 版でラッピングして IFRAME で埋め込むこともできるようにする TogoStanza を作成した。

作成した Ruby 版の JS stanza wrapper スタンザは下記の開発環境にデプロイされている。

* http://dev.togostanza.org/stanza

参考：Ruby版とJavaScript版について

* http://togostanza.org/documents/development.html
* [[BH14.14/TogoStanza]]
* [[SPARQLthon/togostanza js]]

== JS stanza wrapper の使い方 ==

Ruby 版でラッピングしたい開発した JS 版のスタンザを ts build で Web Components 化し、HTTP(S) でアクセスできるサーバに配置する。
ここでは togostanza.org にデプロイした下記の JS 版スタンザを例として利用する（このデプロイ先では CORS 対策をしておく必要がある）。

* http://togostanza.org/dist/stanza/

これを JS stanza wrapper スタンザのヘルプページ

* http://dev.togostanza.org/stanza/js_stanza_wrapper/help

にあるように、

<pre>
<div data-stanza="http://dev.togostanza.org/stanza/js_stanza_wrapper" data-stanza-server="JS版スタンザのURL" data-stanza-name="スタンザ名" data-stanza-options="パラメータ名1=値1 パラメータ名2=値2"></div>
</pre>

という形で

* data-stanza に Ruby 版 JS stanza wrapper スタンザの URL を
* data-stanza-server に JS 版のスタンザがデプロイしてある URL を
* data-stanza-name にデプロイ先の JS 版スタンザ名を
* data-stanza-options にスペース区切りで JS 版スタンザに渡す「パラメータ名=値」のリストを

それぞれ指定することにより JS 版のスタンザを Ruby 版 (IFRAME 版) として埋め込むことができる。

=== 例 ===

JS 版の Protein 3D structure スタンザ

* http://togostanza.org/dist/stanza/protein_structure/help.html

を Ruby 版として埋め込むには、

<pre>
<div data-stanza="http://dev.togostanza.org/stanza/js_stanza_wrapper" data-stanza-server="http://togostanza.org/dist/stanza" data-stanza-name="protein_structure" data-stanza-options="up_id=P00533 start_pos=58 end_pos=250"></div>
</pre>

または

<pre>
<iframe src="http://dev.togostanza.org/stanza/js_stanza_wrapper?server=http%3A%2F%2Ftogostanza.org%2Fdist%2Fstanza&name=protein_structure&options=up_id=P00533+start_pos=58+end_pos=250"></iframe>
</pre>

のようにすることで IFRAME にできる。

ブラウザで確認するには

http://dev.togostanza.org/stanza/js_stanza_wrapper?server=http://togostanza.org/dist/stanza&name=protein_structure&options=up_id=P00533+start_pos=58+end_pos=250

のようにオプションを指定するだけで OK。

== JS stanza wrapper の仕組み ==

もともと Ruby 版のスタンザは、

<pre>
<head>
<link href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.2.2/css/bootstrap.min.css" rel="stylesheet">
<link href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.js"></script>

<link href="http://togostanza.org/stanza/assets/stanza.css" rel="stylesheet">
<script src="http://togostanza.org/stanza/assets/stanza.js"></script>
</head>

<body>
<div data-stanza="スタンザのURL" data-stanza-パラメータ名1="値1" data-stanza-パラメータ名2="値2" ... ></div>
</body>
</pre>

のように書いておくと /stanza/assets/stanza.js が該当する div を

<pre>
<iframe src="スタンザのURL?パラメータ名1=値1&パラメータ名2=値2"></iframe>
</pre>

に展開することでスタンザが IFRAME として埋め込まれるようになっている。

JS stanza wrapper では data-stanza-server, -name, -options の3つのパラメータを受け取り、そのまま JS 版を呼び出すように stanza.rb に渡す。

<pre>
class JsStanzaWrapperStanza < TogoStanza::Stanza::Base
  property :params do |server, name, options|
    { "server" => server, "name" => name, "options" => options }
  end
end
</pre>

これを template.hbs で

<pre>
  <head>
    <title>JS stanza wrapper</title>
    <script src="assets/js_stanza_wrapper/webcomponentsjs/webcomponents.min.js"></script> <!-- ts build の生成物よりコピー -->
    <link rel="stylesheet" href="assets/js_stanza_wrapper/css/ts.css"> <!-- ts build の生成物よりコピー -->
    <link rel="import" href="{{params.server}}/{{params.name}}/"> <!-- JS 版スタンザの URL -->
  </head>

  <body>
    <togostanza-{{params.name}} {{params.options}}></togostanza-{{params.name}}>
  </body>
</pre>

のように HTML にレンダリングすることで、JS 版スタンザを Web Components として IFRAME の内部に埋め込んでいるだけ。

* https://github.com/togostanza/togostanza/tree/master/js_stanza_wrapper_stanza

== Ruby 版 TogoStanza 開発の現状と注意点 ==

Ruby 版 TogoStanza 開発では、依存している RDF ライブラリが最近は Ruby 2.2 以上を要求するようになっているので、
まず安定版 2.3 系列の Ruby 2.3.1 以降をインストールする。

* https://www.ruby-lang.org/ja/

次に、まだインストールしていない場合は togostanza の gem をインストールする。

<pre>
sudo gem install togostanza
</pre>

GitHub から最新版の TogoStanza レポジトリを（あとでプルリクするのに必要ならフォークしてから）取得する。

<pre>
git clone git@github.com:togostanza/togostanza.git
</pre>

レポジトリ内にブランチを作成して bundle install を行い依存ライブラリをインストールする。
ブランチ名はこれから作成するスタンザ名などを指定しておくと分かりやすい。

<pre>
git branch add_js_stanza_wrapper_stanza
git checkout add_js_stanza_wrapper_stanza
cd togostanza
bundle install
sudo gem install nokogiri
bundle install
rm Gemfile.lock
bundle install
</pre>

ちなみに bundle install で nokogiri がエラーになることが多いようだが、
手動で gem install nokogiri したり Gemfile を調整したりして完了させた。

つぎに togostanza コマンドで新しいスタンザを作成する。

<pre>
togostanza stanza new js_stanza_wrapper
cd js_stanza_wrapper_stanza/
</pre>

スタンザの目的に応じて、

* stanza.rb
* template.hbs

と、必要なら

* sparql/*.rq
* assets/スタンザ名/*

などを開発する。

さらに、スタンザの説明やヘルプページで使われるテスト用のパラメータなど、スタンザのメタデータを

* metadata.json

に記載する。この値が自動的に

* スタンザ名.gemspec

ファイルに取り込まれるようになっているが、自動生成される gemspec ファイルにバグがあり、

<pre>
-  spec.authors       = Array(metadata["stanza:author"])
-  spec.email         = Array(metadata["stanza:address"])
-  spec.summary       = metadata["stanza:label"]
-  spec.description   = metadata["stanza:definition"]
+  spec.authors       = Array(metadata["author"])
+  spec.email         = Array(metadata["address"])
+  spec.summary       = metadata["label"]
+  spec.description   = metadata["definition"]
   spec.homepage      = ''
-  spec.license       = metadata["stanza:license"]
+  spec.licenses      = Array(metadata["license"])
</pre>

のような書き換えが必要（スミマセン…）。

出来上がったら rackup.ru のある togostanza 直下のディレクトリに戻り、ローカル環境で動くかどうか動作確認する。

<pre>
bundle exec rackup
</pre>

* スタンザ一覧に含まれているか確認 http://localhost:9292/stanza
* 追加したスタンザの動作確認 http://localhost:9292/stanza/スタンザ名/help

開発が完了したらコミットし、GitHub にプッシュする

<pre>
git add Gemfile Gemfile.lock  js_stanza_wrapper_stanza
git commit
git push origin add_js_stanza_wrapper_stanza
</pre>

GitHub のウェブを開いてプルリクを作成、マージする。

* https://github.com/togostanza/togostanza --> create pull request
* https://github.com/togostanza/togostanza/pull/61 --> merge

これを togostanza.org にデプロイするにはもう一手間かかるがここでは省略。