Scrivi i tuoi gadget

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

La Guida introduttiva presenta i gadget. Il passo successivo è creare i tuoi gadget. Questo documento spiega come fare.

Passaggi di base

Per creare ed eseguire il deployment di un gadget, procedi nel seguente modo:

  1. Utilizza qualsiasi editor di testo per scrivere la specifica del gadget e ospitala su un server web pubblico.
  2. Aggiungi il tuo gadget a un sito che abbia la possibilità di eseguire gadget.

Anatomia di un gadget

Una volta compreso come modificare e pubblicare i gadget, potete iniziare a includere funzionalità più avanzate nelle specifiche del tuo gadget. La specifica del gadget XML è composta da 3 parti principali:

  • Sezione dei contenuti. Nella sezione <Content> è avvenuto il vero lavoro del gadget. Qui puoi specificare il tipo di gadget, la logica di programmazione e spesso gli elementi HTML che determinano l'aspetto del gadget.
  • Preferenze utente. La sezione <UserPrefs> definisce i controlli che consentono agli utenti di specificare le impostazioni per il gadget. Ad esempio, un gadget di saluto personalizzato potrebbe fornire un campo di testo in cui gli utenti possono specificare il proprio nome.
  • Preferenze gadget. La sezione <ModulePrefs> nel file XML specifica le caratteristiche del gadget, ad esempio titolo, autore, dimensioni preferite e così via.

Nota: all'interno degli attributi XML in una specifica del gadget, è necessario "escape" (ovvero codificare correttamente i caratteri) in modo che vengano interpretati correttamente. Per ulteriori informazioni, consulta la sezione Utilizzo di caratteri speciali di escape.

Quando scrivi un gadget, inizia dalla sezione <Content>.

Definizione dei contenuti

La sezione <Content> rappresenta il "brains" di un gadget. La sezione <Content> definisce il tipo di contenuti e contiene i contenuti stessi o ha un link a contenuti esterni. Nella sezione <Content>, gli attributi dei gadget e le preferenze utente vengono combinati con la logica di programmazione e le informazioni di formattazione per diventare un gadget in esecuzione.

Il modo più semplice per creare il tuo gadget è semplicemente inserire il codice HTML (e facoltativamente JavaScript o Flash) nella sezione <Content>. Gli sviluppatori web esperti possono leggere la pagina Scegli un tipo di contenuti per altre opzioni relative al controllo dell'accesso, all'hosting remoto, utilizzando linguaggi di scripting alternativi e altri argomenti.Ecco un semplice gadget di esempio. Questo gadget mostra una fotografia cliccabile che apre un album fotografico in una nuova pagina HTML:

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

Specifica di un DOCTYPE

Puoi includere un DOCTYPE arbitrario nelle specifiche del tuo gadget. Per impostazione predefinita, i gadget che non specificano un DOCTYPE vengono visualizzati in modalità di ricerca.

Definire le preferenze utente

Alcuni gadget devono fornire agli utenti un modo per fornire informazioni specifiche per gli utenti. Ad esempio, un gadget di gioco potrebbe consentire agli utenti di inserire un livello di difficoltà preferito. La sezione delle preferenze utente (<UserPref>) nel file XML descrive i campi di input dell'utente che sono diventati controlli dell'interfaccia utente quando il gadget viene eseguito. Le preferenze dell'utente vengono archiviate in modo permanente.

Nota: per un meccanismo di persistenza per uso più generico che non è legato agli userpref, vedi l'API persistenza di OpenSocial.

Ad esempio, questo gadget mostra un saluto personale in base all'ora del giorno. Consente agli utenti di specificare quanto segue:

  • Un nome da utilizzare nell'annuncio. Il nome viene visualizzato anche nella barra del titolo.
  • Un colore di sfondo.
  • Consente di indicare se visualizzare o meno una foto.

Ecco come viene visualizzato il gadget quando l'utente fa clic su modifica per modificare le preferenze dell'utente:

Controlli userprefs

Le preferenze utente che vengono trasformate in controlli dell'interfaccia utente nel gadget in esecuzione sono definite nella specifica XML come segue:

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

Tieni presente quanto riportato di seguito:

  • La riga 3 del file contiene il testo title="Preferences for __UP_myname__". Quando esegui il gadget, il valore specificato per la preferenza utente myname è dinamico sostitutivo con __UP_myname__.
  • La preferenza utente myname è contrassegnata come "required." Se l'utente tenta di eseguire il gadget senza fornire un valore per questo campo, la casella di modifica delle preferenze utente rimane aperta finché non viene fornito un valore.
  • La preferenza utente mychoice ha un tipo di dati bool. visualizzato nell'interfaccia utente come casella di controllo.
  • La preferenza utente mycolor ha un tipo di dati enum. L'elenco EnumValues specifica le opzioni visualizzate in un menu a discesa nella casella di modifica delle preferenze utente.

Ecco il gadget completo, incluso il codice JavaScript che mostra il saluto per il 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>

Per un elenco di tutti gli attributi <UserPref>, consulta la Guida di riferimento.

Le preferenze utente sono accessibili dal tuo gadget utilizzando l'API JavaScript delle preferenze utente, ad esempio:

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

Per un elenco di tutte le funzioni JavaScript, consulta la Guida di riferimento a JavaScript.

Nota: se memorizzi dati utente privati sensibili nelle preferenze utente di un gadget, ti consigliamo di utilizzare la funzionalità dominio bloccato.

Variabili di sostituzione delle preferenze utente

Puoi utilizzare una variabile di sostituzione nel formato __UP_userpref__ nelle sezioni <ModulePrefs> o <UserPref>, dove userpref corrisponde all'attributo name di una preferenza utente. Quando il gadget viene eseguito, il valore stringa della preferenza utente corrispondente viene sostituito con la variabile senza caratteri di escape. Ad esempio, in questo estratto, il valore fornito dall'utente in fase di esecuzione per la preferenza utente projects viene sostituito da __UP_projects__ nella stringa 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>

Puoi vedere un altro esempio in questo caso nell'esempio di preferenze utente.

Di seguito sono riportate le linee guida generali per l'utilizzo delle variabili di sostituzione delle preferenze utente:

  • Per l'attributo <ModulePrefs> title, utilizza __UP_nome__ . Si tratta di un escape HTML.
  • Per l'attributo <ModulePrefs> title_url, utilizza __UP_nome__ . Si tratta di un escape con URL.
  • Nel codice HTML della sezione <Content>, utilizza __UP_nome__. Questo è in formato HTML.
  • Nel codice JavaScript della sezione <Content>, utilizza la funzione gadgets.Prefs().

Definizione delle preferenze per i gadget

La sezione <ModulePrefs> nel file XML specifica le caratteristiche del gadget, ad esempio titolo, autore, dimensioni preferite e così via. Ad esempio:

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

Gli utenti del tuo gadget non possono modificare questi attributi.

Per un elenco completo degli attributi <ModulePrefs>, consulta la Guida di riferimento.

Come procedere

Quando tutto è pronto per scrivere gadget più complessi, vai a Concetti fondamentali dello sviluppo o torna alla home page della documentazione per una panoramica di sezioni e argomenti.

Torna all'inizio