オリジナル ガジェットを作成

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

スタートガイドでは、ガジェットを紹介しています。次のステップでは、独自のガジェットを作成します。このドキュメントでは、その方法について説明します。

基本的な手順

ガジェットを作成してデプロイするための基本的な手順は次のとおりです。

  1. 任意のテキスト エディタを使用してガジェットの仕様を記述し、公開ウェブサーバーでホストします。
  2. ガジェットを実行できるサイトにガジェットを追加します。

ガジェットの構造

ガジェットを編集、公開する方法を理解したら、ガジェットの仕様に高度な機能を組み込む準備が整います。XML ガジェット仕様は、3 つの主要部分で構成されています。

  • コンテンツ セクション。<Content> セクションは、ガジェットの実際の作業が行われる場所です。ここで、ガジェットの種類、プログラミング ロジック、多くの場合にガジェットの外観を決定する HTML 要素を指定します。
  • ユーザー設定。<UserPrefs> セクションでは、ユーザーがガジェットの設定を指定できるようにするコントロールを定義します。たとえば、カスタマイズされた応答メッセージ ガジェットでは、ユーザーが名前を指定するためのテキスト フィールドを提供できます。
  • ガジェットの設定XML ファイルの <ModulePrefs> セクションには、タイトル、著者、推奨サイズなど、ガジェットの特性が指定されています。

注: ガジェット仕様の XML 属性内では、特定の文字を正しく解釈できるように「エスケープ」する(または適切にエンコードする)必要があります。詳細については、特殊文字のエスケープをご覧ください。

ガジェットを作成する場合は、<Content> セクションから始める必要があります。

コンテンツの定義

<Content> セクションは、ガジェットの「頭脳」を表します。<Content> セクションでは、コンテンツの種類を定義し、コンテンツ自体を保持するか、外部コンテンツへのリンクを指定します。<Content> セクションには、ガジェットの属性とユーザー設定を、プログラミングのロジックやフォーマット情報と組み合わせることで、ランニング ガジェットになります。

ガジェットを作成する最も簡単な方法は、HTML(および必要に応じて JavaScript や Flash)を <Content> セクションに配置することです。経験豊富なウェブ デベロッパーは、アクセス制御、リモート ホスティング、代替スクリプト言語の使用、その他のトピックに関するその他のオプションについて、コンテンツ タイプを選択するを読むことができます。こちらはシンプルなサンプル ガジェットです。このガジェットは、新しい HTML ページでフォトアルバムを開くクリック可能な写真を表示します。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
  <Content type="html">
  <![CDATA[
    <div style="text-align:center"><a
      id="Riggs" title="My Photo Album" target="_blank"
      href="http://picasaweb.google.com/doc.examples/ShelfBoy">
<img border="0" alt="Photo" src="http://doc.examples.googlepages.com/Riggsie-OP.jpg"
title="Click Here."></a>
</div> ]]> </Content> </Module>

DOCTYPE の指定

ガジェット仕様に任意の DOCTYPE を含めることができます。DOCTYPE を指定していないガジェットは、デフォルトで後方互換モードで表示されます。

ユーザー設定の定義

一部のガジェットでは、ユーザー固有の情報を提供する手段をユーザーに提供する必要があります。たとえば、ゲーム ガジェットを使用して、ユーザーが希望する難易度のレベルを入力できます。XML ファイルのユーザー設定(<UserPref>)セクションには、ガジェットの実行時にユーザー インターフェース コントロールになるユーザー入力フィールドを記述します。ユーザー設定は永続的に保存されます。

注: userprefs に関連付けられていない、汎用的な永続メカニズムについては、OpenSocial の 永続 API をご覧ください。

たとえば、このガジェットは時間帯に応じて個人の応答メッセージを表示します。ユーザーが次の項目を指定できます。

  • 応答メッセージで使用する名前です。この名前はタイトルバーにも表示されます。
  • 背景色。
  • 写真を表示するかどうか。

ユーザーが [edit] をクリックしてユーザー設定を変更すると、ガジェットは次のように表示されます。

Userprefs コントロール

実行中のガジェットでユーザー インターフェース コントロールになるユーザー設定は、XML 仕様で次のように定義されます。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="250" />
<UserPref name="myname" display_name="Name" required="true" />
<UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
<UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
<UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" > <EnumValue value="Red" /> <EnumValue value="Aqua" /> <EnumValue value="Lime" /> <EnumValue value="Yellow" /> <EnumValue value="Pink" /> <EnumValue value="Orange" /> <EnumValue value="White" /> </UserPref>

次の点に注意してください。

  • ファイルの 3 行目に title="Preferences for __UP_myname__" というテキストが含まれています。ガジェットを実行する場合、ユーザー設定 myname の値は、__UP_myname__ に動的に置き換えられます
  • myname のユーザー設定は「&required」とマークされています。ユーザーがこのフィールドに値を指定せずにガジェットを実行しようとすると、ユーザー設定の編集ボックスは、値が指定されるまで開いたままになります。
  • ユーザー設定 mychoice のデータタイプは bool です。これは、ユーザー インターフェースではチェックボックスとして表示されます。
  • ユーザー設定 mycolorenum データ型です。EnumValues のリストは、ユーザー設定編集ボックスのプルダウン メニューに表示される選択内容を指定します。

ガジェットの一覧は、このガジェットの挨拶を表示する JavaScript を含めてください。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="400"/>
  <UserPref name="myname" display_name="Name" default_value="Rowan"/>
  <UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
  <UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
  <UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
    <EnumValue value="Red" />
     <EnumValue value="Aqua" />
     <EnumValue value="Lime" />
     <EnumValue value="Yellow" />
     <EnumValue value="Pink" />
     <EnumValue value="Orange" />
     <EnumValue value="White" />
   </UserPref>
   <Content type="html"><![CDATA[
   <div id="content_div"></div>
   <script type="text/javascript">
   // Get userprefs
   var prefs = new gadgets.Prefs();

   function displayGreeting () {
     // Get current time
     var today = new Date();
     var time = today.getTime();
     var html = "";

     // Based on the time of day, display an appropriate greeting
     var hour = today.getHours();
     var salutation = "Afternoon";
     if (hour < 12) {
       salutation = "Morning";
     } else if (hour > 17) {
       salutation = "Evening";
     }

     // Set the background color according to the mycolor userpref
     var element = document.getElementById('content_div');
     element.style.height=250;
     // Set the background color according to the mycolor userpref
     element.style.backgroundColor=prefs.getString("mycolor");

     // Display a greeting based on the myname userpref
     html += "<br><FONT SIZE=6>Good " + salutation + ", " +
           prefs.getString("myname") + "!!!<br><br></FONT>";

     // If the "Show Photo?" checkbox is checked, display photo.
     if (prefs.getBool("mychoice") == true) {
       html += '<img src="' + prefs.getString("myphoto") + '">';
     }
     element.innerHTML = html;
   }
   // Pass the userprefs for this module instance to the function
   // (allows users to include multiple module instances on their page)
   gadgets.util.registerOnLoadHandler(displayGreeting);

   </script>
   ]]>
  </Content>
</Module>

すべての <UserPref> 属性の一覧については、リファレンスをご覧ください。

ユーザー設定は、ユーザー設定 JavaScript API を使用して、ガジェットからガジェットからアクセスできます。次に例を示します。

<script type="text/javascript">
  var prefs = new gadgets.Prefs();
  var someStringPref = prefs.getString("StringPrefName");
  var someIntPref = prefs.getInt("IntPrefName");
  var someBoolPref = prefs.getBool("BoolPrefName");
</script>

すべての JavaScript 関数のリストについては、JavaScript リファレンスをご覧ください。

注: 機密性の高いプライベート ユーザーのデータをガジェットのユーザー設定に保存する場合は、ロックされたドメイン機能を使用することをおすすめします。

User Preference 代入変数

<ModulePrefs> または <UserPref> セクションで、__UP_userpref__ という形式の代替変数を使用できます。ここで、userpref は、ユーザー設定の name 属性と一致します。ガジェットが実行されると、対応するユーザー設定の文字列値が、エスケープされていない変数に置き換えられます。たとえば、以下の抜粋では、projects ユーザー設定のために実行時にユーザーが指定する値が、title_url 文字列の __UP_projects__ に置き換えられています。

<Module>
  <ModulePrefs title="Build Monitor"
             title_url="http://www.example.com/build/status.php?__UP_projects__"/>
  <UserPref name="projects" display_name="project(s)"/>
  <Content ... />
</Module>

別の例については、ユーザー設定のサンプルをご覧ください。

ユーザー設定置換変数を使用する場合の一般的なガイドラインを次に示します。

  • <ModulePrefs> title 属性には、__UP_name__ を使用します。これは HTML エスケープです。
  • <ModulePrefs> title_url 属性には __UP_name__ を使用します。これは URL エスケープです。
  • HTML の <Content> セクション内で、__UP_名前__を使用します。 これは HTML エスケープです。
  • <Content> セクションの JavaScript コードで、gadgets.Prefs() 関数を使用します。

ガジェットの設定の定義

XML ファイルの <ModulePrefs> セクションには、タイトル、著者、希望のサイズ設定など、ガジェットの特性を指定します。次に例を示します。

<Module>
<ModulePrefs title="Today's Network Traffic" title_url="http://www/~rowan/gadgets/stats/"
height="200" author="Jane Smith" author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>

ガジェットのユーザーは、これらの属性を変更できません。

<ModulePrefs> 属性の一覧については、リファレンスをご覧ください。

さらに活用する

より複雑なガジェットを作成する準備ができたら、開発の基礎に移動するか、ドキュメントのホームページに戻ってセクションとトピックの概要を確認してください。

トップへ戻る