約一ヶ月前に、フィードの内容を Web ページに表示する feedrenderer.js を公開しました。実はほぼ同時にもうひとつ、 Google Docs のスプレッドシートのデータを表示する「spreadsheetrenderer.js」も作っていたのですが、 DevFest でライトニング・トークやら Chrome OS 本の発売やらがあってほったらかしになっていました。ようやっと落ち着いてきたので、本日はそれを公開します。特徴は以下のとおりです。

• Google Docs のスプレッドシートから、 Google Visualization API を利用した柔軟なデータの読み込みが可能。
• Google Docs 用のデータソース URL を簡単に構築できる。
• 公開スプレッドシートのほか、（ユーザーが Google Docs にログインしていれば）プライベートなスプレッドシートも読み込み可能。
• Closure Library のモジュールとしても、独立したライブラリとしても利用できる。
• HTML のテンプレートを指定するだけで、簡単に表示形式をカスタマイズできる。
• JavaScript により、各フィールドの表示フォーマットや全体の表示をより細かくカスタマイズできる。

実はこのブログのコメント欄は Google Docs で管理しており、 Google Visualization API の検索機能で現在のページに対するコメントだけを抜き出し、表示しています。 Google Docs をデータベースのように使っているわけです。クライアントサイドの JavaScript だけで使えますから、サーバーを立てる必要もなく、もちろん無料です。

spreadsheetrenderer.js を使うと、この便利な Google Visualization API を簡単に活用できます。商用利用も含めて、ご自由にご利用ください。ただし、利用に際して発生した問題に関しては、あくまで自己責任でお願いします。

Google Visualization API とは

Google Visualization API という名前を初めて聞く方もおられるかと思います。これは Google Chart Tools の Interactive charts を実現するために作られた API で、 Google Docs のスプレッドシートのデータを JavaScript で読み込むためのものです。 Query Language と呼ばれる SQL ライクな言語を使うことで、ソートしたり、条件を満たす行だけを読み込んだりできる優れものです。

詳細は以下の記事で解説していますので、ご参照ください。

• Google Spreadsheets を簡易 SQL DB に！「Google Visualization API」
• Google Visualization API 詳細、および Gadgets-in-Docs の作り方
• Google Visuaization API リファレンス

基本的な使い方

それでは、使い方をご紹介します。ライブラリの JavaScript は以下の場所にあるので、ダウンロードして適切な場所に保存してください。

http://webos-goodies.googlecode.com/svn/trunk/prod...

そして、データを表示する Web ページで、以下のようにして Visualization API と spreadsheetrenderer.js を読み込んでおきます。

<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load("visualization", "1");
</script>
<script type="text/javascript" src="spreadsheetrenderer.js"></script>

ここでは以下のシートにある件名と県コードの先頭 5 行を表示してみましょう。

http://spreadsheets.google.com/pub?key=tjGUo14k5R2...

これは以下の HTML で実現できます。

<ul id="result"></ul>

<script type="text/javascript">
var renderer = new SpreadsheetRenderer({
  key: '0Ao0lgngMECUtdGpHVW8xNGs1UjJIWkU3NWg1TXRQWEE',
  template:'<li>%県コード% : %1%</li>' });
renderer.render('select * limit 5', 'result');
</script>

以下、実行結果です。

見ての通り、使い方は先日公開した FeedRenderer クラスとかなり似ています。 SpreadsheetRenderer クラスのコンストラクタに渡している template パラメータが各エントリを HTML に挿入する際のテンプレート文字列になっており、この中の「%〜%」という部分が対応するフィールドに置き換えられます。

実際のリクエストは render メソッドによって行われ、第 1 引数の問い合わせの結果を第 2 引数で指定した要素にテンプレートに沿った形で挿入します。問い合わせの指定に使う Query Language については、前述の過去記事などを参照してください。

テンプレートのプレースホルダである「%〜%」は、各フィールドのカラム名（シートの最も上の行の文字列）、もしくは 0 から始まるカラム番号で指定してください。上の例でも、左のカラムは「県コード」というカラム名で、右のカラムは「1」という番号で指定しています。

コンストラクタの引数詳細

SpreadsheetRenderer コンストラクタの引数には、以下のメンバを持つオブジェクトを指定します。

これらのうち、 gid, sheet, headers は Visualization API のデータソースの指定パラメータそのものですので、詳細はこちらのページをご覧下さい。また、 key には Google Docs でのスプレッドシート編集ページの URL に含まれている「key=」パラメータと同じものを指定してください。

このようにオブジェクトで指定する方法のほかに、データソース URL を直接指定することもできます。その場合、 template や formatter は第 2 引数に指定してください。

new SpreadsheetRenderer(
  'http://spreadsheets.google.com/tq?key=0Ao0lgngMECUtdGpHVW8xNGs1UjJIWkU3NWg1TXRQWEE&gid=0&pub=1',
  { template:'<li>%県コード% : %1%</li>' });

データソース URL は、スプレッドシートになんでも良いのでガジェットを追加して（「挿入」メニューで追加できます）、その右上の▼メニューにある「クエリのデータ ソース URL を取得する...」で表示できます。

カスタマイズ

表示するデータの見た目などは、コンストラクタや render メソッドに渡す引数によって柔軟にカスタマイズできます。以下、可能なカスタマイズをご紹介します。

各フィールドの出力フォーマットの変換

テンプレート文字列内のプレースホルダを各フィールドの値で置き換える際、デフォルトでは単純に HTML エスケープをかけたものを使います。この動作を変更したいときは、必要なフィールドごとの変換関数を格納したオブジェクトを用意し、それを setFormatter メソッド（もしくはコンストラクタの formatter パラメータ）に渡してください。

以下は県コードを 2 桁で表示します。

<ul id="result"></ul>

<script type="text/javascript">
  var template = '<li>%県コード% : %1%</li>';
  var formatter = {
    '県コード': function(value, rawValue) {
      value = '' + value;
      while(value.length < 2) value = '0' + value;
      return value;
    }
  };
  var renderer = new SpreadsheetRenderer({ key: '0Ao0lgngMECUtdGpHVW8xNGs1UjJIWkU3NWg1TXRQWEE' });
  renderer.setTemplate(template);
  renderer.setFormatter(formatter);
  /* 上の3行は以下と等価
  var renderer = new SpreadsheetRenderer({
    key: '0Ao0lgngMECUtdGpHVW8xNGs1UjJIWkU3NWg1TXRQWEE',
    template: template, formatter: formatter }); */
  renderer.render('select * limit 5', 'result');
</script>

実行例

変換関数は 3 つの引数をとり、変換結果（テンプレートのプレースホルダを置換する文字列）を返す関数です。

format_func(value, rawValue, values)

value

文字列形式のフィールドの値です。 DataTable クラスの getFormattedValue メソッドで取得したものです。

rawValue

DataTable クラスの getValue メソッドで取得した値です。

values

現在処理中の行の各フィールドについて [value, rawValue] の配列を格納したオブジェクトです。これを使って他のフィールドの値を参照した条件分岐（特定の県コードの行の色を変更するなど）が可能です。

最終出力のカスタマイズ

フィールドごとのカスタマイズのほか、最終的に HTML をドキュメントに挿入する部分の処理も差し替え可能です。これにより、フィードのソートや行ごとに異なったスタイルを設定するなどの処理が可能です。

最終出力のカスタマイズは、 render メソッドの第 2 引数に文字列の代わりに関数を指定することで行います。以下は背景色を交互に変更する例です。

<div id="result"></div>

<script type="text/javascript">
  function output(html, table) {
    for(var i = 0 ; i < html.length ; ++i) {
      html[i] = html[i].replace('<c>', (i & 1) ? '#cef' : '#efc');
    }
    document.getElementById('result').innerHTML = html.join('');
  }
  var renderer = new SpreadsheetRenderer({
    key: '0Ao0lgngMECUtdGpHVW8xNGs1UjJIWkU3NWg1TXRQWEE',
    template:'<div style="background-color:<c>">%県コード% : %1%</div>' });
  renderer.render('select * limit 5', output);
</script>

実行例

出力関数は 2 つの引数をとる関数です。戻り値は無視されますので、関数内でドキュメントへの HTML の挿入まで行う必要があります。

output_func(html, table);

html

各エントリごとの HTML への変換結果（formatter_func の返り値）の配列です。これを加工することで表示のカスタマイズが可能です。

table

シートの内容を保持する DataTable クラスのオブジェクトです。

Closure Library での利用

SpreadsheetRenderer クラスは Closure Library で構築されており、同様に Closure Library を利用したプロジェクトではモジュールとして組み込むことが可能です。 Closure Library については、 こちらの記事をご参照ください。

以下にソースがありますので、これをアプリケーションの中に組み込んでください。

http://webos-goodies.googlecode.com/svn/trunk/cms/...

これで、 wg.SpreadsheetRenderer のクラス名で前述の機能が利用できます。ただし、 Closure Compiler による最適化に対応するため、コンストラクタや render メソッドに渡すオプションのオブジェクトのキーは、必ずダブルクォーテーションもしくはシングルクォーテーションで囲ってください。

new wg.SpreadsheetRenderer({ 'key': '〜', 'template': '<div>%title%</div' });
/* これではダメ
new wg.SpreadsheetRenderer({ key: '〜', template: '<div>%title%</div' }); */

formatter のフィールド名なども同様です。忘れやすいのでご注意ください。

IE で table タグにレンダリングする際の注意

ここまでの例では結果をリストに表示していますが、表形式のデータなんだから、テーブルで表示したいですよね。しかし、残念ながら IE では、以下のコードは正しく動きません。

<table><tbody id="table"></tbody></table>

<script type="text/javascript">
  var renderer = new SpreadsheetRenderer({
    key: '0Ao0lgngMECUtdGpHVW8xNGs1UjJIWkU3NWg1TXRQWEE',
    template:'<tr><td>%県コード%</td><td>%1%</td></tr>' });
  renderer.render('select * limit 5', 'table');
</script>

これは IE のバグ仕様で、テーブル系の要素には innerHTML が正しく動かないのです。したがって、テーブルを表示するには render メソッドの第 2 引数に関数を渡して、そこでテーブルごとレンダリングしなければなりません。

<div id="table"></div>

<script type="text/javascript">
  function output(html, table) {
    document.getElementById('table').innerHTML =
      '<table><tbody>' + html.join('') + '</tbody></table>';
  }
  var renderer = new SpreadsheetRenderer({
    key: '0Ao0lgngMECUtdGpHVW8xNGs1UjJIWkU3NWg1TXRQWEE',
    template:'<tr><td>%県コード%</td><td>%1%</td></tr>' });
  renderer.render('select * limit 5', output);
</script>

実行例

IE9 では直っててほしいなぁ・・・ (; ;

以上、本日は Web ページ中に簡単に Google Spreadsheets のデータを表示できる JavaScript ライブラリ「spreadsheetrenderer.js」をご紹介しました。 Google Spreadsheets は多彩な計算式が使えたり、外部のデータをインポートできたりと、なにげにいろいろな機能があります。このライブラリともども、ぜひご活用ください！