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

スタート ガイドでは、ガジェットの概要について説明しました。次は、オリジナルのガジェットを作成するステップです。このドキュメントでは、以下について説明します。

目次

  1. 基本的な手順
  2. ガジェットの構造
    1. コンテンツの定義
    2. ユーザー設定の定義
    3. ガジェット設定の定義
  3. 注: ガジェットは必ず公開されます
  4. さらに詳しく

基本的な手順

次に、ガジェットを作成して展開する手順を示します。

  1. テキスト エディタでガジェットの仕様を記述し、公開ウェブ サーバーでホストします。
  2. ガジェットをコンテナ (iGoogle、Orkut など) に追加します。「コンテナ」とは、ガジェットを実行できるアプリケーションやサイトです。

ガジェットの構造

ガジェットを編集して公開する手順を理解できたら、今度はガジェットの仕様により高度な機能を追加してみましょう。XML ガジェット仕様は、以下の 3 つの部分から構成されます。

  • コンテンツ セクション。<Content> セクションは、ガジェットの実際の動作を指定する場所です。ガジェットのタイプ、プログラミング ロジック、ガジェットの外観を決める HTML 要素などを指定します。
  • ユーザー設定。<UserPrefs> セクションでは、ユーザーがガジェットの設定を指定できるようにするためのコントロールを定義します。たとえば、挨拶を表示するガジェットであれば、ユーザーが名前を入力するテキスト フィールドが必要になるでしょう。
  • ガジェット設定。XML ファイルの <ModulePrefs> セクションで、タイトル、作成者、最適に表示されるサイズなどのガジェットの特性を指定します。

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

ガジェットの記述は <Content> セクションから始めます。

コンテンツの定義

<Content> セクションはガジェットの頭脳部分です。この <Content> セクションで、コンテンツのタイプを定義し、コンテンツ自体を保持するか、外部のコンテンツにリンクするかを指定します。<Content> セクションで、ガジェットの属性やユーザー設定に、プログラミング ロジックやフォーマット情報を組み合わせることで、実行可能なガジェットを構築します。

ガジェットの作成方法として最も簡単なのは、<Content> セクションに HTML (必要に応じて JavaScript や Flash) を配置する方法です。経験豊富なウェブ デベロッパーであれば、コンテンツ タイプの選択を参考にして、アクセス制御、リモート ホスティング、他のスクリプト言語の使用などに関連するオプションを指定できます。次に、単純なサンプル ガジェットを示します。このガジェットでは、表示されている写真をクリックすると、新しい 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>

ユーザー設定の定義

ガジェットによっては、ユーザーが独自の情報を指定できる方法を提供する必要があります。たとえば、ゲーム ガジェットであれば、ユーザーが難易度を指定できた方が良いかもしれません。XML ファイルのユーザー設定 (<UserPref>) セクションで、ガジェットの実行時にユーザー インターフェース コントロールになる、ユーザーによる入力フィールドを指定します。ユーザー設定は永続的に保持されます。

たとえば、次に示すガジェットは、時間帯に応じて適切な挨拶を表示します。このガジェットでは、ユーザーが以下の項目を設定できます。

  • 挨拶に使用する名前。この名前はタイトル バーにも表示されます。
  • 背景色。
  • 写真を表示するかどうか。

ユーザーがユーザー設定を変更するため [edit] をクリックすると、次のような状態のガジェットが表示されます。

ユーザー設定コントロール

実行中のガジェットにユーザー インターフェース コントロールとして表示されるユーザー設定は、次に示すように 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 です。ユーザー インターフェースにはチェックボックスとして表示されます。
  • ユーザー設定 mycolor のデータ型は enum です。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 リファレンスをご覧ください。

ユーザー設定代入変数

<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 エスケープされます。
  • <Content> セクション内の HTML では、__UP_name__.を使用します。これは HTML エスケープされます。
  • <Content> セクション内の JavaScript コードでは、gadgets.Prefs() 関数を使用します。

ユーザー設定の共有

shareable-prefs 機能を使えば、ガジェットのユーザー設定を複数のユーザーで編集できるようになります。つまり、ユーザーはガジェットを共有して互いの編集内容を確認できます。たとえば家族で買い物リストのガジェットを共有すれば、それぞれが欲しい商品を追加できます。ユーザー設定データは、iGoogle がホストするガジェット状態の一部です。ユーザー設定について詳しくは、Gadgets API デベロッパー ガイドをご覧ください。

複数のユーザーでガジェットのユーザー設定を共有するには、ガジェットの <ModulePrefs> セクションに行 <optional feature="shareable-prefs"/> を含める必要があります。たとえばこのガジェットでは、list データ型のユーザー設定を使って買い物リストのデータを入力します。

このガジェットの共有

このガジェットのコードは次のとおりです。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs 
    title="Our Grocery List" 
    scrolling="true"> 
    <optional feature="shareable-prefs"/> 
   </ModulePrefs>
  <UserPref name="mylist" 
    display_name="Add items" 
    datatype="list" />
  <Content type="html">
  <![CDATA[ 
    <div id="content_div" style='color: #CC0099; font-family: serif; font-size: 120%;'></div>

  <script type="text/javascript"> 
    // Get userprefs
    var prefs = new gadgets.Prefs();
    // Get the list
    var items = prefs.getArray("mylist");  
    var html = "";
    // If there are no items in the list yet, display message.
    if (items.length == 0)
    {
      html += "Edit the userprefs to add items to the list.";
    }
    else {
      for (var i = 0; i < items.length ; i++) {
        var term = (items[i]);
        html += term + "<br />";
      }
    }
    document.getElementById("content_div").innerHTML = html; 
  </script>
  ]]> 
  </Content>
</Module>

共有可能な設定をサポートするガジェットを iGoogle に追加したら、次の方法でそのガジェットを共同使用できるようにします。

ステップ 1: 共有するガジェット上にある三角形をクリックして、[このガジェットを共有] を選択します。

このガジェットの共有

ステップ 2: あなたが Gmail ユーザーの場合は、このガジェットを共有する友だちを選択するか、友だちのメール アドレスを入力します。

このガジェットの共有

ステップ 3: 友だちにガジェットのコンテンツ編集を許可するか、または友だちの iGoogle ページにガジェットを表示するだけにするかを決定します。

  • [コンテンツの表示と編集] を選択した場合、友だちはガジェットのユーザー設定を編集できます。この変更は、ガジェットのあなたのバージョンと他の共有バージョンに反映されます。
  • [コンテンツの表示] を選択した場合、友だちはガジェットもローカル コピーも編集できません。あなただけがガジェットを変更でき、その変更はそのガジェットのすべての共有バージョンに反映されます。

[招待状を送る] をクリックします。友だちは招待メールを受け取り、自分の iGoogle ページにガジェットを追加することができます。

共有の招待

ガジェットの編集を許可された友だちは、ガジェットのユーザー設定を変更し、その変更をそのガジェットのすべての共有バージョンに公開できます。

ガジェット設定の定義

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> 属性の一覧については、リファレンスをご覧ください。

注: ガジェットは必ず公開されます

「非公開のガジェット」というものは存在しません。ガジェットを公のウェブサイトに公開すると、不特定多数の人がそれを見つけて表示できます。電話番号や個人的なメールアドレスなど、ガジェットに個人情報が含まれていないことを確認してください。

ガジェットを公開したくない場合はどうしたらよいでしょうか。Google では、ガジェットを作成したら、その仕様を共有することを推奨しています。しかし、公開できる状態になるまでは、できるだけ人目につかないようにしたいかもしれません。以下に、そのような場合に役立つヒントを示します。

  • ガジェットをコンテンツ ディレクトリに登録したり、googlemodules.comhotmodules.com のようなディレクトリに投稿しないようにします。
  • ユーザーが、ガジェットが見つからないからといって、その URL を推定する可能性は低いでしょう。検索エンジンで検出されないようにするには、以下の点を確認します。
    • ウェブ サーバー上のファイル リストに、ガジェット ファイルが含まれていないかどうか (これは、ユーザーののぞき見対策にもなります)。
    • ガジェットにリンクしているハイパーリンクがないかどうか。

さらに詳しく

より複雑なガジェットを作成したい場合は、開発の基礎をご覧ください。ドキュメント ホーム ページに戻ると、セクションとトピックの一覧が表示されます。

トップへ戻る