opensocial-jquery 0.3.0 Preference と Window の強化と見直しをしました。

おはようございます。なかじまんです。opensocial-jquery 0.3.0 を公開しました。

Preference と Window の強化と見直しをしました。

Preference

次のとおり、ユーザ設定を保存できるようにしました。feature/setprefs を必要とします。

$.pref('foo', 'foo1');
$.pref('bar', 123);
$.pref('buz', false);

次のとおり、キーと値の組を指定できます。直感的でいいでしょ?

$.pref({
foo: 'foo1',
bar: 123,
buz: false
});

次のとおり、値として配列も保存できます。直感的でいいでしょ? gadgets.Prefs.setArray を代替するものです。なぜか gadgets.Prefs.setArray は、ユーザ設定を永続化しません。バグでしょうかね。$.pref は、配列であっても永続化するようにしてあります。

$.pref('foo', ['foo1', 123, false]);

そして、次のとおり、配列として値を取得できます。

var foo = $.prefArray('foo');
console.log(foo); // => ['foo1', '123', 'false']

次のとおり、ユーザ設定を取得するとき、HTML エスケープしないように振る舞いを変更しました。$.prefArray も同様です。gadgets.Prefs.getString と getArray は HTML エスケープしていて使い勝手が悪かったのです。

$.pref('foo', '<b>foo</b>');
var foo = $.pref('foo');
console.log(foo); // => '<b>foo</b>'

次のとおり、URL パラメータも取得できるようにしました。ユーザ設定と URL パラメータを区別する線引きが難しい... つまり、URL パラメータは、ユーザ設定の一環としてみなしてもよいと整理し、よい意味で妥協しています。このほうが覚えやすいでしょ?

var lang = $.pref('lang'); // 言語
var country = $.pref('country'); // 地域
var moduleId = $.pref('mid'); // モジュールID
var lang = $.pref('up_lang');

URL パラメータとユーザ設定のキーが同名のときは、URL パラメータを優先します。同名にならないような命名を推奨しますが、どうしても区別したいときは、ユーザ設定のキーの先頭に "up_" を付与してください。

Window

次のとおり、ガジェットの横幅を取得できます。iframe@width に相当します。直感的でいいでしょ?

var width = $(window).width();
console.log(width); // => 257

次のとおり、ガジェットの縦幅を取得できます。iframe@height に相当します。直感的でいいでしょ?

var height = $(window).height();
console.log(height); // => 200

$(window).width と height は、gadgets.window.getViewportDimensions を代替するものです。

次のとおり、ガジェットの高さを変更できます。$(window).height(height) は、gadgets.window.adjustHeight(opt_height) を代替するものです。直感的でいいでしょ?

$(window).height(400);
// $(window).adjustHeight(400); と同じ

次のとおり、ガジェットのタイトルを設定するとき、その中で HTML エスケープするように振る舞いを変更しました。つまり、HTML エスケープする前のタイトルを指定できるようにしました。

$(window).title('<b>foo</b>');
// gadgets.window.adjustHeight('&lt;b&gt;foo&lt;/b&gt;'); と同じ

opensocial-jquery 0.3.0 では、jQuery.container プロパティと CSS container selector という新しい考え方を導入しました。これは、別途エントリを投稿して説明します。