Google Gadgets API 入門 (4)

2007-01-08 Google Gadgets API 入門 (4)

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

前回は Google Gadgets API が提供する JavaScript ライブラリのうち、ユーザ・プリファレンスに関するものを紹介しました。今回は、同じく JavaScript ライブラリに含まれる汎用関数について解説します。今回紹介する関数は Core JavaScript ライブラリに含まれるもので、特別な指定をすることなく使用することができます。

外部コンテンツの取得

Core JavaScript ライブラリには、外部コンテンツ（指定された URL のコンテンツ）を取得するための関数が提供されています。この機能によって、あるサイトのフィード（RSS や Atom）を取得したり、検索エンジンからの検索結果を取得することができます。以下に外部コンテンツを取得するための関数を示します：

_IG_FetchContent(url, func)	url に指定されたコンテンツをテキスト・データとして取得します。コンテンツの取得は非同期で行われ、完了した時点で func に指定した関数が呼び出されます。
_IG_FetchXmlContent(url, func)	url に指定された XML コンテンツを DOM-Tree として取得します。コンテンツの取得は非同期で行われ、完了した時点で func に指定された関数が呼び出されます。
_IG_FetchFeedAsJSON(url, func, num_entries, get_summaries)	url に指定されたフィード（RSS または Atom）を JSON オブジェクトとして取得します。フィードの取得は非同期で実行され、完了した時点で func に指定された関数が呼び出されます。num_entries と get_summaries は省略可能なパラメータです。num_entries には取得するフィードのエントリ数を指定します。1 ～ 9 までの値が有効であり、省略時は 3 となります。get_summaries が true の場合は、エントリのサマリーも取得します（省略時は false）。

これらの関数は全て非同期で実行され、コンテンツの取得が完了した時点で（指定しておいた）コールバック関数が呼び出される仕組みになっています。

コールバック関数

コールバック関数の形式の基本は以下の通りです：

function on_fetched(response)
{
    if(response == null) { return }
    ...
}

コールバック関数の引数である response のデータ型は、使用した _IG_Fetch*** 関数によって異なります。_IG_FetchContent() の場合は文字列、_IG_FetchXmlContent() の場合は DOM-Tree、_IG_FetchFeedAsJSON() の場合は JSON オブジェクトになります。

コールバック関数の中で response が null の場合に return していますが、これは Google Gadgets API のドキュメントに書かれているサンプルに倣ったためです。しかし、どういう場合に null となるのかという記述はドキュメントから見つけることができませんでした。

_IG_FetchXmlContent 関数についての注釈

Google Page Creator のスペースに置いた XML ファイルを _IG_FetchXmlContent() で取得した場合に、コールバック関数の引数が DOM-Tree ではなく単純な文字列型になってしまいました。他のサーバに置いた同じファイルを取得すると、DOM-Tree として取得できました。サーバによって違いがあるようです。

Google Gadgets API のドキュメントにあるサンプル・コードでは、コールバック関数を以下のように実装しています：

function on_fetched(response)
{
    if(response == null || typeof(response) != "object" || response.firstChild == null)
    {
        _gel("content_div").innerHTML = "<i>Invalid data.</i>"
        return
    }
    ...
}

このことから、「_IG_FetchXmlContent() 関数を使っても必ずしもコンテンツを DOM-Tree として取得できるとは限らない」ということなのかもしれません。もし取得したコンテンツが DOM-Tree ではなく文字列型として渡されてしまった場合は、上記コードのようにエラーとして処理するか、「 d:id:benikujyaku:20070103 ajaxslt で文字列から DOM-Tree に変換する」で紹介した方法などで DOM-Tree に変換します。

コールバック関数への追加パラメータ

コールバック関数のパラメータに渡されるのは、基本的には取得されたコンテンツだけですが、それ以外に追加のパラメータを渡す方法も提供されています。以下に例を示します：

function on_fetched(response, additional_param)
{
    if(response == null) { return }
    ...
}

_IG_FetchContent("http://example.com/hoge.txt", _IG_Callback(on_fetched, 100))

コールバック関数の第一引数は response とし、追加のパラメータは第二引数以降とします。また、_IG_Fetch*** 関数に渡すコールバック関数は _IG_Callback() によってラップします。_IG_Callback() の第一引数にコールバック関数を指定し、第二引数以降に追加で渡すパラメータを指定します。

その他の関数

Core JavaScript ライブラリには、他にも以下の関数が含まれています：

_IG_RegisterOnloadHandler(func)	Gadget が読み込まれたときに呼び出されるイベント・ハンドラを登録します。func に登録するイベント・ハンドラを指定します。func は引数を取らない関数です。注意として、iframe 化される Gadget（"html" タイプの Gadget）の場合は、document.body.onload に関数を代入することでイベント・ハンドラの設定を行います。
_gel(id)	JavaScript の document.getElementById() のラッパー関数です。
_esc(str)	JavaScript の escape() と encodeURIComponent() のラッパー関数です。
_unesc(str)	JavaScript の unescape() と decodeURIComponent() のラッパー関数です。
_trim(str)	str の先頭と末尾のホワイトスペースを削除します。
_gelstn(tagname)	JavaScript の document.getElementsByTagName() のラッパー関数です。
_uc(str)	str の uppercase バージョンを返します。
_min(val1, val2)	val1 と val2 の小さい方（等しい場合は val2）を返します。
_max(val1, val2)	val1 と val2 の大きい方（等しい場合は val2）を返します。
_hesc(str)	HTML 文字列である str から '<'、'>'、'&'、'''、'"' をエスケープした値を返します。
_args()	URL パラメータを連想配列として返します。例えば、URL パラメータが "&foo=bar&up_cats=meow" の場合は {"foo":"bar", "up_cats":"meow"} が返されます。

_gel() などのラッパー関数を利用すると、ソースコードを簡素に記述することができます。また、知っていることで他の人の書いた Gadget のソースコードを読むときの助けにもなります。

次回予告

次回は Feature-specific JavaScript ライブラリと呼ばれる、特定の機能に特化した JavaScript ライブラリの解説に入ります。

紅孔雀