Google Gadgets API 入門 (6)

2007-01-10 Google Gadgets API 入門 (6)

■[Google Gadgets] Google Gadgets API 入門 (6)

今回は Feature-specific ライブラリの一つである tabs ライブラリについて解説します。

tabs ライブラリとは

tabs ライブラリとは、Gadget にタブ機能を持たせるための Feature-specific ライブラリです。タブ機能を利用することで、Gadget に与えられた小さな領域において複数の情報を効率的に分類表示することが可能となります。

tabs ライブラリの使用

tabs ライブラリを使用するには、Gadget-Spec の <ModulePrefs> の内側に「<Require feature="tabs" />」を追加する必要があります。また、タブに対するデフォルトのスタイルシートを適用するために、http: //www.google.com/ig/tablib.css のインポートも行います。以下に Gadget-Spec の記述例を示します：

<Module>
  <ModulePrefs ...>
    <Require feature="tabs" />
  </ModulePrefs>
  ...
  <Content ...>
  <![CDATA[
  <style type="text/css">
  @import url(http://www.google.com/ig/tablib.css);
  </style>
  ...
  ]]>
  </Content>
</Module>

タブ機能を利用するには、最初に tabs オブジェクトをインスタンス化します：

var tabs = new _IG_Tabs(__MODULE_ID__)

タブの作成などの操作は、作成した tabs オブジェクトを通して行います。

以下に tabs オブジェクトのコンストラクタと、tabs オブジェクトを通して利用可能な関数の一覧を示します：

_IG_Tabs(module_id, opt_selected_tab)	tabs オブジェクトのコンストラクタです。module_id には __MODULE_ID__ を指定します。opt_selected_tab は任意のパラメータであり、初期状態で選択されるタブの名前を指定します（省略時はインデックスが 0 のタブが選択されます）。
addTab(tabName, opt_domId, opt_callback)	tabs オブジェクトにタブを追加します。tabName には作成するタブの名前を指定します。opt_domId と opt_callback は共に省略可能なパラメータです。opt_domId にはタブのコンテンツを保持するの DOM ID を指定します。opt_domId が省略、または存在しない DOM ID が指定された場合は、新しいが作成されます。opt_callback にはタブが選択されたときに呼び出されるコールバック関数を指定します。コールバック関数の引数にはタブの DOM ID が渡されます。関数は戻り値として、作成されたタブに関連付けられたの DOM ID を返します。
addDynamicTab(tabName, callback)	動的に生成されるコンテンツを含むタブを tabs オブジェクトに追加します。tabName には作成するタブの名前、callback にはコンテンツを生成するコールバック関数を指定します。コールバック関数はタブが選択されるたびに毎回呼び出されます。コールバック関数の引数にはタブの DOM ID が渡されます。関数は戻り値として、作成されたタブに関連付けられたの DOM ID を返します。
setSelectedTab(tabIndex)	tabIndex で指定されたインデックスのタブを選択します。タブのコールバック関数が存在すれば、それが呼び出されます（タブが既に選択されている場合はコールバック関数は呼び出されません）。タブのインデックスは 0 から開始します（最も左側に位置するタブのインデックスが 0 です）。
moveTab(tabIndex1, tabIndex2)	tabIndex1 と tabIndex2 で指定されるインデックスのタブの位置を交換します。選択されているタブは変更されず、コールバック関数も呼び出されません。
numTabs	tabs オブジェクトに追加されているタブの数を表すプロパティです。
currentTab	現在選択されているタブのインデックスを表すプロパティです。

注意として、numTabs と currentTab は関数ではなくプロパティとなっています（現時点の Google Gadgets API のドキュメントでは関数となっているので注意）。また、タブを削除する機能はありません。

tabs ライブラリの使用例は、以下に紹介するサンプル Gadget を参照してください。

サンプル Gadget

この Gadget は tabs ライブラリの機能を実際に確かめるために作成したものです。以下の機能を持っています：

[New Tab] ボタンを押すと、その左にあるテキスト・ボックスで指定された名前のタブを作成します。
[Num of Tabs] ボタンを押すと、その左にあるテキスト・ボックスにタブの数を表示します。
[Change Tab] ボタンを押すと、その左にあるテキスト・ボックスで指定されたインデックスのタブを選択します。

この Gadget の Gadget-Spec は次のようになっています：

<?xml version="1.0" encoding="UTF-8" ?>

<Module>
  <ModulePrefs title="Hello, tabs library">
    <Require feature="tabs" />
  </ModulePrefs>
  <Content type="html">
  <![CDATA[

<!-- tabs ライブラリのためのスタイルシートをインポート -->
<style type="text/css">
@import url(http://www.google.com/ig/tablib.css);
</style>

<!-- Manager タブのコンテンツ -->
<div id="manager_id">
  <form id="myform">
    <div>
      <input type="text" name="tab_name" value="tab_name" />
      <input type="button" value="New Tab" onclick="create_new_tab()" />
    </div>
    <div>
      <input type="text" name="num_of_tabs" />
      <input type="button" value="Num of Tabs" onclick="count_tabs()" />
    </div>
    <div>
      <input type="text" name="tab_index" value="1" />
      <input type="button" value="Change Tab" onclick="select_tab()" />
    </div>
  </form>
</div>

<script language="JavaScript">

// Manager タブを作成
var tabs = new _IG_Tabs(__MODULE_ID__)
tabs.addTab("Manager", "manager_id")

// 新しくタブを作成する
function create_new_tab()
{
    var tab_name = _gel("myform").tab_name.value
    var tab      = tabs.addTab(tab_name)
    _gel(tab).innerHTML = tab_name
}

// タブの数をカウントする
function count_tabs()
{
    _gel("myform").num_of_tabs.value = tabs.numTabs
}

// 指定インデックスのタブを選択する
function select_tab()
{
    var tab_index = _gel("myform").tab_index.value
    tabs.setSelectedTab(tab_index)
}
</script>

  ]]>
  </Content>
</Module>

ポイントは以下の通りです：

Manager タブのコンテンツを静的に用意している（の部分）。タブのコンテンツは create_new_tab() 関数で行っているように、動的に設定することもできますが、Manager タブのように事前にコンテンツが確定している場合は静的な HTML として用意しておくほうが楽です。
フォーム要素の値へのアクセスに _gel() 関数を使用している（document.myform.tab_name.value などとはせずに）。以下の「フォーム要素の値にアクセスするときの注意」を参照してください。

フォーム要素の値にアクセスするときの注意

フォーム要素の値にアクセスするときは、document.myform.tab_name.value ではなく _gel("myform").tab_name.value のようにします。これは、ユーザがタブを切り替えたときに、DOM-Tree としての構成が変化してしまうからです。document.myform.tab_name.value のようにフォーム要素の値にアクセスしていると、タブが一度でも切り替えられた後では、その方法でアクセスできなくなってしまうためです。

その問題を回避するためには、フォームに ID を振っておき、_gel() 関数（document.getElementById() のラッパー関数）によって、DOM ID から対象のフォームにアクセスします。

タブのコンテンツを動的に作成する

このサンプルには含まれていないので、ここで addDynamicTab() 関数の使用例を示します。まず、以下のようにタブを作成します：

tabs.addDynamicTab("tab_name", on_tab_selected)

コールバック関数には選択されたタブの DOM ID が渡されるので、以下のようにタブのコンテンツを設定します：

function on_tab_selected(tab_id)
{
    // 実際には Math.random() ではなく独自のコンテンツを設定する
    _gel(tab_id).innerHTML = Math.random()
}

スタイルシートのカスタマイズ

デフォルトで提供されれいるスタイルシート（http://www.google.com/ig/tablib.css）のクラスをオーバーライドすることで、表示されるタブの外観を変更することができます（"html-inline" タイプの Gadget でスタイルシートをカスタマイズすると表示が乱れてしまうため、）。以下に標準のスタイルシートで定義されているクラスを示します：

.tablib_table__MODULE_ID__	タブが含まれるテーブルを表すクラスです。
.tablib_selected__MODULE_ID__	選択状態のタブを表すクラスです。
.tablib_unselected__MODULE_ID__	非選択状態のタブを表すクラスです。
.tablib_spacerTab__MODULE_ID__	タブとタブの間の領域を表すクラスです。
.tablib_emptyTab__MODULE_ID__	最初のタブの左側、および最後のタブの右側の領域を表すクラスです。

以下の画像の赤い部分が .tablib_spacerTab__MODULE_ID__ に対応し、黄色い部分が .tablib_emptyTab__MODULE_ID__ に対応します：

この Gadget のスタイルシートの設定部分は以下のようになっています：

<style type="text/css">
@import url(http://www.google.com/ig/tablib.css);
.tablib_spacerTab__MODULE_ID__ { background-color: yellow; }
.tablib_emptyTab__MODULE_ID__ { background-color: red; }
</style>

"html-inline" タイプの Gadget ではカスタマイズを行わない

"html-inline" タイプの Gadget ではスタイルシートのカスタマイズは行わないべきです。"html-inline" タイプの Gadget は親ページの一部として描画されるため、スタイルシートを変更すると、同じページに存在するタブ機能を利用する他の Gadget の外観も一緒に変更されてしまいます。

次回予告

次回はまだ決めていませんが、Feature-specific ライブラリのうち残るは drag ライブラリと MiniMessage ライブラリなので、このうちのどちらかを取り上げたいと思います。

紅孔雀