Creación de gadgets propios

La sección Introducción ofrece una descripción general de los gadgets. El paso siguiente consiste en crear tus propios gadgets. Este documento te explica cómo hacerlo.

Contenido

  1. Pasos básicos
  2. Anatomía de un gadget
    1. Definición de contenido
    2. Definición de las preferencias del usuario
    3. Definición de las preferencias del gadget
  3. Recuerda: los gadgets son públicos
  4. Más información

Pasos básicos

A continuación se describen los pasos básicos que debes seguir para crear e instalar un gadget:

  1. Utiliza un editor de textos para escribir la especificación del gadget y guárdala en un servidor web público.
  2. Añade tu gadget a un contenedor como, por ejemplo, iGoogle u orkut. Un contenedor es una aplicación o un sitio que puede ejecutar gadgets.

Anatomía de un gadget

Si ya entiendes cómo editar y publicar gadgets, estás listo para incluir funciones más avanzadas en tus especificaciones de gadget. La especificación de gadget XML consta de 3 partes principales:

  • Sección de contenido. En la sección <Content> se desarrolla el trabajo real del gadget. En esta sección se especifica el tipo de gadget, la lógica de programación y, a menudo, los elementos HTML que determinan su aspecto y diseño.
  • Preferencias del usuario. En la sección <UserPrefs> se definen los controles que permiten a los usuarios especificar valores para el gadget. Por ejemplo, un gadget de saludo personalizado puede incluir un campo de texto para que los usuarios especifiquen sus nombres.
  • Preferencias del gadget. En la sección <ModulePrefs> del archivo XML se especifican las características del gadget como, por ejemplo, el título, el autor, el tamaño preferido, etc.

Nota: en los atributos XML de un gadget, es necesario aplicar formato de escape (es decir, una codificación correcta) a determinados caracteres para que se interpreten correctamente. Para obtener más información, consulta Caracteres especiales de escape.

Cuando desees crear un gadget, deberás comenzar por la sección <Content>.

Definición de contenido

La sección <Content> representa el "cerebro" de un gadget. La sección <Content> define el tipo de contenido, e incluye el contenido o un enlace a contenido externo. En la sección <Content> se combinan los atributos del gadget y las preferencias del usuario con la lógica de programación y la información de formato para generar un gadget funcional.

La forma más sencilla de crear un gadget es utilizar HTML (y, opcionalmente, JavaScript o Flash) en la sección<Content>. Los programadores web expertos pueden consultar otras opciones relacionadas con el control de acceso, el alojamiento remoto y el uso de lenguajes de secuencias de comandos alternativos, entre otros temas, en la sección Elección de un tipo de contenido. A continuación se muestra un sencillo gadget de ejemplo. Este gadget muestra una fotografía en la que se puede hacer clic para abrir un álbum de fotografías en una página HTML nueva:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
  <Content type="html">
  <![CDATA[ 
    <div style="text-align:center"><a
      id="Riggs" title="My Photo Album" target="_blank" 
      href="http://picasaweb.google.com/doc.examples/ShelfBoy">
<img border="0" alt="Photo" src="http://doc.examples.googlepages.com/Riggsie-OP.jpg"
title="Click Here."></a>
</div> ]]> </Content> </Module>

Definición de las preferencias del usuario

Algunos gadgets deben ofrecer a los usuarios un método para proporcionar información específica del usuario. Por ejemplo, es posible que un gadget de juegos permita a los usuarios introducir un nivel de dificultad preferido. En la sección de preferencias del usuario (<UserPref>) del archivo XML se describen los campos de introducción de datos para el usuario que se convierten en controles de interfaz de usuario al ejecutar el gadget. Las preferencias del usuario se guardan de forma persistente.

Por ejemplo, este gadget muestra un saludo personal basado en la hora del día. Permite a los usuarios especificar lo siguiente:

  • El nombre que se utilizará en el saludo. Este nombre también aparecerá en la barra de título.
  • Un color de fondo.
  • Si se mostrará una fotografía.

Éste es el aspecto del gadget cuando el usuario hace clic en editar para modificar las preferencias del usuario:

Controles de preferencias del usuario

Las preferencias del usuario que se convierten en controles de interfaz de usuario al ejecutar el gadget se definen en la especificación XML como se muestra a continuación:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="250" />
<UserPref name="myname" display_name="Name" required="true" />
<UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
<UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
<UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" > <EnumValue value="Red" /> <EnumValue value="Aqua" /> <EnumValue value="Lime" /> <EnumValue value="Yellow" /> <EnumValue value="Pink" /> <EnumValue value="Orange" /> <EnumValue value="White" /> </UserPref>

Observa lo siguiente:

  • La línea 3 del archivo contiene el texto title="Preferences for __UP_myname__". Al ejecutar el gadget, el valor proporcionado para la preferencia del usuario myname sustituye de forma dinámica a __UP_myname__.
  • La preferencia del usuario myname se ha marcado como "required", es decir, obligatoria.Si el usuario intenta ejecutar el gadget sin proporcionar un valor para este campo, el cuadro de edición de las preferencias del usuario permanecerá abierto hasta que se proporcione un valor.
  • La preferencia del usuario mychoice presenta el tipo de datos bool. Esto se muestra en la interfaz de usuario en forma de casilla de verificación.
  • La preferencia del usuario mycolor presenta el tipo de datos enum. La lista de valores EnumValues especifica las opciones que aparecen en el menú desplegable del cuadro de edición de las preferencias del usuario.

A continuación se incluye el código correspondiente al gadget completo, incluido el código JavaScript que muestra el saludo del gadget:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="400"/> 
  <UserPref name="myname" display_name="Name" default_value="Rowan"/>
  <UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
  <UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
  <UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
    <EnumValue value="Red" />
     <EnumValue value="Aqua" />
     <EnumValue value="Lime" />
     <EnumValue value="Yellow" />
     <EnumValue value="Pink" />
     <EnumValue value="Orange" />
     <EnumValue value="White" />
   </UserPref>
   <Content type="html"><![CDATA[
   <div id="content_div"></div>
   <script type="text/javascript">
   // Get userprefs
   var prefs = new gadgets.Prefs();

   function displayGreeting () {
     // Get current time
     var today = new Date();
     var time = today.getTime();
     var html = "";
  
     // Based on the time of day, display an appropriate greeting
     var hour = today.getHours();
     var salutation = "Afternoon";
     if (hour < 12) {
       salutation = "Morning";
     } else if (hour > 17) {
       salutation = "Evening";
     }

     // Set the background color according to the mycolor userpref
     var element = document.getElementById('content_div');  
     element.style.height=250;
     // Set the background color according to the mycolor userpref   
     element.style.backgroundColor=prefs.getString("mycolor"); 

     // Display a greeting based on the myname userpref
     html += "<br><FONT SIZE=6>Good " + salutation + ", " +
           prefs.getString("myname") + "!!!<br><br></FONT>";

     // If the "Show Photo?" checkbox is checked, display photo.
     if (prefs.getBool("mychoice") == true) {
       html += '<img src="' + prefs.getString("myphoto") + '">';
     }
     element.innerHTML = html;
   }
   // Pass the userprefs for this module instance to the function
   // (allows users to include multiple module instances on their page)
   gadgets.util.registerOnLoadHandler(displayGreeting); 
  
   </script> 
   ]]>  
  </Content>
</Module>

Para obtener una lista completa de los atributos <UserPref>, consulta la sección Referencia.

Para acceder a las preferencias de usuario desde tu gadget, utiliza el API de JavaScript de preferencias del usuario, por ejemplo:

<script type="text/javascript">
  var prefs = new gadgets.Prefs();
  var someStringPref = prefs.getString("StringPrefName");
  var someIntPref = prefs.getInt("IntPrefName");
  var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Para obtener una lista completa de las funciones JavaScript, consulta la sección Referencia de JavaScript.

Variables de sustitución de preferencias del usuario

Puedes utilizar una variable de sustitución del formato __UP_userpref__ en las secciones <ModulePrefs> o <UserPref>, donde userpref coincida con el atributo name de una preferencia del usuario. Al ejecutar el gadget, el valor de cadena de la preferencia del usuario correspondiente sustituye a la variable, sin formato de escape. Por ejemplo, en el siguiente fragmento, el valor que el usuario proporciona en tiempo de ejecución para la preferencia del usuario projects sustituye a __UP_projects__ en la cadena title_url:

<Module>
  <ModulePrefs title="Build Monitor"
             title_url="http://www.example.com/build/status.php?__UP_projects__"/>
  <UserPref name="projects" display_name="project(s)"/>
  <Content ... />
</Module>

Puedes ver otro ejemplo en el ejemplo de preferencias del usuario.

A continuación se muestran las directrices generales para utilizar variables de sustitución de preferencias del usuario:

  • Para el atributo <ModulePrefs> title, utiliza __UP_name__ . Presenta formato de escape HTML.
  • Para el atributo <ModulePrefs> title_url, utiliza __UP_name__ . Presenta formato de escape URL.
  • En el código HTML de la sección <Content>, utiliza __UP_name__. Presenta formato de escape HTML.
  • En el código JavaScript de la sección <Content>, utiliza la función gadgets.Prefs().

Uso compartido de las preferencias del usuario

Puedes utilizar la función shareable-prefs para permitir que varios usuarios puedan editar las preferencias de usuario de un gadget. De este modo, los usuarios pueden compartir el gadget y ver las ediciones del resto. Por ejemplo, los miembros de una familia podrían compartir un gadget de lista de la compra, donde cada persona podría añadir sus productos favoritos. Los datos de preferencia de usuario forman parte del estado del gadget alojado en iGoogle. Para obtener más información sobre las preferencias de usuario, consulta la Guía del desarrollador del API de gadgets.

Para que varios usuarios puedan compartir las preferencias de usuario de un gadget, el gadget debe incluir la línea <optional feature="shareable-prefs"/> en la sección <ModulePrefs>. Por ejemplo, este gadget utiliza la preferencia de usuario del tipo de datos "list" para rellenar una lista de la compra:

Uso compartido de este gadget

El código del gadget sería el siguiente:

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

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

Una vez añadido a iGoogle un gadget compatible con las preferencias que se pueden compartir, puedes convertirlo en un gadget de colaboración de la forma que se describe a continuación.

Paso 1: haz clic en el triángulo del gadget que deseas compartir y elige Compartir este gadget.

Uso compartido de este gadget

Paso 2: si eres usuario de Gmail, elige a los amigos con los que desees compartir el gadget o escribe sus direcciones de correo electrónico.

Uso compartido de este gadget

Paso 3: decide si deseas permitir que tus amigos editen el contenido de tu gadget o que sólo puedan verlo en su página de iGoogle.

  • Si eliges Ver y editar mi contenido, tus amigos podrán editar las preferencias de usuario del gadget. Sus cambios aparecerán reflejados en tu versión del gadget y en cualquier otra versión compartida del mismo.
  • Si eliges Ver mi contenido, tus amigos no podrán modificar el gadget, ni siquiera sus copias locales. Sólo tú puedes modificar el gadget; tus cambios se publicarán en todas las versiones compartidas del gadget.

Haz clic en Enviar invitaciones. Tus amigos recibirán un mensaje de correo electrónico con una invitación para añadir el gadget a su propia página de iGoogle.

Uso compartido de una invitación

Los amigos a los que hayas autorizado a editar el gadget podrán modificar las preferencias de usuario del gadget y publicar sus cambios en todas las versiones compartidas del gadget.

Definición de las preferencias del gadget

En la sección <ModulePrefs> del archivo XML se especifican las características del gadget como, por ejemplo, el título, el autor, el tamaño preferido, etc. Por ejemplo:

<Module>
<ModulePrefs title="Today's Network Traffic" title_url="http://www/~rowan/gadgets/stats/"
height="200" author="Jane Smith" author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>

Los usuarios de tu gadget no pueden cambiar estos atributos.

Para obtener una lista completa de los atributos <ModulePrefs>, consulta la sección Referencia.

Recuerda: los gadgets son públicos

Recuerda que no existen gadgets privados. Cuando publicas un gadget en un sitio web público, otros usuarios pueden encontrarlo y verlo. Asegúrate de no incluir información personal como tu número de teléfono o dirección de correo electrónico personal.

¿Qué sucede si no deseas hacer público tu gadget? Google anima a los autores de gadgets a compartir sus especificaciones. Sin embargo, si deseas minimizar la visibilidad pública del gadget antes de publicarlo, sigue estas sugerencias:

  • No envíes el gadget al directorio de contenido ni lo publiques en directorios como googlemodules.com o hotmodules.com.
  • Si otros usuarios no pueden encontrar tu gadget, es poco probable que adivinen la URL. A continuación se indican algunas medidas que permiten evitar los rastreos de los motores de búsqueda:
    • Asegúrate de que tu servidor web no incluya un listado de archivos con tu archivo (esto también evita que otros usuarios puedan fisgonear).
    • Asegúrate de que no existan hiperenlaces web a tu gadget.

Más información

Cuando estés listo para crear gadgets más complejos, accede a la sección Principios de programación o regresa a la página principal de la documentación para obtener una descripción general de las secciones y los temas.

Volver al principio