Creación de una interfaz de usuario

En este documento se describe cómo añadir distintos elementos de interfaz de usuario a un gadget.

Contenido

  1. Vistas
    1. Inclusión de varias secciones de contenido
    2. Concatenación de vistas
    3. Determinación de la vista de gadget actual
    4. Obtención de todas las vistas disponibles
    5. Desplazamiento a otra vista
    6. Transmisión de datos con requestNavigateTo()
  2. Administración de la altura de un gadget
  3. Definición del título de un gadget
  4. Pestañas
    1. Anatomía de un objeto "Tabs"
    2. Funcionamiento
    3. Manipulación de las fichas mediante un índice
    4. Personalización del aspecto de las fichas
  5. MiniMessages
    1. Funcionamiento
    2. Creación de mensajes en distintas ubicaciones
    3. Creación de mensajes con métodos DOM
    4. Creación de un mensaje de temporizador
    5. Creación de un mensaje estático
    6. Personalización del aspecto de MiniMessages
  6. Flash
    1. Ejemplo de Flash

Vistas

Una vista es la ubicación en un contenedor donde se muestra un gadget. Las vistas tienen características diferentes según su tipo. Por ejemplo, un contenedor podría tener una vista que mostrase gadgets en formato reducido y una vista que mostrase gadgets en formato de página completa. Para obtener una lista de las vistas compatibles con tu contenedor, consulta la documentación del mismo.

Por ejemplo, los gadgets de la zona de pruebas de iGoogle se muestran en modo de vista principal ("modo de tamaño reducido"), lo que significa que aparecen con un diseño de columna entre otros gadgets. Para crear una vista ampliada ("modo de tamaño grande") de tu gadget en la que el gadget se expanda horizontalmente para ocupar toda el área de gadgets, debes definir una sección <Content> para el tipo de vista "ampliada" del siguiente modo:

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

Supongamos que defines una sección <Content> para la vista ampliada de un gadget orientado a iGoogle. A continuación, deberás crear también una sección <Content> para que el gadget se muestre correctamente en la vista principal. Puede ser "predeterminada" o "principal". Para obtener más información sobre la creación de gadgets que admitan varias secciones <Content>, consulta la sección Inclusión de varias secciones de contenido.

A continuación se muestra una versión del gadget "Hello World" que define vistas de sección <Content> para "principal" y "ampliada". Su ancho cambia en función de si se muestra en la vista principal o en la vista ampliada.

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

Inclusión de varias secciones de contenido

Puedes incluir más de una sección <Content> en un archivo XML de gadget. Cada sección <Content> indicará las vistas en las que deberá aparecer. Todas las secciones <Content> deberán encontrarse en el mismo nivel en el árbol del documento y podrán utilizar el parámetro opcional view= para definir las vistas en las que deben aparecer.

Dos secciones de contenido

A continuación se muestra un sencillo ejemplo en el que aparece un gadget con dos secciones de contenido, una para "perfil" y otra para "vista ampliada". Estas son las vistas que admite el contenedor 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>

El resultado sería el siguiente:

Vista de perfil

<h1>Profile</h1>

Vista ampliada

<h1>Canvas</h1>

Cualquier otra vista

no se muestra ningún contenido

Secciones de contenido con especificación de varias vistas

Se pueden especificar varias vistas (separadas por comas) para las secciones de contenido:

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

El resultado sería el siguiente:

Vista de perfil

<h1>Canvas and Profile</h1>

Vista ampliada

<h1>Canvas and Profile</h1>

Cualquier otra vista

no se muestra ningún contenido

Sección de contenido con especificación de vista y ninguna sección de contenido predeterminada

Si especificas una sección de contenido con un parámetro de vista, esa sección de contenido sólo se mostrará en esa vista. Si no especificas ninguna sección de contenido predeterminada, no se mostrará ningún contenido en otras vistas.

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

El resultado sería el siguiente:

Vista de perfil

<h1>Profile</h1>

Vista ampliada

no se muestra ningún contenido

Cualquier otra vista

no se muestra ningún contenido

Sección de contenido con especificación de vista y una sección de contenido predeterminada

Para especificar una sección de contenido predeterminada, sólo tienes que definir una sección de contenido sin ningún parámetro de vista:

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

El resultado sería el siguiente:

Vista de perfil

<h1>Profile</h1>

Vista ampliada

<h1>Default</h1>

Cualquier otra vista

<h1>Default</h1>

Ejemplo completo

Puedes utilizar todas estas técnicas en un solo 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>

El resultado sería el siguiente:

Vista de perfil

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

Vista ampliada

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

Cualquier otra vista

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

Concatenación de vistas

Las vistas son compatibles con todos los contenedores de OpenSocial, pero cada contenedor puede admitir un conjunto de vistas diferente. Por ejemplo, iGoogle tiene una vista en un área pequeña llamada home, pero la vista en área pequeña de orkut se llama profile.

Supongamos que deseas crear un gadget que tenga la misma presentación para home en iGoogle y profile en orkut. En lugar de crear secciones <Content> duplicadas, podrías concatenar las vistas de una única sección <Content> del siguiente modo:

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

Puedes utilizar esta técnica en varios contenedores o dentro de un mismo contenedor. Por ejemplo, los gadgets que gestionan la lógica de presentación para vistas con diferentes tamaños en una única sección <Content> pueden ampliar su compatibilidad a la página ampliada mediante la declaración de view="home,canvas".

Determinación de la vista de gadget actual

La forma más sencilla de obtener la vista actual es incluir la función de "vistas" en las preferencias del módulo de gadget:

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

Si incluyes la función de vistas, podrás obtener la vista actual mediante la ejecución de la función gadget.util.getCurrentView().

En el siguiente ejemplo se muestra cómo obtener la vista actual y ejecutar código de forma condicional con el valor obtenido:

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

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

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

Obtención de todas las vistas disponibles

Para obtener los objetos View disponibles, ejecuta la función gadgets.views.getSupportedViews().

var supported_views = gadgets.views.getSupportedViews();
    

El objeto devuelto por la llamada getSupportedViews contiene objetos gadgets.views.View que representan todas las vistas disponibles en iGoogle, clasificadas por nombre de vista.

Si deseas proporcionar enlaces a otras vistas, debes incluir un objeto gadgets.views.View en el método gadgets.views.requestNavigateTo(). Puedes utilizar uno de los objetos devueltos por la llamada getSupportedViews(). Este método se muestra en el siguiente código de ejemplo:

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

Una forma alternativa es crear un nuevo objeto View de forma manual y, a continuación, utilizarlo para iniciar la navegación. En el código siguiente se muestra cómo crear un nuevo objeto gadgets.views.View e incluirlo en el 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);
  };
    

Este es un ejemplo completo basado en el 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>

    

Transmisión de datos con requestNavigateTo()

Si estás utilizando las llamadas gadgets.views.requestNavigateTo(), puedes utilizar un parámetro opcional con los datos que quieres incluir en tu nueva página.

El código siguiente incluye dos variables: foo y bar en la superficie ampliada del gadget actual:

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

En la vista ampliada, comprueba estos valores con el siguiente código:

  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>
    

Administración de la altura de un gadget

De forma predeterminada, la altura de los gadgets es 200 píxeles. Puedes usar el atributo <ModulePrefs> height="nn" para especificar una altura estática mayor o menor que la predeterminada. También puedes usar el atributo <ModulePrefs> scrolling="true" para incorporar una barra de desplazamiento vertical a tu gadget, en caso de que la altura del contenido provoque que el gadget sobrepase la altura establecida.

Sin embargo, algunos gadgets requieren que las modificaciones relacionadas con su altura se realicen de forma dinámica. Por ejemplo, imaginemos que tienes un gadget tipo lista cuya altura debería ampliarse o reducirse en función del contenido de dicha lista. A medida que los usuarios añadieran elementos a la lista, el tamaño del gadget debería aumentar. Al borrar elementos de la lista, el gadget regresaría a su altura original. A continuación se muestra un posible formato para un gadget en ejecución:

Gadget de lista de la compra

Para que tu gadget pueda cambiar su tamaño automáticamente, es necesario incorporar lo siguiente en su especificación:

  • Una etiqueta <Require feature="dynamic-height"/> (en <ModulePrefs>) que indique al gadget que debe cargar la biblioteca dynamic-height.
  • Una llamada a la función JavaScript gadgets.window.adjustHeight() siempre que se produzca alguna modificación en el contenido o bien ocurra algo que requiera cambios en el tamaño del gadget.

Por ejemplo, aquí tenemos la especificación del gadget de la lista de la compra:

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

Si deseas obtener instrucciones para realizar pruebas en la altura y anchura de un gadget, consulta Pruebas de altura y ancho.

Definición del título de un gadget

Puedes usar la función gadgets.window.setTitle() para definir de forma automática el título de tu gadget. Para utilizar esta función, la especificación de tu gadget debe incluir lo siguiente:

  • En <ModulePrefs>, una etiqueta <Require feature="settitle"/> que indique al que debe cargar la biblioteca settitle.
  • Una llamada a gadgets.window.setTitle() para definir el título del gadget.

En este ejemplo se proporciona un campo de texto que permite al usuario definir el título del 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>

Fichas

Puedes usar la biblioteca de fichas para añadir una interfaz de usuario con fichas a tu gadget. Para utilizar fichas, la especificación de tu gadget debe incluir como mínimo lo siguiente:

  • En <ModulePrefs>, una etiqueta <Require feature="tabs"/> que indique al que debe cargar la biblioteca tabs.
  • JavaScript para crear tus fichas e introducir contenido en ellas. Para obtener información más detallada, consulta Funcionamiento.

También es habitual incluir la biblioteca setprefs, de modo que el gadget pueda guardar de forma continuada la última ficha seleccionada por el usuario. De este modo, si el usuario abandona la página y regresa posteriormente a ella, el gadget cargará la ficha memorizada. Para utilizar esta función, debes añadir dos líneas de código en la especificación del gadget:

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

Anatomía de un objeto "Tabs"

La biblioteca de fichas proporciona funciones y CSS para trabajar en los siguientes objetos:

  • Objeto "TabSet". El objeto "Tabs" es el contenedor principal de todas las demás fichas. De forma automática, el objeto "Tabs" es un conjunto de objetos "Tab" individuales. La implementación HTML subyacente es, por lo general, un elemento <table>, al que se hace referencia en el API como "contenedor de encabezados".Para acceder a este código HTML, debes utilizar la función gadgets.TabSet.getHeaderContainer().
  • Objeto "Tab". Un objeto "Tab" es una ficha única de un conjunto de fichas indexadas. La implementación HTML subyacente es, por lo general, un elemento <td>, al que se hace referencia en el API como "contenedor de contenido".Para acceder a este código HTML, debes utilizar la función gadgets.Tab.getNameContainer().
  • Contenedor de contenido. En un contenedor de contenido se almacena el contenido de un objeto "Tab" individual. La implementación HTML subyacente es, por lo general, un elemento <div>, al que se hace referencia en el API como "contenedor de contenido".Para acceder a este código HTML, debes utilizar la función gadgets.Tab.getContentContainer().

Funcionamiento

Para crear un objeto "Tabs" (es decir, un objeto que contenga un conjunto de fichas indexadas), debes usar el constructor gadgets.TabSet(). Por ejemplo:

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

Una vez creado el objeto "Tabs", podrás añadirle fichas individuales con la función addTab(). Una ficha individual tiene tres componentes principales: un índice, un nombre y una ID única que coincide con la ID del <div> correspondiente. <div> es el lugar en el que se coloca el contenido de la ficha. Si no proporcionas ningún contenedor <div>, la biblioteca de fichas generará uno por ti.

El método addTab() utiliza los siguientes argumentos:

  • String tabName -- Etiqueta de la ficha que se creará.
  • Object opt_params -- Objeto de parámetro opcional. Puede incluir lo siguiente:
    • contentContainer --Un elemento HTML existente que se utilizará como el contenedor de contenido de la ficha. Si se omite, la biblioteca de fichas creará uno.
    • callback --Una función de devolución de llamada que se ejecutará cuando se seleccione la ficha.
    • tooltip-- Una descripción informativa que aparece cuando el usuario mueve el cursor del ratón sobre la ficha.
    • index -- El índice en el que se debe insertar la ficha. Si se omite, la nueva ficha se añadirá al final.

addTab() devuelve una cadena que contiene la ID DOM del contenedor de fichas.

Puedes añadir una ficha al objeto "Tabs" e introducir contenido en ella con cualquier de los métodos detallados a continuación:

Técnica 1: captura la ID de la ficha durante su creación y utilízalo para añadir contenido al <div> correspondiente de dicha ficha:

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

Una variación de este método consiste en definir el nombre de la ficha en HTML. Por ejemplo:

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: crea la ficha y añade el <div> correspondiente a la sección HTML del gadget y coloca el contenido estático en el <div>:

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

Técnica 3: crea la ficha y añade el <div> correspondiente a la sección HTML del gadget y coloca el contenido estático en el <div>. Utiliza una función de llamada para añadir contenido dinámico al contenido 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: utiliza la función addTab(tabName, opt_params) para añadir una ficha por nombre. Por ejemplo:

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

}); 

A continuación se ofrece un gadget de ejemplo que incluye distintas formas para añadir fichas e introducir contenido en ellas:

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

Manipulación de las fichas mediante un índice

El API de fichas también incluye funciones que permiten manipular las fichas mediante un índice. Las fichas se indexan de 0 a n, siendo 0 la primera ficha. Por ejemplo, si tienes 3 fichas, sus índices serán 0, 1 y 2. Los índices son útiles para seleccionar fichas de forma automática o para cambiar la colocación de dos fichas.

Ten en cuenta que aunque la ID de una ficha permanece constante, su índice sí es variable. Si desplazas la tercera ficha hasta la primera posición, por ejemplo, su índice cambiará de 2 a 0.

En el ejemplo que se ofrece a continuación se muestra cómo seleccionar una ficha de forma automática. Este fragmento crea un enlace. Si un usuario hace clic en el enlace, la segunda ficha se selecciona, como si dicho usuario hubiera hecho clic en la ficha propiamente dicha:

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

En el ejemplo que se ofrece a continuación se muestra cómo mover una ficha de forma automática. Este fragmento crea un enlace. Si un usuario hace clic en el enlace, el gadget cambiará las posiciones de la primera y la segunda ficha:

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

Personalización del aspecto de las fichas

En esta sección se describe cómo se puede personalizar el aspecto de las fichas con CSS o JavaScript.

Personalización de fichas con CSS

En la clase CSS de las fichas se definen las clases que se aplican a los elementos HTML que conforman las fichas.

Puedes usar las siguientes clases CSS para anular la configuración predeterminada y modificar el aspecto de tus fichas.

Clase CSS Descripción
.tablib_table Se aplica a la tabla HTML que contiene las fichas.
.tablib_selected Se aplica a la ficha seleccionada.
.tablib_unselected Se aplica a todas las fichas no seleccionadas.
.tablib_spacerTab Se aplica a los elementos que actúan de espaciadores entre las fichas.
.tablib_emptyTab Controla el elemento espaciador inicial y final de las fichas.
.tablib_navContainer Se aplica al contenedor principal, que contiene todo el contenido relacionado con las fichas (es decir, los encabezados de fichas y todos los contenedores de contenido individuales).

A continuación se muestra la configuración y las clases CSS predeterminadas que puedes anular:

.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 ejemplo:

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

También puedes usar JavaScript para aplicar estilos CSS al contenedor principal de las fichas. La función getHeaderContainer() devuelve la tabla HTML de fichas, que podrás modificar como desees.

Por ejemplo, este fragmento cambia el tamaño de fuente y añade un poco de margen a la parte superior:

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

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

Para personalizar el estilo de los encabezados de ficha individuales, accede a los elementos de ficha individuales y modifica sus propiedades. A continuación te ofrecemos un ejemplo que hace el estilo de la primera ficha diferente:

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

Modificación de la alineación de las fichas

De forma predeterminada, las fichas se centran a medida que se añaden. No obstante, si el número de fichas es inferior a 3 ó 4, es posible que desee alinearlas a la derecha o a la izquierda. Para ello, utiliza la función alignTabs(). Utiliza un parámetro con el valor left, right o center. Si vas a alinear las fichas a la izquierda o a la derecha, existe un parámetro opcional adicional que puedes incluir para indicar el ancho del espacio que debe existir con respecto al lado izquierdo o derecho; el tamaño predeterminado es 3 píxeles.

Por ejemplo:

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

Cómo ocultar fichas

Puedes usar la función displayTabs() para mostrar u ocultar las fichas y su contenido. Esta función tiene un valor booleano de true o false.

A continuación se muestra un ejemplo de cómo crear un botón para mostrar u ocultar las fichas:

<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

Un MiniMessage es un mensaje temporal que se muestra a los usuarios desde un gadget. Los MiniMessages están diseñados para ser descartados, ya sea de forma automática o por acción directa del usuario Los tipos básicos MiniMessages son los siguientes:

  • Mensajes descartables que los usuarios pueden eliminar haciendo clic en una [x].
  • Mensajes de temporizador que desaparecen una vez ha transcurrido un determinado número de segundos.
  • Mensajes estáticos que se deben descartar de forma automática.

Para utilizar MiniMessages, la especificación de tu gadget debe incluir como mínimo lo siguiente:

  • En <ModulePrefs>, una etiqueta <Require feature="minimessage"/> que indique al gadget que debe cargar la biblioteca de MiniMessages.
  • Las funciones JavaScript encargadas de describir el comportamiento de los MiniMessages. Para obtener una lista completa de las funciones de la biblioteca de MiniMessages, consulta la referencia.

El uso de MiniMessages puede resultar de tu interés en las siguientes situaciones:

  • Promoción: puedes utilizar un MiniMessages para mostrar un mensaje promocional en tu gadget.
  • Estado: muchos gadgets recopilan y cargan datos en segundo plano. Puedes utilizar un MiniMessage en el que aparezca el texto "Cargando..." u otros textos relacionados con el estado.
  • Depuración/Error: si se produce un error en un gadget, puedes utilizar un MiniMessage para notificárselo al usuario, en lugar de dejar a éste sin información durante el error.
  • Otros: en función del tipo de gadget (por ejemplo, un calendario, eBay), puede resultar útil mostrar notificaciones a los usuarios. Dado el carácter reducido y descartable de los MiniMessages, resultan ideales para comunicar información especial.

Funcionamiento

Los pasos básicos para añadir un MiniMessage a tu gadget son sencillos:

1. Importar la biblioteca de MiniMessages:

<Require feature="minimessage"/>

2. Crear un nuevo objeto "MiniMessage" con el constructor gadgets.MiniMessage():

var msg = new gadgets.MiniMessage(__MODULE_ID__);

En la mayoría de ocasiones, lo mejor es crear un único objeto global al que se pueda acceder desde todos los ámbitos.

3. Crear un MiniMessage nuevo con algo de texto:

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

Esto hará aparecer un mensaje con formato previo y descartable con una [x] asociada en la parte superior de tu gadget. Cuando el usuario haga clic en la [x], el mensaje se cerrará.

Has terminado. Ya has creado uno de los muchos tipos de mensajes descartables posibles.

Creación de mensajes en distintas ubicaciones

De forma predeterminada, los mensajes se colocan en un elemento HTML que actúa de contenedor situado en la parte superior del gadget. Los mensajes sucesivos se incorporan al mismo contenedor como elementos secundarios y en orden descendente. Sin embargo, este comportamiento se puede modificar para un mensaje o para todos ellos.

Configuración de una ubicación para todos los mensajes

Puedes anular la ubicación predeterminada del elemento contenedor de mensajes. Para ello, deberás transmitir un elemento HTML al constructor, preferiblemente un <div>. Este elemento se convertirá en el contenedor de mensajes, donde éstos se insertarán y donde aparecerán.

Por ejemplo, en este fragmento, el mensaje <h3> "Ocupo el primer puesto"aparece en la parte superior del gadget. Los MiniMessages aparecen debajo en el messageBox <div>, en el orden en el que se han ido incorporando los mensajes.

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

Configuración de una ubicación para un único mensaje

Puedes crear un mensaje descartable en una ubicación específica, en lugar de incorporarlo al contenedor de mensajes. Para ello, marca el mensaje en la sección HTML del gadget y transmite el elemento HTML (preferiblemente un <div>) como primer parámetro a createDismissibleMessage().

Por ejemplo, en este fragmento, el mensaje aparece dentro del 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>

Creación de mensajes con métodos DOM

En determinadas ocasiones, quizá te interese generar mensajes descartables con métodos DOM HTML. Dado que dichos mensajes no existen en DOM, se añadirán de forma predeterminada al contenedor de mensajes.

Por ejemplo:

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

Creación de un mensaje de temporizador

Un mensaje de temporizador es un mensaje con formato previo que desaparece una vez ha transcurrido un determinado número de segundos. La función createTimerMessage() utiliza dos parámetros: una cadena de mensaje, y un número que indica durante cuantos segundos se debe mostrar dicho mensaje. Por ejemplo:

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

Creación de un mensaje estático

Un mensaje estático es un mensaje con formato previo que aparece hasta que la función dismissMessage() lo descarta de forma automática. Esto es especialmente útil para mostrar mensajes de notificación que informen al usuario de las tareas que el gadget está ejecutando en segundo plano como, por ejemplo, la recopilación de contenido. Por ejemplo:

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

Personalización del aspecto de MiniMessages

Existen dos métodos distintos para modificar el aspecto predeterminado de los MiniMessages:

  • cambiar el aspecto de mensajes individuales.
  • cambiar de forma general el aspecto de todos los mensajes.

Cambio del estilo de mensajes concretos

Para modificar el estilo de un mensaje debes utilizar las funciones DOM. Al crear un nuevo mensaje descartable, se devuelve un elemento HTML. Para modificar el aspecto de un mensaje, puedes configurar las propiedades de estilo del elemento HTML devuelto. Por ejemplo:

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

Nota: ten en cuenta que este ejemplo muestra el procedimiento correcto para modificar el color de fondo de un mensaje. El hecho de configurar el color de fondo del elemento <div> que contiene el mensaje no es suficiente para modificar íntegramente el color de fondo.

Cambio del estilo de todos los mensajes

Para cambiar el estilo de todos los mensajes debes utilizar CSS. En la clase CSS se definen las clases que se aplican a los elementos HTML que definen los MiniMessages.

Puedes usar las siguientes clases CSS para anular la configuración predeterminada y modificar el aspecto de tus mensajes.

Clase CSS Descripción
.mmlib_table Se aplica a la tabla HTML que contiene los mensajes.
.mmlib_xlink Se aplica al enlace [x] usado para descartar un mensaje. La configuración sólo se aplica a un mensaje descartable.

Por ejemplo, la siguiente acción cambia el fondo a azul marino y los elementos en primer plano a blanco:

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

A continuación se muestra la configuración y las clases CSS predeterminadas que puedes anular:

.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

Puedes utilizar la biblioteca flash para insertar un vídeo Flash (concretamente, un archivo .swf) en tu gadget. Para insertar contenido Flash, la especificación de tu gadget debe incluir como mínimo lo siguiente:

  • En <ModulePrefs>, una etiqueta <Require feature="flash"/> que indique al que debe cargar la biblioteca flash.
  • Una llamada a gadgets.flash.embedFlash() para insertar un archivo .swf en tu gadget y que aparezca en una ubicación específica. Ten en cuenta que al usar esta función, todos los recursos se deben agrupar en un archivo .swf.

La biblioteca flash incluye las siguientes funciones:

Función Descripción
gadgets.flash.embedFlash(swf_url, swf_container, swfVersion, opt_params)

Inserta el archivo .swf especificado por swf_url, y lo muestra en el gadget en la ubicación especificada por swf_container. El parámetro opt_params es un objeto opcional que puede contener cualquier parámetro html válido.

Rdevuelve true si es correcto, y false, si no lo es.

Nota: si tienes problemas de rendimiento o si el símbolo de intercalación no aparece (en ocasiones un problema de Firefox 2.0), intenta establecer expresamente wmode en "window", del siguiente modo: gadgets.flash.embedFlash("example.swf", "wrapper", {wmode: "window"});

gadgets.flash.embedCachedFlash(swf_url, swf_container, swfVersion, opt_params) Introduce un archivo Flash almacenado en caché en el árbol DOM. Los parámetros y el valor de retorno son iguales que en el método embedFlash().
gadgets.flash.getMajorVersion() Devuelve la versión principal del reproductor Flash o cero si no se detecta éste.

Ejemplo de Flash

Al hacer clic en uno de los botones de este gadget de ejemplo, aparecerá el archivo .swf correspondiente. Al hacer clic en Stop, el gadget aparecerá como una foto fija.

A continuación te ofrecemos la especificación del gadget del ejemplo:

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

Volver al principio