Gadgets API

Gadgets API
- その他のガジェット

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

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

基本的な手順

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

テキストエディタでガジェットの仕様を記述し、公開ウェブサーバーでホストします。
ガジェットをコンテナ (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.com や hotmodules.com のようなディレクトリに投稿しないようにします。
ユーザーが、ガジェットが見つからないからといって、その URL を推定する可能性は低いでしょう。検索エンジンで検出されないようにするには、以下の点を確認します。
- ウェブサーバー上のファイルリストに、ガジェットファイルが含まれていないかどうか (これは、ユーザーののぞき見対策にもなります)。
- ガジェットにリンクしているハイパーリンクがないかどうか。

さらに詳しく

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

トップへ戻る


例: "ajax apis" または "オープンソース"

Gadgets API

Gadgets API

その他のガジェット

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

目次

基本的な手順

ガジェットの構造

コンテンツの定義

ユーザー設定の定義

ユーザー設定代入変数

ユーザー設定の共有

ガジェット設定の定義

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

さらに詳しく

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