Criação de uma interface de usuário

Este documento descreve como adicionar os diversos elementos de interface de usuário ao seu gadget.

Sumário

  1. Modos de exibição
    1. Inclusão de diversas seções de conteúdo
    2. Concatenação de modos de exibição
    3. Determinação do modo de exibição atual do gadget
    4. Obtenção de todos os modos de exibição disponíveis
    5. Navegação para outro modo de exibição
    6. Envio de dados por meio de requestNavigateTo()
  2. Gerenciamento da altura do gadget
  3. Definição do título do gadget
  4. Guias
    1. Anatomia de um objeto de guias
    2. Como funciona
    3. Manipulação de guias por índice
    4. Personalização da exibição de guias
  5. MiniMessages
    1. Como funciona
    2. Criação de mensagens em locais diferentes
    3. Criação de mensagens usando métodos DOM
    4. Criação de uma mensagem de temporizador
    5. Criação de uma mensagem estática
    6. Personalização da exibição de MiniMessages
  6. Flash
    1. Exemplo de Flash

Modos de exibição

Um modo de exibição é um local em um recipiente onde é exibido um gadget. Modos de exibição diferentes possuem características diversas. Um recipiente pode ter um modo de exibição que mostra gadgets em formato pequeno e um modo de exibição que mostra os gadgets em formato de página inteira. Para obter uma lista dos modos de exibição suportados pelo seu recipiente, consulte a documentação do recipiente.

Por exemplo, na sandbox do iGoogle, um gadget é exibido no modo de exibição de página inicial ("modo pequeno"), ou seja, ele aparece em um layout por colunas entre outros gadgets. Para criar um modo de exibição de tela ("modo grande") de seu gadget, no qual ele se expande horizontalmente para cobrir toda a área de gadgets, você deve definir uma seção <Content> no modo de exibição de "tela", da seguinte maneira:

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

Suponha que você defina uma seção <Content> para o modo de exibição de tela para um gadget destinado ao iGoogle. Você também deverá criar uma seção <Content> para fazer com que o gadget seja exibido apropriadamente no modo de exibição de página inicial. Isso pode ser "padrão" ou "página inicial". Para ler mais textos sobre como desenvolver gadgets que suportam múltiplas seções <Content>, consulte Inclusão de diversas seções de conteúdo .

Aqui está uma versão de um gadget Hello World que define os modos de exibição da seção <Content> como "página inicial" e "tela". Sua largura varia de acordo com o uso do modo de exibição inicial ou do modo de exibição de tela.

<?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>

Inclusão de diversas seções de conteúdo

Você pode incluir mais de uma seção <Content> em um arquivo XML de gadget, onde cada seção <Content> define as visualizações nas quais deve ser exibida. Todas as seções <Content> devem ser irmãs na árvore de documentos e podem usar o parâmetro view= opcional para definir as visualizações nas quais devem ser exibidas.

Duas seções de conteúdo

Veja um exemplo simples que mostra um gadget com duas seções de conteúdo, uma para o "perfil" e outra para a "tela". Esses são os modos de exibição suportados pelo recipiente do 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>

Veja como fica a saída:

Modo de exibição de perfil

<h1>Profile</h1>

Modo de exibição de tela

<h1>Canvas</h1>

Qualquer outro modo de exibição que não seja de tela ou perfil

nenhum conteúdo é exibido

Seções de conteúdo com diversos modos de exibição especificados

As seções de conteúdo podem especificar diversos modos de exibição, separados por vírgulas:

<?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>

Veja como fica a saída:

Modo de exibição de perfil

<h1>Canvas and Profile</h1>

Modo de exibição de tela

<h1>Canvas and Profile</h1>

Qualquer outro modo de exibição que não seja de tela ou perfil

nenhum conteúdo é exibido

Seção de conteúdo com modo de exibição especificado e nenhuma seção de conteúdo padrão

Se você especificar uma seção de conteúdo com um parâmetro de modo de exibição, ela será exibida somente neste modo de exibição. Se você não especificar uma seção de conteúdo padrão, os outros modos de exibição não exibirão nenhum conteúdo.

<?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>

Veja como fica a saída:

Modo de exibição de perfil

<h1>Profile</h1>

Modo de exibição de tela

nenhum conteúdo é exibido

Qualquer outro modo de exibição que não seja de tela ou perfil

nenhum conteúdo é exibido

Seção de conteúdo com modo de exibição especificado e uma seção de conteúdo padrão

Para especificar uma seção de conteúdo padrão, basta definir uma seção de conteúdo sem nenhum parâmetro de modo de exibição:

<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>

Veja como fica a saída:

Modo de exibição de perfil

<h1>Profile</h1>

Modo de exibição de tela

<h1>Default</h1>

Qualquer outro modo de exibição que não seja de tela ou perfil

<h1>Default</h1>

Exemplo completo

Você pode usar todas estas técnicas em um único gadget:

<?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>

Veja como fica a saída:

Modo de exibição de perfil

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

Modo de exibição de tela

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

Qualquer outro modo de exibição que não seja de tela ou perfil

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

Concatenação de modos de exibição

Os modos de exibição são suportados nos recipientes do OpenSocial, mas cada recipiente pode suportar um conjunto diferente de modos de exibição. Por exemplo, o iGoogle oferece um modo de exibição pequeno chamado home, mas esse mesmo modo de exibição no orkut é chamado de profile.

Vamos supor que você queira desenvolver um gadget que tenha a mesma exibição para o home no iGoogle e para o profile no orkut. Em vez de criar seções <Content> duplicadas, você pode concatenar os modos de exibição em uma única seção <Content>, da seguinte maneira:

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

Você pode usar esta técnica em diversos recipientes ou dentro do mesmo recipiente. Por exemplo, os gadgets que lidam com lógica de apresentação para modos de exibição com tamanhos diferentes em uma única seção <Content> podem estender esse suporte para a página da tela declarando view="home,canvas".

Determinação do modo de exibição atual do gadget

A maneira mais fácil de obter o modo de exibição atual é incluir o recurso "modos de exibição" nas preferências de módulo do seu gadget:

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

Quando o recurso de modo de exibição estiver incluído, você poderá obter o modo de exibição atual chamando a função gadget.util.getCurrentView().

O exemplo a seguir demonstra como obter o modo de exibição atual e executar códigos de forma condicional com o valor retornado:

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

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

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

Obtenção de todos os modos de exibição disponíveis

Obtenha os objetos View disponíveis chamando a função gadgets.views.getSupportedViews().

var supported_views = gadgets.views.getSupportedViews();
    

O objeto retornado pela chamada getSupportedViews contém os objetos gadgets.views.View representando todos os modos de exibição disponíveis no iGoogle, indexados por nome.

Se desejar fornecer links para outros modos de exibição, você precisa passar um objeto gadgets.views.View para o método gadgets.views.requestNavigateTo(). Você pode optar por usar um dos objetos retornados pela chamada getSupportedViews(). O exemplo de código a seguir demonstra este método:

  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");
  };
    

Uma alternativa é criar um novo objeto View manualmente e utilizar esse código para iniciar a navegação. O exemplo de código a seguir mostra a criação de um novo objeto gadgets.views.View e sua transferência para o método 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);
  };
    

Veja um exemplo completo com base no gadget "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>

    

Envio de dados por meio de requestNavigateTo()

Se você estiver usando as chamadas gadgets.views.requestNavigateTo(), você poderá fornecer um parâmetro opcional, contendo os dados a serem transmitidos para a próxima página.

O código a seguir transmite duas variáveis: foo e bar à superfície da tela do gadget atual:

  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);
    

No modo de exibição de tela, procure esses valores no código a seguir:

  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>
    

Gerenciamento da altura do gadget

Por padrão, os gadgets têm 200 pixels de altura. Você pode usar o atributo <ModulePrefs> height="nn" para especificar uma altura estática maior ou menor que a altura padrão. Você pode usar o atributo <ModulePrefs> scrolling="true" para criar uma barra de rolagem vertical para o gadget, caso a altura do conteúdo exceda a altura designada.

Entretanto, alguns gadgets precisam ter flexibilidade para alterar sua altura dinamicamente. Por exemplo, suponha que você criou um gadget de lista cuja altura precisa ser expandida e contraída, dependendo do conteúdo da lista. O gadget cresce à medida que os usuários adicionam itens à lista. Quando eles limpam a lista, o gadget retorna à altura original. Veja aqui a aparência do gadget sendo executado:

Gadget de lista de compras

Para adicionar ao seu gadget o recurso de redimensionamento, adicione os itens abaixo à especificação:

  • Uma tag <Require feature="dynamic-height"/> (em <ModulePrefs>) para informar ao gadget que ele precisa carregar a biblioteca dynamic-height.
  • Uma chamada à função JavaScript gadgets.window.adjustHeight() sempre que houver uma alteração de conteúdo ou ocorrer outro evento que exija o redimensionamento do gadget.

Por exemplo, veja abaixo a especificação do gadget de lista de compras:

<?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>

Para obter orientações sobre como testar a largura e a altura de um gadget, consulte Teste de largura e altura.

Definição do título do gadget

Use a função gadgets.window.setTitle() para definir o título do gadget programaticamente. Para usar esta função, seu gadget deve incluir:

  • Em <ModulePrefs>, uma tag <Require feature="settitle"/> para informar ao gadget que ele precisa carregar a biblioteca settitle.
  • Uma chamada a gadgets.window.setTitle() para definir o título do gadget.

Este exemplo fornece um campo de texto que permite que o usuário defina o título do gadget:

<?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>

Guias

Use a biblioteca de guias para adicionar uma interface de usuário com guias ao seu gadget. Para usar guias, a especificação do seu gadget deve incluir no mínimo:

  • Em <ModulePrefs>, um tag <Require feature="tabs"/> para informar ao gadget que ele precisa carregar a biblioteca tabs.
  • JavaScript para criar as guias e preenchê-las com conteúdo. Para obter mais detalhes, consulte Como funciona.

Também é comum incluir a biblioteca setprefs para que o gadget possa armazenar sempre a última guia selecionada pelo usuário. Assim, se o usuário sair e retornar à página, o gadget carrega a guia armazenada. Para aproveitar este recurso, incorpore duas linhas de código na especificação do seu gadget:

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

Anatomia de um objeto de guias

A biblioteca de guias fornece funções e CSS para realizar operações com os objetos abaixo:

  • Objeto TabSet. O objeto de guias é o recipiente-pai de todas as guias. Programaticamente, o objeto de guias é uma matriz de objetos de guia individuais. Normalmente, a implementação básica do HTML é um elemento <table>, mencionado na API como o ''header container'' (recipiente de cabeçalho). Use a função gadgets.TabSet.getHeaderContainer() para acessar este HTML.
  • Objeto de guia. Um objeto de guia é uma única guia dentro de uma matriz de guias indexadas. Normalmente, a implementação básica do HTML é um elemento <td>, mencionado na API como o ''name container'' (recipiente de nome). Use a função gadgets.Tab.getNameContainer() para acessar este HTML.
  • Recipiente de conteúdo. Um objeto de recipiente de conteúdo contém o conteúdo de um objeto de guia individual. Normalmente, a implementação básica do HTML é um elemento <div>, mencionado na API como o ''content container'' (recipiente de conteúdo). Use a função gadgets.Tab.getContentContainer() para acessar este HTML.

Como funciona

Use o construtor gadgets.TabSet() para criar um objeto de guias (ou seja, um objeto contendo um conjunto de guias indexadas). Por exemplo:

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

Depois de criar o objeto de guias, adicione as guias individuais a ele usando a função addTab(). Uma guia individual apresenta três componentes principais: um índice, um nome e um ID exclusivo que é igual ao ID de um <div> correspondente. O <div> é o local onde o conteúdo da guia é colocado. Se você não fornecer o recipiente de <div>, a biblioteca de guias irá gerá-lo.

O método addTab() utiliza os seguintes argumentos:

  • String tabName -- Marcador da guia a ser criada.
  • Object opt_params -- Objeto de parâmetro opcional. Ele pode incluir:
    • contentContainer --Um elemento HTML existente para ser usado como recipiente do conteúdo da guia. Se omitido, a biblioteca de guias cria um elemento.
    • callback --função mA callback a ser executada quando a guia é selecionada.
    • tooltip-- Uma descrição de dica de ferramenta que aparece quando o usuário move o cursor do mouse sobre a guia.
    • index -- É o índice no qual a guia será inserida. Se omitido, a nova guia é anexada no final.

addTab() retorna uma string contendo o ID do DOM do recipiente da guia.

Você pode adicionar uma guia a um objeto de guias e preenchê-la com conteúdo usando uma das maneiras descritas abaixo:

Técnica 1: Capture o ID da guia ao criá-la e use o ID para adicionar conteúdo ao <div> correspondente da guia:

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

Uma variação desta abordagem é definir o nome da guia em HTML. Por exemplo:

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.";

Técnica 2: Crie a guia e adicione um <div> correspondente à parte HTML do gadget; coloque o conteúdo estático no <div>:

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

Técnica 3: Crie a guia e adicione um <div> correspondente à parte HTML do gadget; coloque o conteúdo estático no <div>: Use uma função de retorno de chamada para adicionar conteúdo dinâmico ao conteúdo estático:

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>

Técnica 4: Use a função addTab(tabName, opt_params) para adicionar uma guia por nome. Por exemplo:

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

}); 

Aqui está um exemplo de gadget que mostra as maneiras diferentes de adicionar guias e preenchê-las com conteúdo:

<?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>

Manipulação de guias por índice

A API de guias também inclui funções que permitem a manipulação das guias por índice. As guias são indexadas de 0 a n, onde 0 é a primeira guia. Por exemplo, se houver 3 guias, os índices são 0, 1 e 2. Você pode usar os índices para selecionar uma guia programaticamente e para trocar a posição de duas guias.

Embora o ID de uma guia permaneça constante, o mesmo não ocorre com seu índice. Por exemplo, se você mover a terceira guia para a primeira posição, o índice é alterado de 2 para 0.

Aqui está um exemplo de como selecionar uma guia programaticamente. Este snippet cria um link. Quando o usuário clica no link, a segunda guia é selecionada, como se o usuário tivesse clicado na própria guia:

<script>
...
function selectTab() {
tabs.setSelectedTab(1);
}
</script> <a href="javascript:void(0)" onclick="selectTab()">Select Second Tab</a>

Aqui está um exemplo de como mover uma guia programaticamente. Este snippet cria um link. Quando o usuário clica no link, o gadget troca as posições da primeira e da segunda guia:

<script>
...
function switchTabs() {
tabs.swapTabs(0, 1);
} </script> <a href="javascript:void(0)" onclick="switchTabs()">Switch Tabs</a>

Personalização da exibição de guias

Esta seção descreve como você pode personalizar a aparência de suas guias usando CSS ou JavaScript.

Personalização de guias com CSS

O CSS das guias define as classes aplicadas aos elementos do HTML que compõem as guias.

Você pode usar as classes CSS abaixo para ignorar a configuração padrão e modificar a aparência das suas guias.

Classe CSS Descrição
.tablib_table Aplica-se à tabela HTML que contém as guias.
.tablib_selected Aplica-se à guia selecionada.
.tablib_unselected Aplica-se a todas as guias não selecionadas.
.tablib_spacerTab Aplica-se aos elementos de espaçamento entre cada guia.
.tablib_emptyTab Controla os espaçamentos de início e de fim em volta das guias.
.tablib_navContainer Aplica-se ao recipiente pai, que abrange todo o conteúdo relacionado às guias (ou seja, cabeçalhos de guia e todos os recipientes individuais de conteúdo).

Veja as classes CSS padrão e as configurações que podem ser adicionadas:

.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;
}

Por exemplo:

<![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...>

Você também pode usar JavaScript para aplicar estilos CSS ao recipiente de cabeçalho das guias. A função getHeaderContainer() retorna a tabela HTML das guias, que você pode modificar conforme desejar.

Por exemplo, este snippet altera o tamanho da fonte e adiciona margem no alto:

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

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

Você pode personalizar o estilo dos cabeçalhos de guias individuais, obtendo os elementos da guia individual e modificando suas propriedades. Veja um exemplo que torna o estilo da primeira guia exclusivo:

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

Alteração de alinhamento da guia

Por padrão, as guias são centralizadas ao serem adicionadas. Entretanto, se houver menos que 3 ou 4 guias, você pode alinhá-las à esquerda ou à direita. Para isso, use a função alignTabs(). Ela aceita um parâmetro com o valor left, right ou center. Se você for alinhar guias à esquerda ou à direita, há um parâmetro opcional que pode ser passado para indicar a largura do deslocamento em relação ao lado esquerdo ou direito. O tamanho padrão é 3px.

Por exemplo:

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

Como ocultar guias

Use a função displayTabs() para alternar a exibição das guias e de seu conteúdo. Esta função assume o valor booleano de true ou false.

Aqui está um exemplo que cria um botão que exibe ou oculta as guias:

<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>

MiniMessages

Uma MiniMessage é uma mensagem temporária exibida aos usuários dentro de um gadget. As MiniMessages foram criadas para serem eliminadas programaticamente ou pelo usuário. Os tipos básicos de MiniMessages são:

  • Mensagens dispensáveis que os usuários removem clicando em um [x].
  • Mensagens de temporizador que desaparecem depois de decorrido um determinado período de tempo em segundos.
  • Mensagens estáticas que devem ser dispensadas programaticamente.

Para usar MiniMessages, a especificação do seu gadget deve incluir:

  • Em <ModulePrefs>, uma tag <Require feature="minimessage"/> para informar ao gadget que ele precisa carregar a biblioteca de MiniMessages.
  • Funções JavaScript descrevendo o comportamento da MiniMessage. Consulte a Referência para obter uma lista completa das funções da biblioteca de MiniMessages.

Veja alguns dos motivos para usar MiniMessages:

  • Promoção: Você pode usar as MiniMessages para exibir uma mensagem promocional no gadget.
  • Status: Muitos gadgets obtêm e carregam dados em segundo plano. Você pode usar MiniMessages para exibir ''Carregando...'' ou outras mensagens relacionadas a status.
  • Depuração/erro: Se um gadget encontrar um erro, ele pode usar as MiniMessages para notificar o usuário, em vez de falhar em silêncio.
  • Outros: Dependendo do tipo de gadget (por exemplo, calendário, eBay), você pode exibir notificações para os usuários. Como as MiniMessages são pequenas e dispensáveis, use-as para comunicar informações especiais.

Como funciona

As etapas básicas da adição de uma MiniMessage ao gadget são simples:

1. Importe a biblioteca de MiniMessages:

<Require feature="minimessage"/>

2. Crie uma instância de um novo objeto de MiniMessage usando o construtor gadgets.MiniMessage():

var msg = new gadgets.MiniMessage(__MODULE_ID__);

Na maioria dos casos, você criará um único objeto global que possa ser acessado por todos os escopos.

3. Crie uma nova MiniMessage com um texto:

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

Isso adiciona no início do gadget uma mensagem pré-formatada dispensável com um [x] associado a ela. Quando os usuários clicam no [x], a mensagem é fechada.

Pronto! Você criou um dos diversos tipos de mensagens dispensáveis.

Criação de mensagens em locais diferentes

Por padrão, as mensagens são colocadas dentro de um elemento de recipiente de HTML bem no início do gadget. Cada mensagem subseqüente é anexada como filha ao recipiente, em ordem decrescente. Entretanto, você pode modificar esse comportamento para todas as mensagens ou para uma única mensagem.

Definição de um local para todas as mensagens

Você pode passar um elemento HTML ao construtor, de preferência um <div>, para ignorar a localização padrão do elemento de recipiente da mensagem. Esse elemento torna-se o recipiente no qual as mensagens serão inseridas e exibidas.

Por exemplo, neste snippet a mensagem <h3> "Estou no topo agora!" aparece no início do gadget. As MiniMessages são exibidas abaixo dela em messageBox <div>, na ordem em que foram adicionadas.

<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>

Definição de um local para uma única mensagem

Você pode criar uma mensagem dispensável em uma localização designada em vez de anexá-la ao recipiente da mensagem. Para isso, faça o markup da mensagem dentro da parte HTML do gadget. Em seguida, passe o elemento HTML (de preferência um <div>) como o primeiro parâmetro a createDismissibleMessage().

Por exemplo, neste snippet, a mensagem é exibida dentro do 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>

Criação de mensagens usando métodos DOM

Pode haver casos em que você irá gerar a mensagem dispensável usando métodos HTML DOM. Como a mensagem não existe no DOM, ela é anexada ao recipiente de mensagens por padrão.

Por exemplo:

<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>

Criação de uma mensagem de temporizador

Uma mensagem de temporizador é pré-formatada para desaparecer depois de decorrido o período de tempo especificado. A função createTimerMessage() aceita dois parâmetros: uma string de mensagem e um número indicando a duração, em segundos, da exibição da mensagem. Por exemplo:

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

Criação de uma mensagem estática

Uma mensagem estática é pré-formatada para ser exibida até ser dispensada programaticamente pela função dismissMessage(). Isso é útil para exibir mensagens de notificação que mantenham o usuário informado durante a execução de tarefas do gadget em segundo plano, como a obtenção de conteúdo. Por exemplo:

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

Personalização da exibição de MiniMessages

Há duas maneiras de se alterar a aparência padrão de MiniMessages:

  • Altere a aparência das mensagens individuais.
  • Altere a aparência de todas as mensagens de forma global.

Alteração do estilo de mensagens individuais

Use funções DOM para alterar o estilo de uma mensagem. Um elemento HTML é retornado quando você cria uma nova mensagem dispensável. Você pode modificar a aparência da mensagem configurando as propriedades de estilo desse elemento HTML retornado. Por exemplo:

<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>

Observação: Este exemplo mostra a forma correta de alterar totalmente a cor de fundo de uma mensagem. A cor de fundo não será totalmente alterada se apenas a configuração da cor de fundo do <div> que contém a mensagem for alterada.

Alteração do estilo de todas as mensagens

Use CSS globalmente para alterar o estilo de todas as mensagens. O CSS define as classes aplicadas aos elementos de HTML que definem as MiniMessages.

Você pode usar as classes CSS abaixo para ignorar a configuração padrão e modificar a aparência de suas mensagens.

Classe CSS Descrição
.mmlib_table Aplicável à tabela HTML que contém a mensagem.
.mmlib_xlink Aplicável ao link [x] usado para dispensar uma mensagem. A configuração se aplica somente à mensagem dispensável.

Por exemplo, isto altera a cor de fundo para azul marinho e a cor principal para branco:

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

Veja as classes CSS padrão e as configurações que podem ser adicionadas:

.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

Use a biblioteca flash para incorporar um filme Flash (especificamente, um arquivo .swf) em seu gadget. Para incorporar conteúdo Flash, a especificação do seu gadget deve incluir no mínimo:

  • Em <ModulePrefs>, uma tag <Require feature="flash"/> para informar ao gadget que ele precisa carregar a biblioteca flash.
  • Uma chamada a gadgets.flash.embedFlash() para incorporar um arquivo .swf no gadget e exibi-lo em um local designado. Para usar esse recurso, todos os recursos devem estar em um único arquivo .swf.

A biblioteca flash inclui as seguintes funções:

Função Descrição
gadgets.flash.embedFlash(swf_url, swf_container, swfVersion, opt_params)

Incorpora o arquivo .swf especificado por swf_url e o exibe no gadget no local especificado por swf_container. O parâmetro opt_params é um objeto opcional que pode conter qualquer parâmetro html válido.

Rretorna true se for bem-sucedido, ou false se falhar.

Observação: Se ocorrerem problemas de desempenho ou se o gadget não for exibido (esse problema ocorre às vezes no Firefox 2.0), tente configurar wmode expressamente como "window", conforme mostrado abaixo: gadgets.flash.embedFlash("example.swf", "wrapper", {wmode: "window"});

gadgets.flash.embedCachedFlash(swf_url, swf_container, swfVersion, opt_params) Injeta um arquivo Flash com cache na árvore DOM. Os parâmetros e o valor retornado são os mesmos do método embedFlash().
gadgets.flash.getMajorVersion() Retorna a principal versão do Flash Player, ou zero se o Flash Player não for detectado.

Exemplo de Flash

Quando você clica em algum botão deste exemplo de gadget, ele reproduz o arquivo .swf correspondente. Quando você clica em Stop, o gadget exibe uma fotografia estática.

Aqui está a especificação do gadget do exemplo:

<?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>

Voltar ao início