Gadgets API

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

ユーザーインターフェースの作成

このドキュメントでは、ガジェットにユーザーインターフェースのさまざまな要素を追加する方法について説明します。

ビュー

ビューは、ガジェットが表示されるコンテナ内の場所です。さまざまなビューに、さまざまな特性があります。たとえば、コンテナには小さい形式のガジェットが表示される場合と、全画面形式のガジェットが表示される場合があります。コンテナがサポートするビューについては、コンテナのドキュメントをご覧ください。

たとえば iGoogle サンドボックスでは、ガジェットはホームビューモード (小さい表示モード) で表示されます。これは、他のガジェットとともに段組のレイアウトで表示されます。ガジェットのキャンバスビュー (全画面表示モード。ガジェットは領域の横幅全体に拡大されます) を作成するには、次のように<Content> セクションを「canvas」ビュータイプとして定義する必要があります。

<Content type="html" view="canvas">

iGoogle をターゲットとするガジェットのキャンバスビューで、<Content> セクションを定義すると仮定します。この場合、<Content> セクションも作成して、ガジェットがホームビューで正しく表示されるようにする必要があります。これは、「default」または「home」のいずれかにします。複数の <Content> セクションをサポートするガジェットの作成については、複数のコンテンツセクションを含めるをご覧ください。

これは、Hello World ガジェットで <Content> セクションに「home」と「canvas」のビューを定義したバージョンの例です。ホームビューで表示するかキャンバスビューで表示するかによって、幅が変化します。

<?xml version="1.0" encoding="UTF-8" ?>
<Module> 
  <ModulePrefs title="Hello World!">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="home">
    <![CDATA[
      Hello, small world!
    ]]>  
  </Content>
  <Content type="html" view="canvas"> 
    <![CDATA[
      Hello, big world!
    ]]> 
  </Content>
</Module>

複数のコンテンツセクションを含める

1 つのガジェット XML ファイルには、複数の <Content> セクションを含めることができます。各 <Content> セクションは、それぞれがレンダリングするビューを宣言します。ドキュメント内のすべての <Content> セクションは兄弟関係にあり、レンダリングするビューをオプションパラメータ view= を使用して定義することもできます。

2 つのコンテンツセクション

「profile」と「canvas」という 2 つのコンテンツセクションを含む 1 つのガジェットを表す簡単な例を次に示します。これらのビューは orkut コンテナによってサポートされます。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Multiple Content Sections (version 1)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>
  </Content>
  <Content type="html" view="canvas">
  <![CDATA[
    <h1>Canvas</h1>
  ]]>
  </Content>
</Module>

出力は以下のようになります。

プロファイルビュー

<h1>Profile</h1>

キャンバスビュー

<h1>Canvas</h1>

キャンバスまたはプロファイル以外のビュー

コンテンツは表示されない

複数のビューが指定されたコンテンツセクション

コンテンツセクションには、複数のビューをカンマ区切りで指定できます。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Multiple Content Sections (version 2)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="canvas,profile">
  <![CDATA[
    <h1>Canvas and Profile</h1>
  ]]>
  </Content>
</Module>

出力は以下のようになります。

プロファイルビュー

<h1>Canvas and Profile</h1>

キャンバスビュー

<h1>Canvas and Profile</h1>

キャンバスまたはプロファイル以外のビュー

コンテンツは表示されない

ビューは指定されているがデフォルトコンテンツセクションが指定されていないコンテンツセクション

コンテンツセクションにビューパラメータを指定した場合、そのコンテンツセクションはそのビューにのみ表示されます。他のビューには、デフォルトコンテンツセクションを指定しない限りコンテンツは表示されません。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>  
  <ModulePrefs title="Multiple Content Sections (version 3)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>        
  </Content>
</Module>

出力は以下のようになります。

プロファイルビュー

<h1>Profile</h1>

キャンバスビュー

コンテンツは表示されない

キャンバスまたはプロファイル以外のビュー

コンテンツは表示されない

ビューとデフォルトコンテンツセクションが指定されているコンテンツセクション

デフォルトコンテンツを指定するには、次のようにビューパラメータのないコンテンツセクションを定義します。

<Module>  
  <ModulePrefs title="Multiple Content Sections (version 4)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>        
  </Content>
  <Content type="html">
  <![CDATA[
    <h1>Default</h1>
  ]]>
  </Content>
</Module>

出力は以下のようになります。

プロファイルビュー

<h1>Profile</h1>

キャンバスビュー

<h1>Default</h1>

キャンバスまたはプロファイル以外のビュー

<h1>Default</h1>

サンプルコード全体

これらすべての手法を 1 つのガジェットにまとめると次のようになります。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Multiple Content Sections (version 5)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>
  </Content>
  <Content type="html" view="canvas">
  <![CDATA[
    <h1>Canvas</h1>
  ]]>
  </Content>
  <Content type="html" view="canvas,profile">
  <![CDATA[
    <h2>This shows up in canvas and profile views</h2>
  ]]>
  </Content>
  <Content type="html">
  <![CDATA[
    <h1>Default</h1>
    <h2>The content in this section only shows up if no other content sections are applicable</h2>
  ]]>
  </Content>
</Module>

出力は以下のようになります。

プロファイルビュー

<h1>Profile</h1>
<h2>This shows up in canvas and profile views</h2>

キャンバスビュー

<h1>Canvas</h1>
<h2>This shows up in canvas and profile views</h2>

キャンバスまたはプロファイル以外のビュー

<h1>Default</h1>
<h2>The content in this section only shows up if no other content sections are applicable</h2>

ビューを連結する

ビューはさまざまな OpenSocial コンテナでサポートされますが、サポートされるビューのセットは各コンテナで異なる可能性があります。たとえば iGoogle には home という名前の小さなビューがありますが、orkut の小さなビューは profile という名前です。

iGoogle の home と orkut の profile と同じ表示のガジェットを作成すると仮定します。この場合、重複する <Content> セクションを作成するのではなく、1 つの <Content> セクションのビューを次のようにして連結できます。

<Content type="html" view="home,profile">

この手法はコンテナ間で使用することも、同一コンテナ内で使用することもできます。たとえばサイズの異なるビューの表示ロジックを 1 つの <Content> セクションで処理するガジェットは、view="home,canvas" を定義することでそのサポートをキャンバスページにまで拡張できます。

現在のガジェットビューを判定する

現在のビューを取得するための最も簡単な方法は、ガジェットのモジュール設定に「views」機能を追加する方法です。

<ModulePrefs title="Views example"> 
  <Require feature="views" />
</ModulePrefs>

views 機能が追加されていると、gadget.util.getCurrentView() 関数を呼び出すことで、現在のビューを取得できます。

次に、現在のビューを取得して、返された値に対して条件に応じたコードを実行する例を示します。

function getViewName() {
  return gadgets.views.getCurrentView().getName();
}

if (getViewName() == "canvas") {
  /* Do canvas specific stuff here */
}

if (getViewName() == "home") {
  /* Do home specific stuff here */
}

使用可能なビューをすべて取得する

このセクションのコードを使用するには、ガジェットの ModulePrefs セクションに必ず

<Require
      feature="views">

を入れてください。

gadgets.views.getSupportedViews() 関数を呼び出して、使用可能な View オブジェクトを取得します。

var supported_views = gadgets.views.getSupportedViews();

getSupportedViews 呼び出しによって返されるオブジェクトには、iGoogle で使用可能なすべてのビューを表す、ビュー名によってインデックス化された gadgets.views.View オブジェクトが含まれます。

別のビューに移動する

このセクションのコードを使用するには、ガジェットの ModulePrefs セクションに必ず

<Require
      feature="views">

を入れてください。

他のビューへのリンクを提供する場合は、gadgets.views.requestNavigateTo() メソッドに gadgets.views.View オブジェクトを渡す必要があります。getSupportedViews() 呼び出しによって返されるオブジェクトの 1 つを選択することができます。次は、このメソッドを示したコードの例です。

  function navigateTo(dest) {
    var supported_views = gadgets.views.getSupportedViews();
    gadgets.views.requestNavigateTo(supported_views[dest]);
  };

  /**
   * When called, this method asks the container to switch to the canvas
   */
  function gotoCanvas() {
    navigateTo("canvas");
  };

  /**
   * When called, this method asks the container to switch to the home
   */
  function gotoHome() {
    navigateTo("home");
  };

別の方法としては、新しい View オブジェクトを手作業で作成し、それを使用してナビゲーションを開始することもできます。次のコードは、新しい gadgets.views.View オブジェクトを作成して gadgets.views.requestNavigateTo() メソッドに渡す例を示しています。

  /**
   * When called, this method asks the container to switch to the canvas
   */
  function gotoCanvas() {
    var canvas_view = new gadgets.views.View("canvas");
    gadgets.views.requestNavigateTo(canvas_view);
  };

  /**
   * When called, this method asks the container to switch to the home
   */
  function gotoHome() {
    var home_view = new gadgets.views.View("home");
    gadgets.views.requestNavigateTo(home_view);
  };

これは「Hello World」ガジェットを基にした、完全な例です。

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs height="100" title="Navigation">
    <Require feature="views" /> 
  </ModulePrefs>
  <Content type="html" view="home">
  <![CDATA[ 
  <div>Hello world Home view</div>
  <script type="text/javascript">
  
    function goToView(dest) {
      var supported_views = gadgets.views.getSupportedViews();
      gadgets.views.requestNavigateTo(supported_views[dest]);
    };
  </script>

  <a href="javascript:goToView('canvas')" >Go to canvas view</a><br><br>

  ]]> 
  </Content>
  <Content type="html" view="canvas">
  <![CDATA[ 
  <div>Hello world Canvas view</div>
  <script type="text/javascript">
  
    function goToView(dest) {
      var supported_views = gadgets.views.getSupportedViews();
      gadgets.views.requestNavigateTo(supported_views[dest]);
    };
  </script>
  <a href="javascript:goToView('home')" >Go to home view</a><br><br>
  ]]> 
  </Content>
  </Module>

requestNavigateTo() によりデータを渡す

このセクションのコードを使用するには、ガジェットの ModulePrefs セクションに必ず

<Require
      feature="views">

を入れてください。

gadgets.views.requestNavigateTo() 呼び出しを使用している場合は、新しいページに渡すデータを含むオプションパラメータを指定することができます。

次のコードは、foo と bar の 2 つの変数を現在のガジェットのキャンバスサーフェスに渡しています。

  function gotoCanvas(params) {
    var canvas_view = new gadgets.views.View("canvas");
    gadgets.views.requestNavigateTo(canvas_view, params);
  };

  var my_params = {
    foo : 12345,
    bar : "Bar value"
  };

  gotoCanvas(my_params);

キャンバスビューでは、これらの値を次のコードによって確認します。

  var prefs = gadgets.views.getParams();
  var foo = prefs["foo"];
  /* foo contains 12345 */

  var bar = prefs["bar"];
  /* bar contains "Bar value" */<sup class="changed">New!</sup>

ガジェットの高さの管理

デフォルトのガジェットの高さは 200 ピクセルです。<ModulePrefs> 属性 height="nn" を使用して、ガジェットの静的高さをデフォルトから変更できます。<ModulePrefs> 属性 scrolling="true" を使用すると、指定された高さよりもガジェットが高い場合に、ガジェットに縦のスクロールバーを付けることができます。

ガジェットによっては、動的に高さを変更できる必要があります。たとえばリストを表示するガジェットでは、リストの内容に合わせて、ガジェットの高さを高く、または低くする必要があります。ユーザーがリストに項目を追加すると、ガジェットは高くなります。ユーザーがリストをクリアすると、ガジェットは元の高さに戻ります。実行中のガジェットの例を次に示します。

ガジェット自体がサイズを変更できるようにするため、ガジェットの仕様に以下を追加する必要があります。

dynamic-height ライブラリを読み込むようガジェットに指示する <Require feature="dynamic-height"/> タグ (<ModulePrefs> の下に置きます)。
JavaScript 関数 gadgets.window.adjustHeight() への呼び出し。コンテンツの変更時や、ガジェットのサイズを変更する必要があるその他のイベントの発生時ごとに呼び出します。

買い物リストのガジェットの仕様の例を次に示します。

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Dynamic Height" 
    height="100"> 
    <Require feature="dynamic-height"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
    <script type="text/javascript">
    // This example lets users add items to a grocery list and then clear the list.
    // When items are added or cleared, the gadget resizes itself.
    var mylist = "";
    var flag = 0;

    // Function that is invoked whenever user clicks the Add button to add an
    // item to the list.
    function addToList (form) {
        var input = _trim(form.inputbox.value);
        if (input == "") {
            return;
        }

        // Make alternating lines green/white, depending on value of flag variable.
        if(flag == 0){
            mylist += "<div style='padding-left: 5px;background-color: #E6FFE6; font-family:Arial, Helvetica;'>" +input + "</div>";
            flag = 1;
        }
        else {
            mylist += "<div style='padding-left: 5px;font-family:Arial, Helvetica;'>" +input + "</div>";
            flag = 0;
        }

        // Call setContent to output HTML to div and resize gadget
        setContent(mylist);
    }

    // Clear the list
    function clearList(form) {
        // Call setContent to remove all items from the list and resize the gadget
        setContent("");
    }

    // Outputs content to the div and resizes the gadget
    function setContent(html) {
        document.getElementById('content_div').innerHTML = html;

       // Tells gadget to resize itself
       gadgets.window.adjustHeight();
    }
    </script>
  <FORM NAME="myform" ACTION="" METHOD="GET"><BR>
  <INPUT TYPE="text" NAME="inputbox" VALUE="">
  <INPUT TYPE="button" NAME="button" Value="Add" onClick="addToList(this.form)">
  <INPUT TYPE="button" NAME="button2" Value="Clear" onClick="clearList(this.form)">
  </FORM>
  <div id="content_div"></div>
  ]]>
  </Content>
</Module>

ガジェットの幅と高さをテストするガイドラインについては、幅と高さのテストをご覧ください。

ガジェットのタイトルの設定

gadgets.window.setTitle() 関数を使用すると、ガジェットのタイトルをプログラムで設定できます。この関数を使用するには、ガジェットの仕様に以下を含める必要があります。

settitle ライブラリを読み込むようガジェットに指示する <Require feature="settitle"/> タグ (<ModulePrefs> の下に置きます)。
ガジェットのタイトルを設定する gadgets.window.setTitle() への呼び出し。

次の例では、ユーザーがガジェットのタイトルを設定できるテキストフィールドを提供します。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Set Title Example">
    <Require feature="settitle"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
    <script type="text/javascript">
    function changeTitle(form) {
      var newTitle = form.inputbox.value;
      gadgets.window.setTitle(newTitle);	 
    }
    </script>
<FORM NAME="myform" ACTION="" METHOD="GET">Change the Gadget Title: <BR><BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><BR><BR>
<INPUT TYPE="button" NAME="button" Value="Change Title" onClick="changeTitle(this.form)">
</FORM>
<div id="content_div"></div>
  ]]>
  </Content>
</Module>

タブ

tabs ライブラリを使用すると、ガジェットにタブ付きのユーザーインターフェースを追加できます。タブを使用するには、ガジェットの仕様に少なくとも以下を含める必要があります。

tabs ライブラリを読み込むようガジェットに指示する <Require feature="tabs"/> タグ (<ModulePrefs> の下に置きます)。
タブを構成し、タブのコンテンツを設定する JavaScript。詳しくは仕組みをご覧ください。

また通常は、setprefs ライブラリを含めて、ユーザーが前回選択したタブをガジェットの実行後も保存できるようにします。これにより、ユーザーがページからいったん離れても、戻ってきたときに、記録されていたタブがガジェットに読み込まれます。この機能を利用するには、ガジェットの仕様に次の 2 行のコードを追加してください。

<Require feature="setprefs"/>
...
<UserPref name="selectedTab" datatype="hidden"/>

タブオブジェクトの構造

tabs ライブラリは次のオブジェクトを処理するための関数と CSS を提供します。

TabSet オブジェクト。この tabs オブジェクトはすべてのタブの親コンテナです。プログラム上では、tabs オブジェクトは個々の tab オブジェクトの配列です。元になる HTML の実装では、通常 <table> 要素であり、API の中では「ヘッダーコンテナ」と呼ばれます。この HTML には gadgets.TabSet.getHeaderContainer() 関数を使ってアクセスします。
tab オブジェクト。tab オブジェクトは、インデックス付きタブの配列内の個々のタブです。元になる HTML 実装では、通常 <td> 要素であり、API の中では「ネームコンテナ」と呼ばれます。この HTML には gadgets.Tab.getNameContainer() 関数を使ってアクセスします。
コンテンツコンテナ。コンテンツコンテナには、個々の tab オブジェクトのコンテンツが保管されます。元になる HTML 実装では、通常 <div> 要素であり、API の中では「コンテンツコンテナ」と呼ばれます。この HTML には gadgets.Tab.getContentContainer() 関数を使ってアクセスします。

仕組み

gadgets.TabSet() コンストラクタを使用して、tabs オブジェクト (インデックス付きタブのセットを含むオブジェクト) を作成します。例を次に示します。

// Initialize tabs, designate the tab named "Two" as 
// the tab selected by default. 
var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");

tabs オブジェクトの作成後に、addTab() 関数を使用して個々のタブを追加できます。個々のタブには、インデックス、名前、一意の ID (対応する <div> の ID に一致) の 3 つの主要なコンポーネントがあります。<div> はそのタブのコンテンツが置かれる場所です。<div> コンテナを自分で指定しない場合は、tabs ライブラリが自動的に生成します。

addTab() メソッドには、次の引数を指定します。

String tabName-- 作成するタブのラベルです。
Object opt_params-- オプションのパラメータオブジェクトです。これには次の項目を含めることができます。
- contentContainer-- タブのコンテンツコンテナとして使用する既存の HTML 要素。省略すると、タブライブラリにより作成されます。
- callback-- タブが選択されたときに実行するコールバック関数。
- tooltip-- ユーザーがマウスカーソルをタブに重ねたときにポップアップするツールチップの説明。
- index-- タブを挿入するインデックス。省略すると、新しいタブは末尾に追加されます。

addTab() は、タブコンテナの DOM ID を含む文字列を返します。

タブを tabs オブジェクトに追加して、次のいずれかの方法で、タブにコンテンツを設定できます。

テクニック 1: タブの作成時にタブの ID を取得し、その ID を使用してそのタブに対応する <div> にコンテンツを追加します。

var one_Id = tabs.addTab("One"); 
document.getElementById(one_Id).innerHTML = "Content for tab One.";

同様の方法で、HTML でタブの名前を定義することもできます。例を次に示します。

var one_Id = tabs.addTab('<div style="color: red; font-weight: bold; background-color:#ccf;">Cool Tab</div>');
document.getElementById(one_Id).innerHTML = "Content for tab One.";

テクニック 2: タブを作成して、対応する <div> をガジェットの HTML 部分に追加し、静的コンテンツを <div> に含めます。

tabs.addTab("Two", "two_id");
...
</script>     
<div id="two_id" style="display:none">Content for tab Two.</div>

テクニック 3: タブを作成して、対応する <div> をガジェットの HTML 部分に追加し、静的コンテンツを <div> に含めます。コールバック関数を使用して、動的コンテンツを静的コンテンツに追加します。

tabs.addTab("Three", "three_id", callback); 
...
function callback(tabId) {
  var p = document.createElement("p");
  p.innerHTML = "This is dynamic content generated in callback.";
  document.getElementById(tabId).appendChild(p);
}
...
</script>
<div id="three_id" style="display:none">This is static content for tab Three.</div>

テクニック 4: addTab(tabName, opt_params) 関数を使用して、タブを名前で指定して追加します。例を次に示します。

tabs.addTab("Tab", { 
     contentContainer: document.getElementById("domId"), 
     callback: func, 
     tooltip: "Popup description" 

});

タブの追加とコンテンツの設定のさまざまな方法を示すサンプルガジェットを次に示します。

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Tabs Demo" height="140" scrolling="true" > 
    <Require feature="tabs" /> 
  </ModulePrefs>
  <Content type="html">
  <![CDATA[ 

    <script type="text/javascript">
    // Initialize tabs, designate the tab named "Two" as
    // the tab selected by default.
    var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");
    function init() {
        // Technique #1: Capture the tab's ID when you create it, and use the ID 
        // to add content to the tab's corresponding <div>.        
        var one_Id = tabs.addTab('<div style="color: red; font-weight: bold; background-color:#ccf;">Cool Tab</div>');       
        document.getElementById(one_Id).innerHTML = "Content for tab One.";

        // Technique #2: Create the tab and define a corresponding <div> in the
        // HTML portion of the gadget. Add static content to the <div>.      

        tabs.addTab("Two", {
           contentContainer: document.getElementById("two_id")
        });

        // Technique #3: Create the tab and define a corresponding <div> in the
        // HTML portion of the gadget. Add static content to the <div>.
        // Use a callback function to add dynamic content to the static content.

        tabs.addTab("Three", {
           contentContainer: document.getElementById("three_id"),
           callback: callback
        });

        // Technique #4: Create the tab with a tooltip message. If specified <div>
        // doesn't exist, tabs library creates one.   
        // Invoke callback function.        
        tabs.addTab("Four", {            
           contentContainer: document.getElementById("four_id"),
           callback: callback,            
           tooltip: "I'm special"          
        });
    }

    // Callback that provides content to tabs Three and Four
    function callback(tabId) {
      var p = document.createElement("p");
      // Get selected tab
      var selectedTab = tabs.getSelectedTab();
      p.innerHTML = "This is dynamic content generated in callback for tab " + selectedTab.getName();
      document.getElementById(tabId).appendChild(p);
    }

    // Call init function to initialize and display tabs.
    gadgets.util.registerOnLoadHandler(init);
    </script>

   <div id="two_id" style="display:none">Content for tab Two.</div>
   <div id="three_id" style="display:none">This is static content for tab Three.</div>
  ]]>
  </Content>
</Module>

インデックスによるタブの操作

タブの API には、インデックスによりタブを操作できる関数もあります。タブには 0 から n までのインデックスが付けられ、最初のタブのインデックスは 0 です。たとえばタブが 3 つある場合、インデックスは 0、1、2 となります。インデックスを使用してプログラム上でタブを選択し、2 つのタブの位置を交換できます。

タブの ID は固定ですが、インデックスは固定ではありません。たとえば 3 番目のタブを 1 番目に移動すると、インデックスは 2 から 0 に変わります。

プログラム上でタブを選択する例を次に示します。このスニペットはリンクを作成します。ユーザーがこのリンクをクリックすると、ユーザーがタブそのものをクリックしたかのように、2 番目のタブが選択されます。

<script>
...
function selectTab() {
    tabs.setSelectedTab(1);
}
</script>

<a href="javascript:void(0)" onclick="selectTab()">Select Second Tab</a>

プログラム上でタブを移動する例を次に示します。このスニペットはリンクを作成します。ユーザーがこのリンクをクリックすると、ガジェットは 1 番目のタブと 2 番目のタブの位置を交換します。

<script>
...
function switchTabs() {
    tabs.swapTabs(0, 1);
}

</script>
<a href="javascript:void(0)" onclick="switchTabs()">Switch Tabs</a>

タブの表示のカスタマイズ

このセクションでは、CSS または JavaScript を使用して、タブの外観をカスタマイズできる方法について説明します。

CSS によるタブのカスタマイズ

タブの CSS は、タブをレイアウトする HTML 要素に適用されるクラスを定義します。

次の CSS クラスを使用して、デフォルトの設定をオーバーライドして、タブのデザインを変えることができます。

CSS Class	説明
`.tablib_table`	タブを含む HTML 表に適用されます。
`.tablib_selected`	選択されたタブに適用されます。
`.tablib_unselected`	選択されていないすべてのタブに適用されます。
`.tablib_spacerTab`	各タブの間のスペーサー要素に適用されます。
`.tablib_emptyTab`	タブの周りの開始と終了のスペーサーを制御します。
`.tablib_navContainer`	すべてのタブ関連のコンテンツ (タブのヘッダーと個々のコンテンツコンテナのすべて) を含む親コンテナに適用されます。

次は CSS クラスと設定のデフォルトです。これを上書きして使うことができます。

.tablib_table {
  width: 100%;
  border-collapse: separate;
  border-spacing: 0px;
  empty-cells: show;
  font-size: 11px;
  text-align: center;
}
.tablib_emptyTab {
  border-bottom: 1px solid #676767;
  padding: 0px 1px;
}
.tablib_spacerTab {
  border-bottom: 1px solid #676767;
  padding: 0px 1px;
  width: 1px;
}
.tablib_selected {
  padding: 2px 0px;
  background-color: #ffffff;
  border: 1px solid #676767;
  border-bottom-width: 0px;
  color: #3366cc;
  font-weight: bold;
  width: 80px;
  cursor: default;
}
.tablib_unselected {
  padding: 2px 0px;
  background-color: #dddddd;
  border: 1px solid #aaaaaa;
  border-bottom-color: #676767;
  color: #000000;
  width: 80px;
  cursor: pointer;
}
.tablib_navContainer {
  width: 10px;
  vertical-align: middle;
}
.tablib_navContainer a:link, .tablib_navContainer a:visited, .tablib_navContainer a:hover {
  color: #3366aa;
  text-decoration: none;
}

例を次に示します。

<![CDATA[ 
  <style type="text/css"> 
   .tablib_selected { color: #FF0000; }
   .tablib_unselected { color: #660099; }
   .tablib_table { font-size:20px; }
   .tablib_emptyTab { padding:2px 5px; }
   .tablib_spacerTab { padding:0px 5px; }
  </style>
<script...>

JavaScript を使用して、CSS スタイルをタブのヘッダーコンテナに適用することもできます。関数 getHeaderContainer() から、タブの HTML 表が返されるので、必要に応じてそれを変更できます。

たとえば次のスニペットは、フォントサイズを変更し、最上部にマージンを追加します。

var tabs = new gadgets.TabSet();
...

var table = tabs.getHeaderContainer();
table.style.fontSize = "10px";
table.style.marginTop = "15px";

個々のタブのヘッダーのスタイルは、個々のタブの要素を取得して、そのプロパティを変更することでカスタマイズできます。1 番目のタブのスタイルを固有に変更する例を次に示します。

var tabs = new gadgets.TabSet();
tabs.addTab("Unique");
...
var firstTab = tabs.getTabs()[0].getNameContainer();
firstTab.style.backgroundColor = "#999999";
firstTab.style.color = "#ffffff";

タブの配置の変更

デフォルトでは、タブは中央に追加されます。ただし、タブが 3 つか 4 つより少ない場合、左または右に配置することもできます。これには alignTabs() 関数を使用します。指定するパラメータは 1 つで、その値は left、right、center のいずれかです。タグを左または右に配置する場合、オプションのパラメータを渡して、左または右の端からのオフセットの幅を指定できます。デフォルトのサイズは 3 ピクセルです。

例を次に示します。

var tabs = new gadgets.TabSet();
...
// Align tabs to the left and offset it by 10 pixels
tabs.alignTabs("left", 10);

タブの非表示

displayTabs() 関数を使用して、タブとそのコンテンツの表示を切り替えることができます。この関数には true または false のブール値のパラメータを指定します。

タブを表示または非表示にするボタンを作成する例を次に示します。

<input onclick="toggleTabs()" type="button" value="Show/Hide"/>
<script>
var tabs = new gadgets.TabSet();
...
var showTabs = true;
function toggleTabs() {
  showTabs = !showTabs;
  tabs.displayTabs(showTabs);
}
</script>

MiniMessage

MiniMessage はガジェット内でユーザーに一時的に表示されるメッセージです。MiniMessage は、プログラムまたはユーザーによって閉じることができます。MiniMessage の基本タイプは、次のとおりです。

ユーザーが [x] をクリックすることで、閉じることができるメッセージ。
指定した秒数が経過した後消えるタイマーメッセージ。
プログラムで閉じる必要のある静的メッセージ。

MiniMessage を使用するには、ガジェットの仕様に以下を含める必要があります。

MiniMessage ライブラリを読み込むようガジェットに指示する <Require feature="minimessage"/> タグ (<ModulePrefs> の下に置きます)。
MiniMessage の動作を記述する JavaScript 関数。MiniMessage ライブラリのすべての関数の一覧は、Gadgets API リファレンスをご覧ください。

MiniMessage を使用すると便利な理由は、次のとおりです。

宣伝: MiniMessage を使用して、ガジェットに宣伝用メッセージを表示できます。
ステータス: ガジェットの多くは、バックグラウンドでデータをフェッチし、読み込んでいます。MiniMessage を使用して、「読み込み中」などのステータス関連のメッセージを表示できます。
デバッグ/エラー: ガジェットでエラーが発生した場合、メッセージの表示なしで失敗するのではなく、MiniMessage を使用してユーザーに知らせることができます。
その他: ガジェットの種類 (カレンダー、eBay など) に応じて、ユーザーにお知らせを表示することもできます。MiniMessage は小さくて、閉じることができるので、特別な情報を伝えることができます。

仕組み

ガジェットに MiniMessage を追加する基本的な手順は簡単です。

1. MiniMessage ライブラリをインポートします。

<Require feature="minimessage"/>

2. gadgets.MiniMessage()コンストラクタを使用して、新しい MiniMessage オブジェクトをインスタンス化します。

var msg = new gadgets.MiniMessage(__MODULE_ID__);

通常は、このオブジェクトをどのスコープからもアクセスできる単一のグローバルオブジェクトにします。

3. 新しい MiniMessage を作成して、何らかのテキストを設定します。

msg.createDismissibleMessage("Please close me when you're done reading me.");

これにより、[x] の付いた、あらかじめフォーマットされた、閉じられるメッセージが、ガジェットの上部に追加されます。ユーザーが [x] をクリックすると、メッセージは閉じます。

できあがりです。さまざまなタイプの閉じられるメッセージの種類のうち 1 つを作成しました。

さまざまな場所でのメッセージの作成

デフォルトではメッセージは、ガジェットの最上部で、コンテナ HTML 要素の中に配置されます。その後に続くメッセージはそれぞれ上から順に、コンテナの子として追加されます。この配置は、すべてのメッセージ、またはメッセージ 1 つだけについて変更できます。

すべてのメッセージの位置の設定

HTML 要素 (<div> を推奨) をコンストラクタに渡すことによって、メッセージコンテナ要素のデフォルトの位置をオーバーライドできます。この要素は、メッセージが挿入され、表示される場所のメッセージコンテナになります。

たとえば次のスニペットでは、<h3> メッセージ「I'm on top now!」がガジェットの上部に表示されます。MiniMessage はメッセージが追加された順に、messageBox <div> の中のその下に表示されます。

<div>
  <h3>I'm on top now!</h3>
</div>


<div id="messageBox"></div>

<script type="text/javascript"> 
  // In the constructor, state that messages should be be displayed
  // in the messageBox <div> rather than at the top of the gadget.
  var msg = new gadgets.MiniMessage(__MODULE_ID__, document.getElementById("messageBox"));
  msg.createDismissibleMessage("I'm the first message.");
  msg.createDismissibleMessage("I'm the second message.");
  msg.createDismissibleMessage("I'm at the bottom.");

</script>

1 つのメッセージの位置の設定

閉じられるメッセージを、メッセージコンテナに追加するのではなく、指定した位置に作成できます。そのためには、ガジェットの HTML 部分の中でメッセージをマークアップし、その HTML 要素 (<div> を推奨) を createDismissibleMessage() への 1 番目のパラメータとして渡します。

たとえば次のスニペットでは、メッセージが status <div> の中に表示されます。

<div id="status" style="color:#B30000;">
  <b>Check out our new API documentation!</b> --
  <a href="http://www.google.com/apis/gadgets" target="_blank">Read</a>
</div>


<script type="text/javascript">
  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  // Pass the HTML element to createDismissableMessage() to indicate
  // where the message should be displayed.
  msg.createDismissibleMessage(document.getElementById("status"));
</script>

DOM メソッドを使用したメッセージの作成

HTML DOM メソッドを使用して、閉じられるメッセージを作成したい場合があります。このメッセージは DOM の中には存在しないため、デフォルトでメッセージコンテナに追加されます。

例を次に示します。

<script type="text/javascript"> 
  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  // Generate the message using DOM methods
  var div = document.createElement("div");
  div.innerHTML = "New message created by W3C DOM methods.";
  // Set some DOM properties
  div.onmouseover = function() {
    div.style.backgroundColor = "green";
  };
  div.onmouseout = function() {
    div.style.backgroundColor = "";
  };
  msg.createDismissibleMessage(div);

</script>

タイマーメッセージの作成

タイマーメッセージは、指定された時間が経過すると消える、あらかじめフォーマットされたメッセージです。関数 createTimerMessage() には、メッセージ文字列と、メッセージを表示する秒数を示す数の 2 つのパラメータを指定します。例を次に示します。

var msg = new gadgets.MiniMessage(__MODULE_ID__);
msg.createTimerMessage("I'm going to disappear in 5 seconds.", 5);

静的メッセージの作成

静的メッセージは、dismissMessage() 関数によりプログラム上で閉じられるまで表示される、あらかじめフォーマットされたメッセージです。これは、ガジェットがコンテンツのフェッチなどのバックグラウンドタスクを実行中であることを、ユーザーに知らせる通知メッセージを表示するのに便利です。例を次に示します。

  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  var loadMessage = msg.createStaticMessage(document.getElementById("loading"));

MiniMessage の表示のカスタマイズ

MiniMessage のデフォルトの外観を変更するには、次の 2 つの方法があります。

個々のメッセージの外観の変更
すべてのメッセージの外観のグローバルな変更

個々のメッセージのスタイルの変更

DOM 関数を使用して、メッセージのスタイルを変更します。新しい閉じられるメッセージを作成すると、HTML 要素が返されます。このメッセージの外観を変えるには、返された HTML 要素のスタイルプロパティを設定します。例を次に示します。

<script type="text/javascript">
  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  var statusMsg = msg.createDismissibleMessage("This is a critical error!");
  // Change the message's background color to red
  statusMsg.style.backgroundColor = "red";
  statusMsg.style.color = "white";
</script>

注: 上記の例では、メッセージの背景色全体を変更する正しい方法を示しています。メッセージを含む <div> の背景色を変更しても、背景色全体は変わりません。

すべてのメッセージのスタイルの変更

CSS を使用して、すべてのメッセージのスタイルをグローバルに変更します。CSS は、MiniMessage を定義する HTML 要素に適用されるクラスを定義します。

次の CSS クラスを使用して、デフォルトの設定をオーバーライドして、メッセージのデザインを変えることができます。

CSS Class	説明
`.mmlib_table`	メッセージを含む HTML 表に適用されます。
`.mmlib_xlink`	メッセージを閉じるのに使用する [x] リンクに適用されます。この設定は、閉じられるメッセージにのみ適用されます。

背景色をネイビーブルーに、前景色を白に変更する例を次に示します。

<![CDATA[
   <style>
     .mmlib_table__MODULE_ID__ {
       background-color: #000066;
       color: #ffffff;
     }
   </style>
<script...>

次は CSS クラスと設定のデフォルトです。これを上書きして使うことができます。

.mmlib_table {
  width: 100%;
  font: bold 9px arial,sans-serif;
  background-color: #fff4c2;
  border-collapse: separate;
  border-spacing: 0px;
  padding: 1px 0px;
  }
.mmlib_xlink {
  font: normal 1.1em arial,sans-serif;
  font-weight: bold;
  color: #0000cc;
  cursor: pointer;
  }

Flash

flash ライブラリを使用すると、ガジェットに Flash ムービー (具体的には .swf ファイル) を埋め込むことができます。Flash コンテンツを埋め込むには、ガジェットの仕様に少なくとも以下を含める必要があります。

flash ライブラリを読み込むようガジェットに指示する <Require feature="flash"/> タグ (<ModulePrefs> の下に置きます)。
ガジェットに .swf ファイルを埋め込んで、指定した位置に表示するための gadgets.flash.embedFlash() の呼び出し。この機能を使用するには、すべてのリソースが .swf ファイルにバンドルされている必要があります。

flash ライブラリには次の関数があります。

関数説明

関数	説明
`gadgets.flash.embedFlash(swf_url, swf_container, swfVersion, opt_params)`	`swf_url` で指定された `.swf` ファイルを埋め込み、ガジェットの中で `swf_container` で指定された位置に表示します。パラメータ `opt_params` は、有効な html パラメータを含めることのできる、オプションのオブジェクトです。 `R`正常に終了した場合は `true` を返し、それ以外は `false` を返します。注: パフォーマンスの問題が発生した場合や、キャレットが表示されない (Firefox 2.0 で発生することのある問題) 場合、`wmode`を`"window"`に明示的に設定してみてください。例:`gadgets.flash.embedFlash("example.swf", "wrapper", {wmode: "window"});`
`gadgets.flash.embedCachedFlash(swf_url, swf_container, swfVersion, opt_params)`	キャッシュされた Flash ファイルを DOM ツリーに注入します。パラメータと戻り値は、`embedFlash()` メソッドと同じです。
`gadgets.flash.getMajorVersion()`	Flash Player のメジャーバージョンを返すか、Flash Player が検出されなかった場合は 0 を返します。

gadgets.flash.embedFlash(swf_url, swf_container, swfVersion, opt_params)

swf_url で指定された .swf ファイルを埋め込み、ガジェットの中で swf_container で指定された位置に表示します。パラメータ opt_params は、有効な html パラメータを含めることのできる、オプションのオブジェクトです。

R正常に終了した場合は true を返し、それ以外は false を返します。

注: パフォーマンスの問題が発生した場合や、キャレットが表示されない (Firefox 2.0 で発生することのある問題) 場合、wmodeを"window"に明示的に設定してみてください。例:gadgets.flash.embedFlash("example.swf", "wrapper", {wmode: "window"});

gadgets.flash.embedCachedFlash(swf_url, swf_container, swfVersion, opt_params) キャッシュされた Flash ファイルを DOM ツリーに注入します。パラメータと戻り値は、embedFlash() メソッドと同じです。

gadgets.flash.getMajorVersion() Flash Player のメジャーバージョンを返すか、Flash Player が検出されなかった場合は 0 を返します。

Flash の例

このサンプルのガジェットでボタンをクリックすると、対応する .swf ファイルが再生されます。[Stop] をクリックすると、ガジェットは静止画を表示します。

この例のガジェットの仕様は次のとおりです。

<?xml version="1.0" encoding="UTF-8" ?> 
<Module> 
<ModulePrefs title="Trevor Does Tricks" height="300">
  <Require feature="flash" />
</ModulePrefs>
<Content type="html">
<![CDATA[

<style type="text/css">
  input.mybutton
  {
     background-color:#FFCC99;
     border-style:solid;
     border-color:#000000;
     font-family:Comic Sans MS,sans-serif;
     font-size:14px;
  }
</style>

<div id="flashcontainer" style="text-align: center;"></div> 

<script type="text/javascript">

  // Display still photo.
  function showPhoto() {
    document.getElementById("flashcontainer").innerHTML = "<img src='http://doc.examples.googlepages.com/Trevor.JPG' />";
  }

  // Play .swf file for specified trick.
  function doTrick(trick) {

    // The URL for the .swf file that shows the specified trick.
    var url = "http://doc.examples.googlepages.com/Trevor-"+trick+".swf";

    // Play .swf file.
      gadgets.flash.embedFlash(url, "flashcontainer", {
      swf_version: 6,
      id: "flashid",
      width: 300,
      height: 250
    })
  }

  // When gadget first loads, display still photo.
  gadgets.util.registerOnLoadHandler(showPhoto);
  </script>
  <br />
  <div style="text-align: center;"> 
    <input type=submit class="mybutton" value="Spin" onClick="doTrick('spin')">
    <input type=submit class="mybutton" value="Speak" onClick="doTrick('speak')">
    <input type=submit class="mybutton" value="Sit" onClick="doTrick('sit')">
    <input type=submit class="mybutton" value="Down" onClick="doTrick('down')">
    <input type=submit class="mybutton" value="Stop" onClick="showPhoto()">
  </div>
  ]]>
</Content>
</Module>

トップへ戻る


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

Gadgets API

Gadgets API

その他のガジェット

ユーザー インターフェースの作成

目次

ビュー

複数のコンテンツ セクションを含める

2 つのコンテンツ セクション

複数のビューが指定されたコンテンツ セクション

ビューは指定されているがデフォルト コンテンツ セクションが指定されていないコンテンツ セクション

ビューとデフォルト コンテンツ セクションが指定されているコンテンツ セクション

サンプル コード全体

ビューを連結する

現在のガジェット ビューを判定する

使用可能なビューをすべて取得する

別のビューに移動する

requestNavigateTo() によりデータを渡す

ガジェットの高さの管理

ガジェットのタイトルの設定

タブ

タブ オブジェクトの構造

仕組み

インデックスによるタブの操作

タブの表示のカスタマイズ

CSS によるタブのカスタマイズ

タブの配置の変更

タブの非表示

MiniMessage

仕組み

さまざまな場所でのメッセージの作成

すべてのメッセージの位置の設定

1 つのメッセージの位置の設定

DOM メソッドを使用したメッセージの作成

タイマー メッセージの作成

静的メッセージの作成

MiniMessage の表示のカスタマイズ

個々のメッセージのスタイルの変更

すべてのメッセージのスタイルの変更

Flash

Flash の例

ユーザーインターフェースの作成

複数のコンテンツセクションを含める

2 つのコンテンツセクション

複数のビューが指定されたコンテンツセクション

ビューは指定されているがデフォルトコンテンツセクションが指定されていないコンテンツセクション

ビューとデフォルトコンテンツセクションが指定されているコンテンツセクション

サンプルコード全体

現在のガジェットビューを判定する

タブオブジェクトの構造

タイマーメッセージの作成