Malheureusement, cette documentation n’est plus à jour. Si vous préférez, vous pouvez utiliser la documentation en anglais, qui a été mise à jour. Nous vous prions de nous excuser pour ce désagrément.

API Google Gadgets - Références

Ceci est un document de référence relatif à l'API Google Gadgets. Il comprend des informations de base sur les spécifications XML des gadgets, des bibliothèques JavaScript principales et spécifiques à certaines fonctions.

Sommaire

Structure XML
Bibliothèques JavaScript
1. Bibliothèque principale JavaScript
2. Bibliothèques de fonctions JavaScript spécifiques
Paramètres de requête

Structure XML

La rubrique suivante décrit la structure et le contenu du fichier XML servant à définir un gadget.

Caractéristiques du gadget

La section <ModulePrefs> du fichier XML définit les caractéristiques d'un gadget, notamment le titre, l'auteur, les dimensions souhaitées, etc. Exemple :

<Module>
  <ModulePrefs title="Developer Forum" 
    title_url="http://groups.google.com/group/Google-Homepage-API" 
    height="200" 
    author="Jane Smith" 
    author_email="xxx@google.com"/> 
  <Content ...>
   ... content ...
  </Content> 
</Module>

Les utilisateurs de votre gadget ne peuvent pas modifier ces attributs.

Le tableau suivant répertorie les attributs de la balise <ModulePrefs> :

Attribut	Description
title	Chaîne de caractères facultative indiquant le titre du gadget. Ce titre est affiché dans la barre de titre du gadget sur la page iGoogle de l'utilisateur. Si cette chaíne contient des variables de substitution associées aux préférences de l'utilisateur et que vous envisagiez de publier votre gadget dans l'annuaire de contenu sur la page d'accueil Google, renseignez également la balise `directory_title` avec un titre à afficher dans cet annuaire.
directory_title	Chaîne de caractères facultative indiquant le titre qui sera associé à votre gadget dans l'annuaire de contenu de la page d'accueil Google. Cet attribut doit contenir uniquement le texte à afficher, non les variables de substitution associées aux préférences de l'utilisateur. En effet, l'annuaire de contenu présente une vue statique de votre gadget qui ne permet pas d'effectuer les substitutions requises pour produire un titre intelligible. Par exemple, si votre gadget est intitulé "Des amis pour __UP_name__", l'annuaire n'est pas en mesure de procéder à la substitution de " __UP_name__". Dans ce cas, définissez l'attribut `directory_title` par "Amis" uniquement.
title_url	Chaîne de caractères facultative indiquant une URL vers laquelle le titre du gadget doit pointer. Vous pouvez, par exemple, utiliser ce titre pour établir un lien vers votre page d'accueil.
description	Chaîne de caractères facultative décrivant le gadget.
author	Chaîne de caractères facultative indiquant l'auteur du gadget.
author_email	Chaîne de caractères facultative indiquant l'adresse e-mail de l'auteur du gadget. Utilisez le système de messagerie de votre choix, mais ne mentionnez pas votre adresse e-mail personnelle afin d'éviter le spam. Vous pouvez, par exemple, adopter la forme d'adresse suivante dans les spécifications de votre gadget : helensmith.feedback+coolgadget@gmail.com. En effet, Gmail ignore les caractères situés après le signe (+), par conséquent cette adresse sera interprétée comme suit : helensmith.feedback@gmail.com. Pour obtenir une invitation à Gmail en vue de créer une adresse Gmail pour votre gadget, contactez l'assistance technique de Google.
author_affiliation	Chaíne de caractères facultative telle que "Google" permettant de préciser l'affiliation de l'auteur. Cet attribut est nécessaire pour les gadgets inclus dans l'annuaire de contenu de la page d'accueil Google.
author_location	Emplacement géographique de l'auteur, "Marseille, France" par exemple.
screenshot	Chaîne de caractères facultative fournissant l'URL de la capture d'écran du gadget. Cette image doit figurer sur un site Web public qui n'est pas bloqué par un fichier robots.txt. Bien que le format PNG soit conseillé, les formats GIF et JPG sont également acceptés. La largeur des captures d'écran de gadgets doit être de 280 pixels. La hauteur de cette capture doit correspondre à la hauteur "normale" du gadget en cours d'utilisation. Pour obtenir des instructions détaillées concernant les captures d'écran, consultez la rubrique Publication dans l'annuaire de contenu.
thumbnail	Chaîne de caractères facultative fournissant l'URL de la vignette du gadget. Cette image doit figurer sur un site Web public qui n'est pas bloqué par un fichier robots.txt. Bien que le format PNG soit conseillé, les formats GIF et JPG sont également acceptés. Les vignettes doivent être de 120 x 60 pixels. Pour obtenir des instructions détaillées concernant les vignettes, consultez la rubrique Publication dans l'annuaire de contenu.
height	Entier positif facultatif précisant la hauteur de la zone dans laquelle le gadget est exécuté. La hauteur par défaut est de 200 pixels.
width	Entier positif facultatif précisant la largeur de la zone dans laquelle le gadget est exécuté. Ce paramètre est applicable aux gadgets utilisés en syndicationuniquement. La largeur par défaut est de 320 pixels.
scaling	Opérateur booléen facultatif indiquant si les proportions du gadget (hauteur par largeur) doivent être conservées lorsque le navigateur est redimensionné. Pour les gadgets dont la hauteur s'adapte automatiquement, définissez cet attribut sur true. Pour les gadgets dont la hauteur est fixe, utilisez la valeur false. La valeur par défaut de cet attribut est true.
scrolling	Opérateur booléen facultatif insérant une barre de défilement verticale et/ou horizontale lorsque le contenu d'un gadget est plus volumineux que l'espace défini. Si la valeur de cet attribut est false, le contenu est tronqué selon la hauteur et la largeur disponibles (notez que la largeur n'est pas configurable). Par défaut, cette valeur est définie sur false.
singleton	Opérateur booléen précisant si les utilisateurs peuvent ajouter plusieurs copies d'un même gadget à partir d'un annuaire. La valeur par défaut est définie sur true. Par conséquent, les gadgets ne peuvent être insérés qu'une seule fois par défaut. Les annuaires peuvent gérer cet attribut comme ils l'entendent. Par exemple, l'annuaire de contenu de la page d'accueil Google utilise l'attribut `singleton="true"` pour griser les gadgets déjà insérés et leur associer la mention "Ajouté". Notez que les modifications apportées à cet attribut ne sont pas prises en compte immédiatement dans les annuaires. Cet attribut n'empêche pas les utilisateurs d'ajouter plusieurs fois un même gadget par le biais du gadget du développeur ou de la fonction Ajouter une URL. Par conséquent, votre gadget doit pouvoir gérer plusieurs instances de lui-même.
author_photo	URL pointant vers une photo destinée à la page des auteurs (format PNG 70 x 100 souhaité, les formats JPG et GIF sont également pris en charge).
author_aboutme	Informations personnelles destinées à la page des auteurs (limitez-vous à 500 caractères environ).
author_link	Lien vers votre site Web, votre blog, etc., à insérer dans la page des auteurs.
author_quote	Citation que vous souhaitez faire figurer sur la page des auteurs (limitez-vous à 300 caractères environ).

Utilisation des bibliothèques

Afin de pouvoir utiliser certaines fonctions de l'API gadget, telles que la hauteur dynamique ou la sauvegarde d'états, vous devez charger la bibliothèque JavaScript correspondante à l'aide de la balise <Require> (dans la section <ModulePrefs>). La balise <Require> comporte un attribut obligatoire, feature, dont la valeur indique la bibliothèque de fonction à importer. Exemple :

<ModulePrefs 
  title="Set Userprefs Demo">
  <Require feature="dynamic-height"/>
  <Require feature="setprefs" /> 
</ModulePrefs>

Pour de plus amples informations sur les bibliothèques de fonctions, consultez la rubrique Bibliothèques de fonctions JavaScript spécifiques.

Définition de paramètres régionaux

Vous pouvez utiliser des balises <Locale> dans la section <ModulePrefs> pour définir les paramètres régionaux pris en charge par votre gadget. Elle vous permet par ailleurs de spécifier des fichiers de localisation, comme indiqué dans la rubrique Google Gadgets et internationalisation.

Par exemple, l'extrait suivant définit deux paramètres régionaux :

<ModulePrefs ...>
  <Locale lang="en" country="us" />
  <Locale lang="ja" country="jp" />
</ModulePrefs>

Les attributs "lang" (langue) et "country" (pays) sont tous deux facultatifs, mais vous devez mentionner au moins l'un des deux dans chaque balise <Locale>. Si l'un ou l'autre de ces attributs est manquant, sa valeur équivaut à "*" et "ALL" (tous). Si vous indiquez un pays et aucune langue, le système suppose que votre gadget prend en charge toutes les langues associées au pays sélectionné. De la même manière, si vous spécifiez une langue mais pas de pays, le système suppose que votre gadget prend en charge tous les pays associés à la langue définie.

Cliquez ici pour obtenir la liste des valeurs admises pour les attributs "lang" et "country".

Il existe quelques exceptions aux règles habituelles relatives à la langue :

Chinois simplifié : lang="zh-cn" (généralement associé à l'attribut country="cn").
Chinois traditionnel : lang="zh-tw" (généralement associé à l'attribut country="tw" ou "hk", respectivement Taiwan ou Hong Kong).

Le tableau suivant répertorie les attributs de la balise <Locale> :

Attribut	Description
lang	Chaîne de caractères facultative indiquant la langue associée aux paramètres régionaux.
country	Chaîne de caractères facultative indiquant le pays associé aux paramètres régionaux.
messages	Chaîne de caractères facultative correspondant à l'URL d'un fichier de localisation. Les fichiers de localisation sont des fichiers XML contenant des chaînes de caractères traduites pour un paramètre régional donné. Pour plus d'informations, consultez la rubrique Google Gadgets et internationalisation.

Si vous ne définissez pas de balise <Locale>, le pays et la langue pris en charge par défaut sont les États-Unis et l'anglais.

Définition des paramètres de compatibilité

Les gadgets ne fonctionnent pas nécessairement dans tous les environnements. Certains gadgets nécessitent d'utiliser un navigateur ou un logiciel particulier. Vous pouvez indiquer certaines informations relatives aux contraintes spécifiques à votre gadget dans la balise <MayRequire>. Exemple :

<ModulePrefs ...>
  <MayRequire type="plugin" value="quicktime"/>
  <MayRequire type="browser" value="firefox" min_version="1.06"/>
  <MayRequire type="platform" 
    value="windows"> This gadget uses a Windows API.
  </MayRequire>
</ModulePrefs>

Le tableau suivant répertorie les attributs de la balise <MayRequire> :

Attribut	Description
type	Chaîne de caractères obligatoire indiquant le type de contrainte. Les valeurs prises en charge pour l'attribut type sont "platform, "browser" (navigateur) et "plugin".
value	Chaîne de caractères obligatoire définissant la valeur du type. Par exemple, type="plugin" value="flash".
min_version	Chaîne de caractères facultative précisant quelle version de l'élément en question est nécessaire.
cdata	Chaîne de caractères facultative fournissant des informations complémentaires relatives à la contrainte.

Préférences utilisateur

Certains gadgets demandent à l'utilisateur de fournir des informations personnelles. Par exemple, un gadget météo peut exiger de l'utilisateur qu'il indique son code postal. Ces préférences sont définies dans le paramètre <UserPref> du fichier XML qui décrit les champs de saisie permettant à l'utilisateur de contrôler l'interface du gadget en cours d'exécution.

Le tableau suivant répertorie les attributs des préférences utilisateur (<UserPref>) :

Attribut	Description
name	Nom "symbolique" obligatoire désignant le paramètre de préférence qui s'affiche lorsque l'utilisateur modifie ce dernier et que l'attribut `display_name` n'est pas défini. Cet attribut peut uniquement contenir des lettres, des nombres et des traits de soulignement, c'est-à-dire être une expression rationnelle telle que ^[a-zA-Z0-9_]+$. Ce nom doit être unique.
display_name	Chaîne de caractères facultative à afficher à côté des préférences de l'utilisateur dans la fenêtre de modification. Ce nom doit être unique.
urlparam	Chaîne de caractères facultative à utiliser comme nom de paramètre dans le cas d'un contenu de type `type="url"`.
datatype	Chaîne de caractères facultative précisant le type de données associé à cet attribut. Les valeurs possibles sont les suivantes : `string`, `bool`, `enum`, `hidden` (chaíne invisible, non modifiable par l'utilisateur), list (tableau dynamique dépendant des entrées de l'utilisateur) ou `location` (pour les gadgets Google Maps). La valeur par défaut est string.
required	Argument booléen facultatif (`true` ou `false`) indiquant si la préférence d'utilisateur concernée est obligatoire. La valeur par défaut est `false`.
default_value	Chaîne de caractères facultative précisant une valeur par défaut applicable à la préférence d'utilisateur.

Les préférences d'utilisateur sont accessibles à partir de l'API JavaScript correspondante, par exemple :

<script type="text/javascript">
   // Must be constructed using the __MODULE_ID__ token. It gets replaced
   // at runtime with the actual ID of your gadget.
   var prefs = new _IG_Prefs(__MODULE_ID__);
   var someStringPref = prefs.getString("StringPrefName");
   var someIntPref = prefs.getInt("IntPrefName");
   var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Type de données enum

enum est l'une des valeurs que vous pouvez définir dans le paramètre <UserPref> datatype. Le type de données enum se présente dans l'interface utilisateur sous forme de menu proposant plusieurs choix. Vous pouvez définir les éléments de ce menu à l'aide de l'attribut <EnumValue>.

Ce paramètre <UserPref> peut permettre aux utilisateurs de choisir le niveau de difficulté d'un jeu, par exemple. Chaque valeur apparaissant dans ce menu (Easy, Medium et Hard) est définie à l'aide d'une balise <EnumValue>.

<UserPref name="difficulty" 
     display_name="Difficulty"
     datatype="enum"
     default_value="4">
  <EnumValue value="3" display_value="Easy"/>
  <EnumValue value="4" display_value="Medium"/>
  <EnumValue value="5" display_value="Hard"/>
</UserPref>

Le tableau suivant répertorie les attributs de la balise <EnumValue> :

Attribut	Description
value	Chaîne de caractères obligatoire définissant une valeur unique. Cette dernière apparaît dans le menu affiché dans la zone de modification des préférences utilisateur, à moins que l'attribut display_value soit défini.
display_value	Chaîne de caractères facultative affichée dans le menu situé dans la zone de modification des préférences utilisateur. Si vous ne renseignez pas le paramètre display_value, l'attribut value est affiché dans l'interface utilisateur.

Section de contenu

La section <Content> définit le type de contenu et peut soit recueillir elle-même le contenu, soit faire référence à un contenu externe. La section <Content> est celle qui articule les attributs d'un gadget et les préférences utilisateur avec la logique de programmation et les informations de mise en forme pour permettre le fonctionnement du gadget. Pour de plus amples informations sur les types de contenu, consultez la rubrique Choix du type de contenu.

Le tableau suivant répertorie les attributs de la balise <Content> :

Attribut	Description
type	Chaîne de caractères facultative définissant le type de contenu. Les valeurs possibles sont html, html-inline et url. La valeur par défaut est html.
href	Chaîne de caractères fournissant une URL de destination. Cet attribut est obligatoire pour type="url" et interdit pour les autres types de contenu.
cdata	Chaîne de caractères facultative. Dans le cas d'un contenu HTML, elle contient les données HTML brutes à afficher dans un cadre iframe.

Bibliothèques JavaScript

Cette rubrique décrit les fonctions JavaScript prises en charge dans l'API Google Gadgets. Pour de plus amples informations sur les contraintes relatives à l'utilisation des bibliothèques JavaScript, consultez la rubrique Utilisation des bibliothèques JavaScript avec différents types de contenu.

Il existe deux types de bibliothèque JavaScript dans l'API Google Gadgets :

Bibliothèque principale JavaScript
Bibliothèques de fonctions JavaScript spécifiques

Bibliothèque principale JavaScript

La bibliothèque principale JavaScript inclut des fonctions de base sans lien avec des fonctions spécifiques.

Le tableau suivant répertorie les méthodes préférences utilisateur et les fonctions pouvant être appelées sur un objet préférences utilisateur une fois que ce dernier est instancié :

Nom	Description
_IG_Prefs()	Méthode des préférences utilisateur. Exemple : `var prefs = new _IG_Prefs();` Cette fonction facultative adopte l'identifiant d'un gadget (`__MODULE_ID__`) comme paramètre. Elle est uniquement obligatoire dans le cas de gadgets intégrés.
getString(userpref)	Renvoie le paramètre userpref spécifié en tant que valeur de chaíne. Lorsque les préférences utilisateur sont associées à un type de données list, cette fonction renvoie le contenu du tableau sous forme de chaíne unique de valeurs, séparées par des barres verticales.
getInt(userpref)	Renvoie le paramètre userpref spécifié en tant que valeur d'entier.
getBool(userpref)	Renvoie le paramètre userpref spécifié en tant que valeur booléenne.
getArray(userpref)	Lorsque le paramètre userpref est associé au type de données list, cette fonction renvoie le contenu sous forme de tableau.
set(userpref, value)	Définit la valeur value du paramètre userpref spécifié. Cette fonction nécessite d'inclure la bibliothèque setprefs dans votre gadget, comme décrit dans la rubrique Bibliothèque Setprefs. Pour obtenir de plus amples informations sur cette fonction ainsi que des exemples, consultez la rubrique Sauvegarde d'états.
setArray(userpref, [value...])	Si le paramètre userpref est associé au type de données list, cette fonction ajoute des éléments dans le tableau. Elle fonction nécessite d'inclure la bibliothèque setprefs dans votre gadget, comme décrit dans la rubrique Bibliothèque Setprefs. Pour de plus amples informations sur cette fonction, consultez la rubrique Utilisation du type de données Liste. Exemple : prefs.setArray("mylist", ["Apples","Oranges"]);
dump()	Cette fonction sert au débogage et utilise la fonction document.writeln() pour afficher toutes les préférences disponibles.

Le tableau suivant répertorie les méthodes JavaScript génériques qui ne présentent pas de lien spécifique avec les préférences utilisateur :

Nom	Description
_IG_FetchContent(url, func)	Récupère le contenu à l'adresse url. Une fois l'opération terminée, cette fonction appelle la fonction func. Notez que _IG_FetchContent() est une fonction asynchrone, c'est-à-dire qu'elle est renvoyée immédiatement, puis appelle sa fonction de rappel interne une fois la récupération de contenu terminée. Cela nécessite d'inclure l'intégralité du code dépendant de cette fonction dans la fonction de rappel ou dans des fonctions appelées par cette dernière. Pour de plus amples informations sur cette fonction, consultez la rubrique Utilisation de texte.
_IG_FetchXmlContent(url, func)	Récupère le contenu XML à l'adresse url. Une fois l'opération terminée, cette fonction appelle la fonction func. Tout comme _IG_FetchContent(), cette fonction est asynchrone. Pour de plus amples informations sur cette fonction, consultez la rubrique Utilisation de contenu XML.
_IG_FetchFeedAsJSON(url, func, num_entries, get_summaries)	Récupère le contenu d'un flux RSS ou Atom à l'adresse url et le renvoie sous forme d'objet JSON. Une fois l'opération terminée, cette fonction appelle la fonction func. Elle récupère le nombre d'entrées spécifié dans le paramètre num_entries (par défaut cette valeur est définie sur 3, mais elle peut aller de 1 à 100) et peut également extraire les résumés de ces entrées en fonction de la valeur attribuée au paramètre get_summaries (paramètre facultatif dont la valeur par défaut est définie sur false). Tout comme _IG_FetchContent(), cette fonction est asynchrone. Pour de plus amples informations sur cette fonction, consultez la rubrique Utilisation de flux.
_IG_RegisterOnloadHandler(func)	Gestionnaire d'événement appelé durant le chargement. Il comporte un argument unique représentant une fonction appelée à la suite du chargement de la page. La fonction exécutée n'accepte aucun argument. Notez que cela n'est utile que pour les gadgets intégrés, car les gadgets comportant des cadres iframe peuvent aisément être enregistrés durant le chargement à l'aide de la fonction document.body.onload = .... Voici quelques exemples : _IG_RegisterOnloadHandler(function() { alert("page loaded"); }); function onLoadFunc__MODULE_ID__() { alert("page loaded"); }); _IG_RegisterOnloadHandler(onLoadFunc__MODULE_ID__);
_gel(id)	Classe enveloppant la fonction JavaScript document.getElementById().
_esc(str)	Classe enveloppant les fonctions JavaScript escape() et encodeURIComponent().
_unesc(str)	Classe enveloppant les fonctions JavaScript unescape() et decodeURIComponent().
_trim(str)	Supprime les espaces au début et à la fin de la chaîne str.
_gelstn(tagname)	Classe enveloppant la fonction JavaScript document.getElementsByTagName().
_uc(str)	Renvoie la chaíne str en lettres capitales.
_min(val1, val2)	Compare les paramètres val1 et val2 pour renvoyer la plus petite valeur ou celle de val2 si les deux valeurs sont égales.
_max(val1, val2)	Compare les paramètres val1 et val2 pour renvoyer la valeur la plus élevée ou celle de val2 si les deux valeurs sont égales.
_hesc(str)	Renvoie la chaíne HTML str dans laquelle les caractères suivants sont remplacés par des caractères d'échappement : <>&'"
_args()	Renvoie les paires de paramètre clé/valeur de l'URL à partir du paramètre document.location sous forme de tableau associatif. Par exemple, "&foo=bar&up_cats=meow" serait ainsi remplacé par {"foo":"bar", "up_cats":"meow"}. Voici un exemple d'utilisation possible, permettant de récupérer la langue et le pays : var lang = _args()["lang"]; if (typeof lang == "undefined") { lang = "en"; }
_toggle()	Permet d'afficher et de masquer un élément HTML.

Bibliothèques de fonctions JavaScript spécifiques

L'API Google Gadgets comprend les bibliothèques de fonctions suivantes :

setprefs
dynamic-height
tabs
drag
grid
minimessage
analytics

Pour utiliser une bibliothèque de fonctions donnée, vous devez l'inclure dans les spécifications de votre gadget à l'aide de la balise <Require> (dans le paramètre <ModulePrefs>). Exemple :

<ModulePrefs 
  title="My Tabbed Gadget">
  <Require feature="tabs"/>
</ModulePrefs>

Les bibliothèques de fonctions sont décrites de manière détaillée dans les rubriques suivantes.

Bibliothèque setprefs

Pour obtenir des informations détaillées sur la bibliothèque setprefs ainsi que des exemples d'utilisation, consultez la rubrique Sauvegarde d'états.

Pour pouvoir faire appel à la bibliothèque setprefs, les gadgets doivent inclure la ligne suivante dans le paramètre <ModulePrefs> :

<Require feature="setprefs"/>

La bibliothèque setprefs comprend la fonction suivante :

set(userpref, value)

Cette fonction est appelée sur un objet préférences utilisateur (généralement masqué). Le paramètre userpref spécifie le nom de la préférence utilisateur, le paramètre value indique la valeur attribuée à la préférence utilisateur. Exemple :

var prefs = new _IG_Prefs(__MODULE_ID__);
prefs.set("score", 5000);

Bibliothèque dynamic-height

Pour obtenir des informations détaillées sur la bibliothèque dynamic-height ainsi que des exemples d'utilisation, consultez la rubrique Réglage de la hauteur du gadget.

Pour pouvoir faire appel à la bibliothèque dynamic-height, les gadgets doivent inclure la ligne suivante dans le paramètre <ModulePrefs> :

<Require feature="dynamic-height" />

La bibliothèque dynamic-height comprend une fonction indiquant au gadget de se redimensionner automatiquement :

_IG_AdjustIFrameHeight()

Bibliothèque tabs

Pour obtenir des informations détaillées sur la bibliothèque tabs ainsi que des exemples d'utilisation, consultez la rubrique Onglets.

Pour pouvoir faire appel à la bibliothèque tabs, les gadgets doivent inclure la ligne suivante dans le paramètre <ModulePrefs> :

<Require feature="tabs" />

Le tableau suivant répertorie les méthodes tabs et les fonctions pouvant être appelées sur un objet tabs une fois que ce dernier est instancié :

Fonction	Description
_IG_Tabs(module_id, opt_selected_tab)	Méthode qui crée une instance de l'objet `tabs`. Le premier paramètre est l'identifiant du gadget, __MODULE_ID__. opt_selected_tab est un paramètre facultatif correspondant au nom de l'onglet sélectionné par défaut lors du premier chargement du gadget. Lorsque ce paramètre n'est pas défini, le premier onglet est sélectionné par défaut.
addTab(tabName, opt_domId, opt_callback)	Ajoute un onglet à l'objet `tabs` et renvoie l'identifiant DOM de la balise <div> associée à l'onglet. En l'absence de balise <div>, la bibliothèque `tabs` en crée une. Le paramètre tabName indique le nom à afficher pour cet onglet. opt_domId est un paramètre facultatif qui fournit l'identifiant DOM de la balise <div> correspondant au contenu de l'onglet. Le paramètre facultatif opt_callback définit la fonction de rappel à déclencher à chaque fois que cet onglet est sélectionné.
addDynamicTab(tabName, callback)	Ajoute à l'objet `tabs` un onglet dont le contenu dynamique est fourni par une fonction callback. Crée une balise <div> vide et renvoie son identifiant DOM. Le contenu de la balise <div> doit être créé de manière dynamique depuis la fonction callback. Le paramètre tabName indique le nom à afficher pour cet onglet. Le paramètre callback définit la fonction callback à appeler à chaque fois que cet onglet est sélectionné.
setSelectedTab(tabIndex)	Sélectionne l'onglet spécifié dans le paramètre tabIndex et déclenche la fonction de rappel associée lorsque celle-ci existe. Si l'onglet est déjà sélectionné, le rappel est alors ignoré. Les onglets sont indexés à l'aide de numéros à partir de 0. Le numéro attribué dans l'index dépend de la position. Lorsque vous modifiez la position d'un onglet par rapport aux autres, son numéro change en conséquence.
moveTab(tabIndex1, tabIndex2)	Intervertit les positions des onglets situés dans tabIndex1 et tabIndex2. L'onglet sélectionné n'est pas modifié et aucune fonction de rappel n'est appelée.

Bibliothèque drag

Pour obtenir des informations détaillées sur la bibliothèque drag ainsi que des exemples d'utilisation, consultez la rubrique Fonction de glisser.

Pour pouvoir faire appel à la bibliothèque drag, les gadgets doivent inclure la ligne suivante dans le paramètre <ModulePrefs> :

<Require feature="drag" />

La bibliothèque drag comprend les fonctions de rappel suivantes :

Fonction de rappel	Description
onDragStart = function(newSource) {}	Appelée lorsque le glisser commence.
onDragTargetHit = function(newTarget, lastTarget) {}	Appelée lorsque le glisser est en cours et qu'une cible est atteinte.
onDragTargetLost = function(lastTarget) {}	Appelée lorsque le glisser est en cours et que l'utilisateur ne pointe plus sur aucune cible.
onDragEnd = function(source, target) {}	Appelée lorsque le glisser a pris fin (l'utilisateur a relâché le bouton de la souris).
onDragClick = function(source) {}	Appelée lorsque l'utilisateur n'a pas déplacé la souris, mais qu'il a cliqué sur une source, puis relâché le bouton.

Le tableau suivant répertorie les méthodes drag et les fonctions pouvant être appelées sur un objet drag une fois que ce dernier est instancié. Les sources et les cibles sont des éléments HTML associés à des identifiants DOM et des identifiants de glisser. Si aucun identifiant de glisser n'est spécifié, la bibliothèque drag utilise l'identifiant DOM comme identifiant de glisser.

Fonction	Description
_IG_Drag()	Méthode `drag` qui instancie un objet `drag` auquel vous pouvez ajouter des sources et des cibles.
addSource(DOM_id)	Ajoute une source à l'objet `drag`. DOM_id correspond à l'identifiant unique de l'élément HTML (HTML element) qui représente la source ajoutée. Si vous n'indiquez aucun identifiant de glisser, la bibliothèque drag utilise l'identifiant DOM comme identifiant de glisser. Exemple : drag_obj.addSource("dom_id1");
addSource(drag_id, HTML_element)	Ajoute HTML_element en tant que source à l'objet `drag`. Attribue à la source un identifiant de glisser (drag_id). Exemple : drag_obj.addSource("first", _gel("dom_id1"));
addSource(drag_id, HTML_element, surrogate)	Ajoute HTML_element en tant que source à l'objet `drag`. Attribue à la source un identifiant de glisser (drag_id). Cette fonction inclut également un paramètre `surrogate` (substitut) permettant d'indiquer le marqueur HTML que vous souhaitez utiliser comme substitut. `surrogate` est un objet vide qui remplace l'objet que l'on est en train de faire glisser. Par défaut, le substitut `surrogate` est une copie de la source. Exemple : drag_obj.addSource("first", _gel("dom_id1"), "<b>This is my surrogate</b>");
removeSource(drag_id)	Supprime la source spécifiée dans le paramètre drag_id.
removeAllSources()	Supprime toutes les sources de l'objet `drag`.
addTarget(DOM_id)	Ajoute une cible à l'objet `drag`. DOM_id correspond à l'identifiant unique de l'élément HTML qui représente la cible ajoutée. Si vous n'indiquez aucun identifiant de glisser, la bibliothèque drag utilise l'identifiant DOM comme identifiant de glisser.
addTarget(drag_id, HTML_element)	Ajoute HTML_element en tant que cible à l'objet `drag`. Attribue à la cible un identifiant de glisser (drag_id).
addTarget(drag_id, HTML_element, priority)	Ajoute HTML_element en tant que cible à l'objet `drag`. Attribue à la cible un identifiant de glisser (drag_id). Le paramètre priority est une valeur numérique définissant une priorité lorsque plusieurs cibles coexistent. La cible portant la priorité la plus élevée est sélectionnée en cas de conflit. La valeur par défaut de la priorité des cibles est définie sur 0. S'il existe deux cibles potentielles, celle dont la priorité est la plus élevée est atteinte. En d'autres termes, une cible de priorité 4 sera sélectionnée avant une cible de priorité 2.
removeTarget(drag_id)	Supprime la cible spécifiée dans le paramètre drag_id.
removeAllTargets()	Supprime toutes les cibles de l'objet `drag`.

Propriétés drag

La bibliothèque drag comprend les propriétés répertoriées ci-dessous. Vous pouvez accéder à ces propriétés par le biais d'un objet drag. Exemple :

if (drag_obj.isDragging == true) {
     // do something
}

Le tableau ci-dessous répertorie les propriétés en lecture seule :

Propriété en lecture seule	Description
isDragging	La valeur est true si l'utilisateur est en train de faire glisser un élément.
hasDragged	La valeur est true si celle du paramètre isDragging est true et que l'utilisateur ait déplacé la souris après avoir maintenu le bouton de la souris appuyé.
surrogate	Pointe vers le substitut actuel.
surrogateInitialX, surrogateInitialY	Position du substitut au départ du glisser.
curSource	Pointe vers la source actuelle. La valeur est null si l'utilisateur n'est pas en train de faire glisser un élément.
curTargetId	Contient l'identifiant de la cible actuelle. La valeur est null si l'utilisateur n'est pas en train de faire glisser un élément.

Le tableau ci-dessous répertorie les propriétés en lecture/écriture. La modification de ces propriétés influence le fonctionnement des opérations de glisser. Ne les modifiez pas lorsqu'un glisser est en cours :

Propriétés en lecture/écriture	Description
leftMargin, rightMargin, topMargin, bottomMargin	Chaque cible est entourée par une marge. Vous pouvez ajuster la sensibilité des cibles en modifiant cette valeur. Par défaut, la marge est de 2 pixels.
surrogateOffsetX, surrogateOffsetY	Modifiez ces valeurs pour décaler légèrement la position du substitut lorsque le glisser débute. La valeur par défaut est égale à 1 pixel. Cette valeur est définie sur 1, et non sur 0, pour que l'utilisateur puisse reconnaítre le début d'un glisser.

Bibliothèque grid

Pour obtenir des informations détaillées sur la bibliothèque grid ainsi que des exemples d'utilisation, consultez la rubrique Grilles.

Pour pouvoir faire appel à la bibliothèque grid, les gadgets doivent inclure la ligne suivante dans le paramètre <ModulePrefs> :

<Require feature="grid" />

Les fonctions de la bibliothèque grid sont résumées ci-dessous.

Fonctions principales requises pour les grilles

L'utilisation de la bibliothèque grid nécessite de mettre en œuvre les fonctions principales (backend) suivantes :

Fonction	Description
`_IGG_getNormalView(index)`	Renvoie le contenu HTML par défaut que la cellule correspondant à `index` doit accueillir lorsque l'utilisateur n'effectue aucun glissé.
`_IGG_isDragSource(index)`	Renvoie une valeur booléenne indiquant si l'élément situé dans l'`index` concerné est une source drag.
`_IGG_isDragTarget(index, sourceIndex)`	Renvoie une valeur booléenne indiquant si l'élément correspondant à `index` est une cible drag lorsque `sourceIndex` est une source drag.

Fonctions principales d'affichage des grilles

Par défaut, la bibliothèque grid appel la fonction getNormalView() pour afficher le contenu d'une cellule. Toutefois, vous pouvez faire réagir le contenu d'une cellule et déterminer son apparence en fonction du type de glissé effectué par l'utilisateur. Pour cela, vous devez associer les fonctions facultatives suivantes à votre objet principal.

Fonction	Description
`_IGG_getSurrogateView(index)`	Renvoie le contenu HTML du substitut (surrogate apparaissant sous le pointeur de la souris) lorsque l'utilisateur fait glisser le contenu correspondant à `index`.
`_IGG_getSourceView(source, target)`	Renvoie le contenu HTML de la cellule constituant la `source` lorsque l'utilisateur effectue un glissé. Si le pointeur de la souris passe sur une cible, `target` (la cible) contient l'index de la cible. Dans le cas contraire, il contient -1.
`_IGG_getTargetView(target, source)`	Renvoie le contenu HTML de la cellule lorsque celle-ci est la cible (`target`) et que l'utilisateur effectue un glissé. `source` correspond à l'index de la source.
`_IGG_getPossibleTargetView(potential_target, source)`	Renvoie le contenu HTML de la cellule lorsque celle-ci est une cible potentielle (`potential_target`), et non une cible, et que l'utilisateur effectue un glissé. `source` correspond à l'index de la source.
`_IGG_getDragView(index, source)`	Renvoie le contenu HTML de la cellule correspondant à `index` lorsqu'elle ne constitue ni une cible potentielle, ni une source et que l'utilisateur effectue un glissé. `source` correspond à l'index de la source.

Fonctions principales de réaction des grilles

La bibliothèque grid fournit les fonctions suivantes pour permettre à votre gadget de répondre aux clics et aux opérations de glisser effectués à l'aide de la souris :

Fonction	Description
`_IGG_handleClick(source)`	Appelée lorsque l'utilisateur a cliqué sur la `source` (l'utilisateur a cliqué, puis relâché le bouton sans faire glisser la souris).
`_IGG_handleDragStart(source)`	Appelée lorsque l'utilisateur à cliqué sur la `source`, puis a commencé un mouvement de glisser.
`_IGG_handleDrag(source, target)`	Appelée lorsque l'utilisateur a terminé une action de glisser. Si l'utilisateur s'est arrêté sur une cible valide, `target` contient alors l'index de la cible. Dans le cas contraire, il contient la valeur -1. Notez que l'appel de la fonction `_IGG_handleClick()` provoque également l'appel de la fonction `_IGG_handleDrag()`. Ainsi, en fonction de l'application, il peut être préférable d'utiliser uniquement la fonction `_IGG_handleDrag()`.

Fonctions principales de rappel des grilles

Les fonctions de rappel principales sont créées automatiquement dans votre objet principal. La bibliothèque grid appelle ces fonctions autant que nécessaire, mais vous pouvez définir vous-même des appels, lorsque les modifications de vos données sont provoquées par d'autres processus que les opérations de glisser des utilisateurs. Cette bibliothèque comprend les fonctions de rappel principales (backend callbacks) suivantes :

Fonction	Description
`_IGG_refreshCell(index)`	Actualise l'affichage de la cellule correspondant à `index`.
`_IGG_refreshAll()`	Actualise l'affichage de toutes les cellules. Notez que cette opération peut prendre du temps, notamment si vous utilisez une grande grille complexe.

Propriétés de l'objet grid

La bibliothèque grid inclut des champs et des fonctions relatifs à l'objet grid qui sont répertoriés ci-dessous. Vous pouvez accéder à ces propriétés par le biais d'un objet grid. Exemple :

document.getElementById("summary").innerHTML = "In the grid " + mygrid.name + 
   " the HTML content of the source is " + mygrid.getCellValue(mygrid.source);

Les champs et les fonctions auxquels vous avez accès à l'aide d'un objet grid sont les suivants :

Fonction	Description
`initDragging()`	Active la fonction de glisser dans la grille.
`dataObject`	Objet principal.
`name`	Chaíne préfixe de tous les identifiants DOM créés par la grille.
`height, width`	Paramètres de hauteur et de largeur de la grille.
`maxIndex`	Valeur de cellule la plus grande figurant dans l'index. Elle correspond généralement à lignes*colonnes-1, mais peut être supérieure si vous créez des cellules supplémentaires avec la fonction `getCell()`.
`source`	Index de la source actuelle. Sa valeur est -1 si l'utilisateur n'est pas en train de faire glisser un élément.
`target`	Index de la cible actuelle. Sa valeur est -1 si l'utilisateur n'est pas en train de faire glisser un élément ou que le pointeur n'est pas situé au-dessus d'une cible.
`getCellName(index)`	Renvoie l'identifiant DOM de l'élément SPAN correspondant au contenu de la cellule située dans `index`.
`getCellTDID(index)`	Renvoie l'identifiant DOM de l'élément TD contenant l'élément SPAN correspondant au contenu de la cellule située dans `index`.
`getCellValue(index)`	Renvoie le contenu HTML de la cellule correspondant à `index`.
`getTable()`	Renvoie le tableau DOM contenant la cellule.
`getCell(index)`	Renvoie la cellule correspondant à `index`. Si l'index est < 0, la valeur null est renvoyée. Si l'index est > à maxIndex, une nouvelle cellule portant ce numéro est créée. Cela vous permet de créer des cellules en dehors du tableau.
`makeNewTable()`	Remanie le tableau DOM HTML dans son ensemble. Notez qu'il vous faudra probablement relier ce nouveau tableau à votre arborescence DOM et que cela peut ralentir votre page, car l'ancien tableau devra certainement être traité par le biais d'un ramasse-miettes.
`table`	Accès direct au tableau DOM HTML. Vous pouvez utiliser la fonction getTable() au lieu de modifier ce paramètre.
`cells`	Accès direct au tableau contenant les cellules DOM. Vous pouvez utiliser la fonction `getCell()` au lieu de modifier ce paramètre.
`dragHandler`	L'objet `_IG_Drag` (voir Bibliothèque drag) permettant de gérer les opérations de glisser dans la grille.
`setXMapper, setYMapper`	Modifie les mappers dans l'objet interne `_IG_Drag`.
`isRightButton`	Renvoie la valeur `true` si l'utilisateur a appuyé sur le bouton droit lors du dernier glisser.
`refreshCell(index)`	Actualise la cellule correspondant à `index`. Cette fonction équivaut à la fonction de rappel `_IGG_refreshCell()`.
`refreshAll()`	Actualise toutes les cellules. Cette fonction équivaut à la fonction de rappel `_IGG_refreshAll()`.
`refreshDragSources()`	Oblige à recalculer toutes les cellules pour déterminer celles qui sont des sources, puis les enregistre avec l'objet drag sous-jacent.
`refreshDragTargets(sourceIndex)`	Actualise toutes les cellules constituant des cibles pour la source correspondant à `sourceIndex`. Notez que cette opération ne permet pas d'enregistrer les cibles avec l'objet drag sous-jacent.
`refreshDragNonTargets(sourceIndex)`	Actualise toutes les cellules qui ne constituent pas des cibles pour la source correspondant à `sourceIndex`.
`addDragSource(index)`	Ajoute une cellule parmi les sources valides (même si la fonction `isDragSource` renvoie la valeur `false`).
`removeDragSource(index)`	Supprime une cellule parmi les sources valides (même si la fonction `isDragSource` renvoie la valeur `true`).
`removeDragSource(index)`	Supprime une cellule parmi les sources valides (même si la fonction `isDragSource` renvoie la valeur `true`).
`calculateDragTargets(sourceIndex)`	Enregistre toutes les cibles de la source correspondant à `sourceIndex` avec l'objet drag sous-jacent.

Fonctions principales avancées

Si vous remplacez dragHandler dans l'objet Grid, il peut arriver que l'utilisateur fasse glisser un élément que la grille n'est pas en mesure de gérer. Dans de tels cas, la grille tente d'appeler ces fonctions dans votre objet principal lorsqu'elles existent. Consultez la rubrique Bibliothèque drag pour plus d'informations sur leur fonctionnement.

_IGG_handleOnDragStart(object)
_IGG_handleOnDragTargetHit(object)
_IGG_handleOnDragTargetLost()
_IGG_handleOnDragEnd(object, object)
_IGG_handleOnDragClick(object)

Bibliothèque MiniMessage

Pour obtenir des informations détaillées sur la bibliothèque MiniMessage, consultez la rubrique Minimessages.

Pour pouvoir faire appel à la bibliothèque MiniMessage, les gadgets doivent inclure la ligne suivante dans le paramètre <ModulePrefs> :

<Require feature="minimessage" />

Le tableau suivant répertorie les méthodes MiniMessage et les fonctions pouvant être appelées sur un objet MiniMessage une fois que ce dernier est instancié :

Fonction	Description
_IG_MiniMessage(moduleId, opt_container)	Méthode MiniMessage. Instancie un nouvelle objet MiniMessage. Utilise l'identifiant du gadget, __MODULE_ID__, en tant que paramètre. Il est possible d'inclure un paramètre opt_container dans la méthode, pour spécifier un élément HTML (généralement une balise <div>) dans lequel insérer les messages. En l'absence du paramètre opt_container, un conteneur de messages par défaut est créé automatiquement et placé en haut du gadget. Par exemple : var mini = new _IG_MiniMessage(__MODULE_ID__, _gel("messageContainer"));
createDismissibleMessage(msg, opt_callback)	Crée un message temporaire. Le paramètre msg représente une chaíne ou un élément HTML. Le message est associé à un lien [x] sur lequel l'utilisateur peut cliquer pour fermer le message. Lorsque le message se ferme, il est supprimé du modèle DOM et la fonction de rappel facultative opt_callback est appelée. Si le rappel renvoie la valeur false, la fermeture est annulée. Par exemple : mini.createDismissibleMessage("Loading message"); mini.createDismissibleMessage(_gel("loading"));
createTimerMessage(msg, seconds, opt_callback)	Crée un message instantané qui reste affiché durant le nombre seconds défini. Le paramètre msg représente une chaíne ou un élément HTML. À la fin du temps imparti, le message débute le processus de fermeture et la fonction de rappel opt_callback s'exécute. Si le rappel renvoie la valeur false, la fermeture est annulée. Par exemple : mini.createTimerMessage("Your account has been updated.", 5);
createStaticMessage(msg)	Crée un message statique qui reste affiché jusqu'à une fermeture programmée à l'aide de la fonction dismissMessage(msg). Le paramètre msg représente une chaíne ou un élément HTML. Exemple : var loadMsg = mini.createStaticMessage("Loading content...");
dismissMessage(msg)	Ferme le message correspondant à msg. Cette fonction est la seule qui permette de fermer un message statique. Par exemple : var loadMsg = mini.createStaticMessage("Loading content..."); mini.dismissMessage(loadMsg);

Bibliothèque analytics

Pour obtenir des informations détaillées sur la bibliothèque analytics, ainsi que des exemples d'utilisation, consultez la rubrique Utilisation de Google Analytics.

Pour pouvoir faire appel à la bibliothèque analytics, les gadgets doivent inclure la ligne suivante dans le paramètre <ModulePrefs> :

<Require feature="analytics" />

La bibliothèque analytics comprend la fonction suivante :

Fonction	Description
_IG_Analytics(id, path)	Enregistre une consultation de page unique dans un seul compte Google Analytics. Cette fonction prend en charge plusieurs appels dans un même gadget. Le paramètre id représente un identifiant de compte Google Analytics. Le paramètre path représente le chemin d'accès des consultations virtuelles de pages enregistrées par Google Analytics pour chaque appel. Définissez-le avec un nom unique qui vous permettra de différencier les consultations de page de vos différents gadgets dans vos rapports Analytics. Exemple : _IG_Analytics("UA_000000-0", "/weathergadget");

Fonction

Description

_IG_Analytics(id, path)

Enregistre une consultation de page unique dans un seul compte Google Analytics. Cette fonction prend en charge plusieurs appels dans un même gadget.

Le paramètre id représente un identifiant de compte Google Analytics.

Le paramètre path représente le chemin d'accès des consultations virtuelles de pages enregistrées par Google Analytics pour chaque appel. Définissez-le avec un nom unique qui vous permettra de différencier les consultations de page de vos différents gadgets dans vos rapports Analytics.

Exemple :

_IG_Analytics("UA_000000-0", "/weathergadget");

Paramètres de requête

Lorsqu'une requête pour obtenir l'URL du gadget est formulée depuis une page iGoogle, les paramètres sont ajoutés à la fin de la requête pour constituer une méthode GET. Cela est uniquement valable lorsque votre type de contenu est défini sur "url". Consultez la rubrique URL pour plus d'informations. Ces paramètres peuvent être lus par un gadget utilisant JavaScript ou par une application Web côté serveur. Pour consulter un exemple, accédez à la rubrique URL.

Les paramètres transmis sont répertoriés dans le tableau suivant :

Nom	Description
up_<name>	Préférence utilisateur accompagnée de sa valeur. Pour chacune des préférences utilisateur, la paire nom-valeur est transmise en tant que paramètre à l'aide du format suivant : `&up_<name>=<value>` Supposons, par exemple, que vous ayez défini un paramètre de code postal appelé `zp` et que l'utilisateur lui ait attribué la valeur 94306. Ce dernier serait transmis au niveau de l'URL de la manière suivante : `&up_zp=94306`
lang	Préférence linguistique sélectionnée par l'utilisateur (dans son navigateur).
country	Pays de résidence de l'utilisateur (définie dans son compte Google).

Retour au début

API Google Gadgets - Guide du développeur

Informations

API Google Gadgets - Références

Sommaire

Structure XML

Caractéristiques du gadget

Utilisation des bibliothèques

Définition de paramètres régionaux

Définition des paramètres de compatibilité

Préférences utilisateur

Type de données enum

Section de contenu

Bibliothèques JavaScript

Bibliothèque principale JavaScript

Bibliothèques de fonctions JavaScript spécifiques

Bibliothèque setprefs

Bibliothèque dynamic-height

Bibliothèque tabs

Bibliothèque drag

Propriétés drag

Bibliothèque grid

Fonctions principales requises pour les grilles

Fonctions principales d'affichage des grilles

Fonctions principales de réaction des grilles

Fonctions principales de rappel des grilles

Propriétés de l'objet grid

Fonctions principales avancées

Bibliothèque MiniMessage

Bibliothèque analytics

Paramètres de requête