Ce document décrit comment ajouter divers éléments d'interface ŕ votre gadget.
Par défaut, la hauteur des gadgets est de 200 pixels. Mais vous pouvez utiliser l'attribut height="nn" dans le paramčtre <ModulePrefs> afin de définir une hauteur fixe supérieure ou inférieure ŕ la hauteur par défaut. Insérez l'attribut scrolling="true" dans le paramčtre <ModulePrefs> pour ajouter une barre de défilement verticale ŕ votre gadget lorsque la hauteur de son contenu dépasse la hauteur définie.
Dans certains cas, les gadgets doivent gérer leur hauteur de maničre dynamique. Supposons, par exemple, que votre gadget présente une liste dont la longueur variable nécessite d'augmenter ou de réduire sa hauteur. Votre gadget s'allonge ŕ mesure que les utilisateurs ajoutent des éléments sur la liste. Lorsqu'ils effacent leur liste, le gadget retrouve sa taille initiale. Voici comment peut se présenter un tel gadget :
Pour que votre gadget puisse se redimensionner de lui-męme, vous devez ajouter les éléments suivants ŕ ses spécifications :
Remarque : La fonction de hauteur dynamique est uniquement disponible sur la page iGoogle, elle ne fonctionne pas dans le cadre d'une syndication ni lorsqu'un gadget est inséré sur d'autres sites Google.
Voici, par exemple, les spécifications requises pour le gadget Liste d'achats :
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="My Grocery List"
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) {
_gel('content_div').innerHTML = html;
// Tells gadget to resize itself
_IG_AdjustIFrameHeight();
}
</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>
Pour obtenir des instructions permettant de tester la largeur et la hauteur d'un gadget, consultez la rubrique Test de largeur et de hauteur.
Vous pouvez utiliser la bibliothčque tabs pour insérer des onglets dans l'interface de votre gadget. Pour cela, les spécifications de votre gadget doivent inclure au minimum les éléments suivants :
Inclure la bibliothčque setprefs est également une pratique courante qui permet aux gadgets de toujours enregistrer le dernier onglet consulté par les utilisateurs. Vous ętes nombreux ŕ souhaiter que votre gadget restitue l'onglet sélectionné par l'internaute en dernier lieu. De cette maničre, votre gadget charge automatiquement l'onglet enregistré lorsqu'un utilisateur retourne sur la page d'accueil aprčs l'avoir fermée. Pour bénéficier de cette fonctionnalité, vous devez insérer deux lignes de code dans les spécifications de votre gadget :
<Require feature="setprefs"/> ... <UserPref name="selectedTab" datatype="hidden"/>
Chaque onglet est associé ŕ un identifiant unique qui correspond ŕ une balise <div>. Cette <div> balise sert ŕ indiquer le contenu de chaque onglet. Si vous ne fournissez pas de balise <div>, la bibliothčque tabs en génčre une automatiquement.
Pour ajouter un onglet et l'associer ŕ un contenu, vous pouvez procéder de l'une des maničres suivantes :
Technique n°1 : Associez un identifiant ŕ l'onglet lors de sa création et utilisez-le pour insérer son contenu dans la balise <div> correspondante :
var one_Id = tabs.addTab("One");
_gel(one_Id).innerHTML = "Content for tab One.";
Technique n°2 : Créez votre onglet, puis ajoutez une balise <div> correspondante dans la partie HTML du gadget afin d'y insérer un contenu statique :
tabs.addTab("Two", "two_id");
...
</script>
<div id="two_id" style="display:none">Content for tab Two.</div>
Technique n°3 : Créez votre onglet, puis ajoutez une balise <div> correspondante dans la partie HTML du gadget afin d'y insérer un contenu statique. Utilisez ensuite la fonction de rappel (callback) pour ajouter un contenu dynamique au sein du contenu statique :
tabs.addTab("Three", "three_id", callback);
...
function callback(tabId) {
var p = document.createElement("p");
p.innerHTML = "This is dynamic content generated in callback.";
_gel(tabId).appendChild(p);
}
...
</script>
<div id="three_id" style="display:none">This is static content for tab Three.</div>
Technique n°4 : Utilisez la fonction addDynamicTab() pour insérer ŕ la fois votre onglet en indiquant son nom et la fonction de rappel permettant de créer un contenu dynamique. Dans ce cas, la bibliothčque tabs crée une balise <div> automatiquement :
tabs.addDynamicTab("My_Tab", callback);
...
function callback(tabId)
{
// do something
_gel(tabId).innerHTML = [something];
}
Vous trouverez un exemple de cette quatričme technique, utilisant la fonction de rappel pour créer un contenu dynamique, dans la rubrique Création de contenu dynamique. Voici un exemple de gadget illustrant les trois premičres méthodes permettant de créer des onglets et d'y insérer un contenu :
Vous trouverez ci-dessous les spécifications correspondant ŕ ce gadget :
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Simple Tabs" height="140">
<Require feature="tabs" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
function init() {
// Initialize tabs, designate the tab named "Two" as
// the tab selected by default.
var tabs = new _IG_Tabs(__MODULE_ID__, "Two");
// 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("One");
_gel(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", "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", "three_id", callback);
}
// Callback that adds dynamic content to the static content already
// in tab Three.
function callback(tabId) {
var p = document.createElement("p");
p.innerHTML = "This is dynamic content generated in callback.";
_gel(tabId).appendChild(p);
}
// Call init function to initialize and display tabs.
_IG_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>
Dans l'exemple ci-dessus la fonction de rappel est utilisée pour ajouter un contenu statique ŕ un onglet. Toutefois, cette fonction de rappel sert généralement ŕ créer un contenu dynamique.
Le gadget présenté ci-dessous ŕ titre d'exemple utilise la fonction de rappel pour fournir un contenu actualisé ŕ chaque fois que l'utilisateur clique sur un nouvel onglet. Le rappel permet d'afficher la date et l'heure actuelle ŕ la seconde prčs. Par conséquent, la valeur change ŕ chaque fois que l'on passe d'un onglet ŕ l'autre.
Ce gadget fait appel ŕ la fonction addDynamicTab(tab_name, callback_function). Cette fonction indique ŕ la bibliothčque tabs de créer un onglet intitulé tab_name et d'appeler la fonction callback_function pour extraire le contenu de l'onglet ŕ partir de la balise <div> correspondante".
Voici comment se présente un tel gadget :
Vous trouverez ci-dessous les spécifications correspondant ŕ ce gadget :
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Dynamic Tabs">
<Require feature="tabs" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
function init() {
// Initialize tabs.
var tabs = new _IG_Tabs(__MODULE_ID__);
// Technique #4: When you use addDynamicTab, the tab's content
// is dynamically generated through the callback function.
tabs.addDynamicTab("One", callback);
tabs.addDynamicTab("Two", callback);
tabs.addDynamicTab("Three", callback);
}
// Callback that displays the current date-time whenever a
// new tab is clicked.
function callback(tabId) {
var date = new Date();
_gel(tabId).innerHTML = date.toLocaleString();
}
// Call init function to initialize and display tabs.
_IG_RegisterOnloadHandler(init);
</script>
]]>
</Content>
</Module>
Cliquez ici pour consulter un exemple plus complexe et réaliste.
La bibliothčque tabs de l'API comprend également des fonctions permettant de gérer les onglets par le biais d'un index. Les onglets sont indexés ŕ l'aide de numéros de 0 ŕ n, oů 0 correspond au premier onglet. Par exemple, si vous utilisez 3 onglets, les numéros associés seront 0, 1 et 2. Ces numéros peuvent servir ŕ programmer la sélection d'un onglet et ŕ inverser les positions de deux onglets.
Notez que si l'identifiant d'un onglet est constant, son index ne l'est pas. Si vous déplacez le troisičme onglet en premičre position, par exemple, le numéro associé passe de 2 ŕ 0.
Voici un exemple de programmation permettant de sélectionner un onglet. Cet extrait créé un lien. Lorsque l'utilisateur clique sur ce dernier, le second onglet apparaít, comme si l'utilisateur avait cliqué sur l'onglet lui-męme :
<script>
...
function selectTab() {
tabs.setSelectedTab(1);
}
</script>
<a href="javascript:void(0)" onclick="selectTab()">Select Second Tab</a>
Voici un exemple de programmation permettant de déplacer un onglet. Cet extrait créé un lien. Lorsque l'utilisateur clique sur ce dernier, les positions du premier et du second onglet sur le gadget sont inversées :
<script>
...
function switchTabs() {
tabs.moveTab(0, 1);
}
</script>
<a href="javascript:void(0)" onclick="switchTabs()">Switch Tabs</a>
La feuille de style des onglets vous est présentée sur la page http://www.google.com/ig/tablib.css. Cette derničre définit les classes applicables aux éléments HTML qui définissent les onglets.
Vous pouvez utiliser les classes CSS suivantes pour remplacer les paramčtres par défaut et ainsi modifier l'apparence de vos onglets.
| Classe CSS | Description |
|---|---|
| .tablib_table__MODULE_ID__ | S'applique au tableau HTML contenant les onglets. |
| .tablib_selected__MODULE_ID__ | S'applique ŕ l'onglet sélectionné. |
| .tablib_unselected__MODULE_ID__ | S'applique aux onglets qui ne sont pas sélectionnés. |
| .tablib_spacerTab__MODULE_ID__ | S'applique aux éléments de séparation entre les onglets. |
| .tablib_emptyTab__MODULE_ID__ | Contrôle les espacements de début et de fin autour des onglets. |
Remarque : Veillez ŕ inclure la mention __MODULE_ID__ lorsque vous remplacez une classe particuličre. Dans le cas contraire, les onglets des gadgets intégrés n'apparaítront pas si vous remplacez une rčgle prioritaire.
L'exemple suivant vous indique comment remplacer des paramčtres CSS dans votre gadget. Pour obtenir la liste des classes et paramčtres que vous pouvez remplacer, consultez la page http://www.google.com/ig/tablib.css.
<![CDATA[
<style type="text/css">
.tablib_selected__MODULE_ID__ { color: #FF0000; }
.tablib_unselected__MODULE_ID__ { color: #660099; }
.tablib_table__MODULE_ID__ { font-size:20px; }
.tablib_emptyTab__MODULE_ID__ { padding:2px 5px; }
.tablib_spacerTab__MODULE_ID__ { padding:0px 5px; }
</style>
<script...>
Vous pouvez utiliser la bibliothčque drag afin d'intégrer la fonction de glisser dans votre gadget. Pour cela, les spécifications de votre gadget doivent inclure au minimum les éléments suivants :
La bibliothčque drag donne aux utilisateurs la possibilité de faire glisser et de déposer des éléments HTML dans l'interface de leurs gadgets. Par exemple, essayez de faire glisser les divers éléments du texte et de les déposer sur la photo dans le gadget ci-dessous :
Cet exemple illustre les principes de base de la bibliothčque drag :
Lorsque le bouton de la souris est maintenu enfoncé, votre gadget peut reconnaítre les cibles sur lesquelles l'utilisateur passe avec le pointeur de sa souris, détecter le moment oů il relâche le bouton et ainsi répondre ŕ cet événement en modifiant le code HTML en conséquence.
La bibliothčque drag utilise principalement les fonctions de rappel répertoriées dans le tableau suivant :
| Fonction de rappel (callback) | 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. |
Pour consulter un récapitulatif des fonctions disponibles dans la bibliothčque drag, reportez-vous ŕ la page des références .
Voici les spécifications du gadget présenté plus haut ŕ titre d'exemple. Pour utiliser la bibliothčque drag, vous devez inclure une balise <Require feature="drag"/> dans le paramčtre <ModulePrefs>. Notez que chaque élément HTML est associé ŕ un identifiant DOM unique. Pour plus d'informations sur les identifiants et les diverses méthodes permettant d'ajouter des sources et des cibles, consultez la rubrique Ajout et suppression de sources et de cibles.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Special Effects" scrolling="true" height="320">
<Require feature="drag" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<table border=0>
<tr>
<td>
<p id="id1" style="font-weight:bold;">original</p>
<p id="id2" style="color:brown; font-weight:bold;">sepia</p>
<p id="id3" style="color:red; font-weight:bold;">red</p>
<p id="id4" style="color:green; font-weight:bold;">green</p>
</td>
<td id="id5" style="padding-left:60;">
<img src="http://doc.examples.googlepages.com/Rowan-small.gif" alt="Rowan"/>
</td>
</tr>
</table>
<script type="text/javascript">
// Preload the images
var images = new Object();
images["id1"] = new Image();
images["id1"].src = "http://doc.examples.googlepages.com/Rowan-small.gif";
images["id2"] = new Image();
images["id2"].src = "http://doc.examples.googlepages.com/Rowan-small-sepia.gif";
images["id3"] = new Image();
images["id3"].src = "http://doc.examples.googlepages.com/Rowan-small-red.gif";
images["id4"] = new Image();
images["id4"].src = "http://doc.examples.googlepages.com/Rowan-small-green.gif";
// drag constructor
var drag_obj = new _IG_Drag();
// Add sources and target. In this example, there is one target: the photo.
drag_obj.addSource("original", _gel("id1"), "<p style=color:orange;>Restore original...</p>");
drag_obj.addSource("sepia", _gel("id2"), "<p style=color:orange;>Change to sepia...</p>");
drag_obj.addSource("red", _gel("id3"), "<p style=color:orange;>Change to red...</p>");
drag_obj.addSource("green", _gel("id4"), "<p style=color:orange;>Change to green...</p>");
drag_obj.addTarget("image", _gel("id5"));
// When user drags source onto target and releases it,
// display appropriate photo.
drag_obj.onDragEnd = function(source, target) {
if (target == null) return;
target.innerHTML = "<img src='" + images[source.id].src + "'/>";
}
</script>
]]>
</Content>
</Module>
L'exemple suivant est plus complexe et permet d'intervertir les emplacements des différents éléments HTML :
Vous trouverez ci-dessous les spécifications correspondant ŕ l'exemple précédent. Elles indiquent comment utiliser toutes les fonctions de rappel, ainsi que les propriétés _IG_Drag_surrogateOffset... qui permettent de préciser l'emplacement du substitut au moment oů le glisser débute. Dans cet exemple, vous pouvez intervertir les emplacements des éléments HTML. Par conséquent, chaque élément tient ŕ la fois le rôle de source et celui de cible.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Drag Example" scrolling="true">
<Require feature="drag" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<table border=0><tr>
<td id="demo1">
Try dragging these
</td><td id="demo2">
<img src="http://doc.examples.googlepages.com/different.gif" alt="different"/>
</td>
</tr><tr>
<td id="demo3">
<ul>
<li>HTML
<li>elements
<li>around
</ul>
</td><td id="demo4">
<table border=1><tr>
<td>on</td>
<td>this</td>
<td>page.</td>
</tr></table>
</td>
</tr></table>
<script type="text/javascript">
// drag constructor
var demo = new _IG_Drag();
// Add sources and targets, and assign them id's.
demo.addSource("demo1");
demo.addSource("demo2");
demo.addSource("demo3");
demo.addSource("demo4");
demo.addTarget("demo1");
demo.addTarget("demo2");
demo.addTarget("demo3");
demo.addTarget("demo4");
// Set location of where each surrogate is at the start of a drag.
_gel("demo1")._IG_Drag_surrogateOffsetY = 20;
_gel("demo2")._IG_Drag_surrogateOffsetY = 0;
_gel("demo3")._IG_Drag_surrogateOffsetY = -10;
_gel("demo4")._IG_Drag_surrogateOffsetY = 20;
// Render initial display of HTML elements
var data = new Array();
data[0] = "<B>(swap with this)</B>"
data[1] = _gel("demo1").innerHTML;
data[2] = _gel("demo2").innerHTML;
data[3] = _gel("demo3").innerHTML;
data[4] = _gel("demo4").innerHTML;
var currentSource = null;
// When drag starts, selected source HTML element is passed in callback;
// here is is assigned as value to currentSource.
demo.onDragStart = function (object) {
currentSource = object;
}
// When user drags source object onto a target object, display text
// "swap with this"
demo.onDragTargetHit = function (object, old_object) {
demo.onDragTargetLost(old_object);
if (object != currentSource)
object.innerHTML = data[0];
}
// Called when drag is underway and user isn't on a target
demo.onDragTargetLost = function (object) {
if (object == null) return;
if (object.id == "demo1") object.innerHTML = data[1];
if (object.id == "demo2") object.innerHTML = data[2];
if (object.id == "demo3") object.innerHTML = data[3];
if (object.id == "demo4") object.innerHTML = data[4];
}
// When user drags source onto target and releases it, swap objects.
// Update surrogate positions.
demo.onDragEnd = function(source, target) {
if (target == null) return;
var src; var trg;
for (var i=1; i!=5; ++i) {
if (source.id == "demo" + i) src = i;
if (target.id == "demo" + i) trg = i;
}
var temp = data[src];
data[src] = data[trg];
data[trg] = temp;
_gel("demo" + src).innerHTML = data[src];
_gel("demo" + trg).innerHTML = data[trg];
temp = _gel("demo" + src)._IG_Drag_surrogateOffsetY;
_gel("demo" + src)._IG_Drag_surrogateOffsetY = _gel("demo" + trg)._IG_Drag_surrogateOffsetY;
_gel("demo" + trg)._IG_Drag_surrogateOffsetY = temp;
}
</script>
]]>
</Content>
</Module>
Comme le montrent les exemples ci-dessus, vous pouvez créer des objets ŕ faire glisser ŕ l'aide de la méthode _IG_Drag() :
var drag_obj = new _IG_Drag();
En observant ces exemples, vous constaterez qu'il existe plusieurs maničres de créer des sources et des cibles. Ces derničres sont des éléments HTML qui possčdent un identifiant drag (identifiant qui les désigne dans la bibliothčque drag de l'API) et un identifiant DOM (identifiant qui les désigne dans JavaScript). Si vous ne spécifiez aucun identifiant drag lorsque vous ajoutez une source ou une cible, l'identifiant DOM sera également utilisé comme identifiant drag. Prenons, par exemple, cette déclaration d'élément HTML dans laquelle l'élément <h2> est associé ŕ l'identifiant JavaScript "js-id1" :
<h2 id="dom-id1">My First Element</h2>
Cet élément HTML peut ętre désigné comme une source de l'une des maničres suivantes :
// DOM ID becomes the drag ID
drag_obj.addSource("dom_id1");
// Here the element is given a drag ID "first" which is different from the DOM ID.
drag_obj.addSource("first", _gel("dom_id1")); // A custom surrogate is included drag_obj.addSource("first", _gel("dom_id1"), "<b>This is my surrogate</b>");
Pour consulter la liste des fonctions permettant d'ajouter et de supprimer une source ou une cible, consultez la page des références.
Le terme minimessage désigne un message qui est présenté de façon temporaire aux utilisateurs ŕ l'intérieur d'un gadget. Les minimessages sont conçus pour ętre fermés de maničre programmée ou ŕ l'initiative de l'utilisateur. Les principaux types de minimessages sont les suivants :
Pour utiliser des minimessages, vous devez inclure au minimum les éléments suivants dans les spécifications de votre gadget :
Ces minimessages peuvent s'avérer utiles dans les situations suivantes :
Cliquez ici pour voir un exemple de gadget ŕ minimessages utilisant la plupart des techniques présentées dans cette rubrique.
Pour voir des exemples concrets de gadgets utilisant la bibliothčque de minimessages, consultez Google Video et le Gadget du développeur.
Les principales étapes permettant d'ajouter un minimessage ŕ votre gadget sont simples :
1. Importez la bibliothčque MiniMessage :
<Require feature="minimessage"/>
2. Instanciez un nouvel objet minimessage ŕ l'aide de la méthode _IG_MiniMessage() :
var msg = new _IG_MiniMessage(__MODULE_ID__);
Dans la plupart des cas, vous souhaiterez en faire un objet global unique, accessible ŕ partir de tous les champs de définition.
3. Créez le texte de votre nouveau minimessage :
msg.createDismissibleMessage("Please close me when you're done reading me.");
Cette ligne crée un message préformaté pouvant ętre fermé ŕ l'aide du signe [x] situé en haut de votre gadget. Lorsque l'utilisateur clique sur le signe [x], le message disparaít.
C'est aussi simple que cela ! Vous venez de créer l'un des nombreux types de message temporaire.
Par défaut, les messages sont placés dans des éléments HTML, appelés conteneurs, en haut du gadget. Dans le cas de messages successifs, chacun d'eux vient s'ajouter en dessous du message qui le précčde. Vous pouvez cependant modifier ce mode de fonctionnement pour un message particulier ou pour tous les messages.
Vous pouvez modifier l'emplacement par défaut du conteneur de messages en indiquant un élément HTML dans la méthode, de préférence ŕ l'aide d'une balise <div>. Cet élément devient alors le conteneur dans lequel les messages sont insérés et affichés.
Dans cet extrait par exemple, le message <h3> "I'm on top now!" apparaít en haut du gadget. Les minimessages sont affichés en dessous de ce dernier dans l'élément messageBox défini par la balise <div> selon l'ordre dans lequel ils ont été ajoutés.
<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 _IG_MiniMessage(__MODULE_ID__, _gel("messageBox")); msg.createDismissibleMessage("I'm the first message."); msg.createDismissibleMessage("I'm the second message."); msg.createDismissibleMessage("I'm at the bottom."); </script>
Vous pouvez choisir l'emplacement oů s'affiche un message temporaire et ainsi empęcher son insertion dans le conteneur de messages. Pour ce faire, vous devez définir votre message dans la section HTML du gadget, puis utiliser l'élément HTML correspondant (de préférence ŕ l'aide d'une balise <div>) comme premier paramčtre dans la méthode createDismissibleMessage().
Dans cet extrait par exemple, le message est affiché dans l'élément status défini par la balise <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 _IG_MiniMessage(__MODULE_ID__); // Pass the HTML element to createDismissableMessage() to indicate // where the message should be displayed. msg.createDismissibleMessage(_gel("status")); </script>
Dans certains cas, vous aurez besoin de créer des messages temporaires ŕ l'aide des méthodes DOM HTML. Le message n'existant pas dans le modčle DOM, il est inséré par défaut dans le conteneur de messages.
Exemple :
<script type="text/javascript">
var msg = new _IG_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>
Les messages instantanés sont des messages préformatés qui disparaissent aprčs un laps de temps défini. La fonction createTimerMessage() nécessite d'entrer deux paramčtres : le message lui-męme et le nombre de secondes correspondant au temps d'affichage du message. Exemple :
var msg = new _IG_MiniMessage(__MODULE_ID__);
msg.createTimerMessage("I'm going to disappear in 5 seconds.", 5);
Les messages statiques sont des messages préformatés dont la fermeture doit ętre programmée ŕ l'aide de la fonction dismissMessage(). Cela permet d'afficher des notifications pour informer l'utilisateur des tâches exécutées par le gadget en arričre-plan, l'extraction d'un contenu par exemple.
Dans l'exemple ci-dessous, un message statique est affiché pour indiquer ŕ l'utilisateur qu'une récupération est en cours. Le message s'efface une fois la récupération terminée :
<div id="loading">Fetching content...</div>
<script type="text/javascript">
var msg = new _IG_MiniMessage(__MODULE_ID__);
var loadMessage = msg.createStaticMessage(_gel("loading"));
_IG_FetchXmlContent('http://www.google.com/', function(responseText)
{
alert(responseText.substr(0,400));
msg.dismissMessage(loadMessage);
});
</script>
Vous pouvez modifier l'apparence par défaut des minimessages de deux maničres différentes :
Pour modifier le style d'un message, utilisez les fonctions DOM. Lorsque vous créez un message temporaire, un élément HTML lui est associé. Vous pouvez ensuite modifier son apparence en définissant les propriétés du style de l'élément HTML renvoyé. Exemple :
<script>
var msg = _IG_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>
Remarque : Notez que la méthode présentée dans cet exemple sert ŕ modifier la couleur de l'ensemble de l'arričre-plan. Si vous modifiez la couleur d'arričre-plan dans la balise <div> contenant le message, vous ne modifiez pas la couleur de l'arričre-plan dans son ensemble.
Pour modifier le style de tous vos messages, utilisez les feuilles de style CSS. La feuille de style des minimessages vous est présentée sur la page http://www.google.com/ig/minimessagelib.css. Cette derničre définit les classes applicables aux éléments HTML qui définissent les minimessages.
Vous pouvez utiliser les classes CSS suivantes pour remplacer les paramčtres par défaut et ainsi modifier l'apparence de vos messages.
| Classe CSS | Description |
|---|---|
.mmlib_table__MODULE_ID__ |
S'applique au tableau HTML contenant le message. |
.mmlib_xlink__MODULE_ID__ |
S'applique au lien [x] permettant de fermer le message. Ce paramčtre s'applique uniquement aux messages temporaires. |
Dans cet exemple, la couleur d'arričre-plan devient bleu marine et le blanc est appliqué au premier plan :
<![CDATA[
<style>
.mmlib_table__MODULE_ID__ {
background-color: #000066;
color: #ffffff;
}
</style>
<script...>
Vous pouvez utiliser la bibliothčque grid pour intégrer la fonction de grille dans votre gadget. Pour cela, les spécifications de votre gadget doivent inclure au minimum les éléments suivants :
La bibliothčque grid fonctionne en association avec la bibliothčque drag pour fournir une interface utilisateur basée sur un tableau. Cet exemple illustre les principes fondamentaux de la bibliothčque grid. Vous pouvez jouer au jeu du morpion en faisant glisser les signes X et O sur l'une des cases de la grille située ŕ droite.
En général, les grilles se composent des éléments suivants :
Voici les principales étapes qui vous permettront d'utiliser la bibliothčque grid :
1. Importez la bibliothčque grid :
<Require feature="grid"/>
2. Créez un objet principal. Vous pouvez également l'initialiser avec un certain nombre de données :
var ttt_backend = new Object();
ttt_backend.data = new Array(".",".","."," ","X",
".",".","."," ","O",
".",".","."," "," ");
L'objet principal est responsable de la gestion du contenu affiché dans la grille. Cet objet doit au moins pouvoir distinguer les phases au cours desquelles les éléments sont cibles de celles oů ils sont sources et reconnaítre leur apparence. Une grille restitue généralement des données qui sont enregistrées dans l'objet principal.
3. Créez un objet new _IG_Grid :
var ttt_grid = new _IG_Grid(ttt_backend, "tictactoegrid", 3, 5);
La méthode _IG_Grid utilise l'objet principal comme premier paramčtre. Le second paramčtre est l'identifiant unique de la grille dont le préfixe correspond au champ identifiant de tous les objets DOM utilisés par la grille. Veillez ŕ ne pas utiliser cette chaíne de caractčres en tant que préfixe pour désigner un autre élément. Le troisičme et le quatričme paramčtres correspondent respectivement au nombre de lignes et de colonnes qui composent la grille.
4. Affichez le contenu de la grille :
grid.getTable().border = 2;
grid.getTable().cellPadding = 5;
_gel("grid_table").appendChild(grid.getTable());
La méthode grid.getTable() renvoie l'objet DOM contenant le tableau HTML de la grille. Vous pouvez modifier ses paramčtres comme vous le feriez pour tout autre tableau DOM HTML. Utilisez la fonction appendChild() pour l'afficher dans votre gadget.
5. Activez la fonction de glisser dans la grille :
grid.initDragging();
6. Mettez en śuvre les fonctions principales :
L'utilisation de la bibliothčque grid nécessite de mettre en śuvre les fonctions principales (backend) suivantes. Cliquez ici pour consulter des exemples de mise en śuvre.
| 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 glisser. |
_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. |
Consultez la page des références pour obtenir une liste complčte des fonctions disponibles dans la bibliothčque grid.
Voici les spécifications requises pour le gadget ci-dessus reproduisant le jeu du morpion :
<?xml version="1.0" encoding="UTF-8" ?>
<Module> <ModulePrefs title="Grid Test" > <Require feature="grid"/> </ModulePrefs> <Content type="html"> <![CDATA[ <span id="ttt_table"></span> <script type="text/javascript"> var ttt_backend = new Object(); ttt_backend.data = new Array(".",".","."," ","X",
".",".","."," ","O",
".",".","."," "," "); // Required backend function. Returns the default HTML content of the cell at index // to be displayed when the user is not dragging. ttt_backend._IGG_getNormalView = function(index) { return this.data[index]; } // Required backend function. Returns a boolean value to indicate whether the element // at index is a drag source. ttt_backend._IGG_isDragSource = function(index) { return (index == 4 /* X */ || index == 9 /* O */); } // Required backend function. Returns a boolean value to indicate whether the element // at index is a drag target when sourceIndex is a drag source. ttt_backend._IGG_isDragTarget = function(index, sourceIndex) { return (index % 5 == 0 || index % 5 == 1 || index % 5 == 2); } ttt_backend._IGG_handleDrag = function(source, target) { this.data[target] = this.data[source]; this._IGG_refreshCell(source); this._IGG_refreshCell(target); this.checkWin(); } ttt_backend.check_three_in_a_row = function(p1, p2, p3) { /* if p1 p2 p3 are all the same and not empty, change the win display. */ if (this.data[p1] == ".") return; if (this.data[p1] != this.data[p2]) return; if (this.data[p1] != this.data[p3]) return; this.data[14] = this.data[p1] + " wins!"; this._IGG_refreshCell(14); } ttt_backend.checkWin = function() { this.check_three_in_a_row(0,1,2); this.check_three_in_a_row(0,5,10); this.check_three_in_a_row(0,6,12); this.check_three_in_a_row(1,6,11); this.check_three_in_a_row(2,6,10); this.check_three_in_a_row(2,7,12); this.check_three_in_a_row(5,6,7); this.check_three_in_a_row(10,11,12); } // Create a new grid object var ttt_grid = new _IG_Grid(ttt_backend, "tictactoegrid", 3, 5); // The function grid.getTable() returns the DOM object that contains the // HTML table for the grid. You can change its settings just like any other // DOM HTML table. ttt_grid.getTable().border = 2; ttt_grid.getTable().cellPadding = 5; // Displays the table in your gadget. _gel("ttt_table").appendChild(ttt_grid.getTable()); // Makes the grid sensitive to dragging. ttt_grid.initDragging(); </script> <div id="content_div"></div> ]]> </Content>
</Module>
L'exemple ci-dessus indique comment créer une grille simple présentant un contenu dynamique et répondant aux actions de glisser. La rubrique suivante décrit des fonctions de la bibliothčque grid vous permettant d'associer des comportements plus complexes ŕ votre grille.
Par défaut, la bibliothčque grid appelle 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. Pour apprendre ŕ utiliser ces fonctions, consultez notre Exemple de grille avancée.
| 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 situé dans l'index concerné. |
_IGG_getSourceView(source, target) |
Renvoie le contenu HTML de la cellule constituant la source lorsque l'utilisateur effectue un glisser. 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 glisser. 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 glisser. 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 glisser. source correspond ŕ l'index de la source. |
La bibliothčque grid fournit les fonctions suivantes pour permettre ŕ votre gadget de répondre aux clics et aux glissés effectués ŕ l'aide de la souris. Pour apprendre ŕ utiliser ces fonctions, consultez un Exemple de grille avancée.
| 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(). |
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. |
Lorsque le glisser d'un utilisateur se termine, les cellules suivantes sont actualisées :
_IGG_handleDrag() n'est pas définie._IGG_handleDrag() n'est pas définie. _IGG_getPossibleTargetView() est définie._IGG_getDragView() est définie. Cela signifie que si vous n'avez pas défini de vues avancées, mais que vous ayez défini une fonction _IGG_handleDrag() (et cela sera certainement le cas), vous devrez appeler la fonction de rappel _IGG_refreshCell() pour que les utilisateurs puissent visualiser les effets que produisent les opérations de glisser.
Cet exemple montre comment utiliser les fonctions décrites ci-dessus dans la rubrique Méthodes avancées.
Cette grille se comporte de la maničre suivante :
Vous trouverez ci-dessous les spécifications correspondant au gadget précédent :
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Advanced Grid Demo"
height="250" > <Require feature="grid"/> </ModulePrefs> <Content type="html"> <![CDATA[ <span id="grid_table"></span> Dragging: <span id="sdat">??</span> <script language="JavaScript"> // Create backend object, initialize with data var backend = new Object(); backend.data = new Array(1,2,3,4,5,6,7,2,1,7,4,5,6,3,5,7,3,6,4,1,2,7,6,5,4,3,2,1); // Default for cell content display backend._IGG_getNormalView = function(index) { var value = this.data[index]; return '<span style="font-size:24pt">' + value + '</span>'; } backend._IGG_isDragSource = function(index) { return true; } backend._IGG_isDragTarget = function(index, sourceIndex) { return this.data[index] != this.data[sourceIndex]; } // Returns the HTML content to be displayed under the cursor during a drag.
// In this example the surrogate view is the source value, bolded. backend._IGG_getSurrogateView = function(index) { var value = this.data[index]; return '<span style="font-size:24pt"><b>' + value + '</b></span>'; } // If the cursor is over a target, returns "source-value → target-value"
// in gray font for display in the source cell. Otherwise, returns source value. backend._IGG_getSourceView = function(source, target) { var s_value = this.data[source]; if (target == -1) { return '<span style="font-size:24pt;color:#888888">' + s_value + '</b></span>'; } else { var t_value = this.data[target]; return '<span style="font-size:10pt;color:#888888">' + s_value + '→' + t_value + '</b></span>'; } } // Returns the HTML content of cells that are legitimate targets for a drag operation. // In this example, a cell is a legitimate target if its value doesn't match the source value. // Cells that are legitimate targets display text in green. Cells that are not legitimate targets // display text in red, via the _IGG_getDragView() function below. backend._IGG_getPossibleTargetView = function(target, source) { var t_value = this.data[target]; // If a cell is a legal target, display its contents in a green font. return '<span style="font-size:24pt;color:#00A000">' + t_value + '</b></span>'; } // Returns the HTML content of cells that are NOT legitimate targets for a drag operation. // Cells that are not legitimate targets display text in red. // Cells that are legitimate targets display text in green via the _IGG_getPossibleTargetView() // function, above. backend._IGG_getDragView = function(target, source) { var t_value = this.data[target]; // If a cell is NOT a legal target, display its contents in a red font. return '<span style="font-size:24pt;color:#FF0000">' + t_value + '</b></span>'; } // If the cursor is over a target, returns "source-value + target-value"
// in green font for display in the target cell. backend._IGG_getTargetView = function(target, source) { var t_value = this.data[target]; var s_value = this.data[source]; return '<span style="font-size:12pt;color:#00A000">' + t_value + '+' + s_value + '</b></span>'; } // Clicking on a cell without dragging increments the value of the // cell's contents by 1. backend._IGG_handleClick = function(source) { this.data[source]++; // Callback on the backend object to force refresh this._IGG_refreshCell(source); } // When the user starts dragging, changes the message underneath the grid to show // the number that is being dragged. backend._IGG_handleDragStart = function(source) { document.getElementById("sdat").innerHTML = this.data[source]; } // If the user didn't drag to a legal target, don't change the data, but refresh the source // cell. Otherwise, adjust the numbers, and refresh the changed cells.
backend._IGG_handleDrag = function(source, target) { if (target == -1) { this._IGG_refreshCell(source); } else { this.data[target] += this.data[source]; this.data[source] = 0; // Callback on the backend object to force refresh this._IGG_refreshCell(source); this._IGG_refreshCell(target); } document.getElementById("sdat").innerHTML = '??'; } var grid = new _IG_Grid(backend, "mygrid", 4, 7); grid.getTable().border = 2; grid.getTable().cellPadding = 5; _gel("grid_table").appendChild(grid.getTable()); grid.initDragging(); </script> ]]>
</Content>
</Module>
Consultez la page des références pour obtenir une liste complčte des fonctions disponibles dans la bibliothčque grid.
Retour au début
©2009 Google - Rčgles de confidentialité - Conditions générales - Ŕ propos de Google
Mis ŕ jour le