La présente rubrique traite de l'obtention et de la manipulation de données distantes, qu'il s'agisse de données textuelles (en général, HTML), de données XML ou de données de flux RSS ou Atom.
L'intéręt majeur des gadgets est leur capacité ŕ regrouper des informations provenant de nombreuses sources différentes pour les recombiner ou ŕ proposer de nouvelles formes d'interaction avec les informations existantes. L'API Google Gadgets permet ŕ votre gadget d'aller rechercher du contenu distant sur des serveurs et des pages Web divers et variés, puis de le traiter.
L'API Google Gadgets fournit les fonctions d'extraction et de traitement de contenu Web distant suivantes :
Remarque : Vous ne pouvez pas utiliser les fonctions _IG_Fetch... avec des gadgets de type type="url".
Les fonctions _IG_Fetch... présentent un certain nombre de caractéristiques en commun :
Prenons l'extrait de code suivant, qui contient la fonction _IG_FetchContent(). Ce code permet d'aller chercher le texte HTML de la page Web google.fr et d'afficher, dans le navigateur, une fenętre contenant les 400 premiers caractčres du texte HTML de google.fr qui a été renvoyé :
_IG_FetchContent('http://www.google.fr/', function (responseText) {
// print the first 400 characters of Google's homepage HTML
alert(responseText.substr(0,400));
});
Cet exemple rend compte des principes de base qui régissent le mode opératoire des fonctions _IG_Fetch... :
Qu'est-ce qu'une fonction de rappel ? Dans le présent contexte, le plus simple est de définir la fonction de rappel comme une fonction transmise en tant que paramčtre (sous forme de référence de fonction) ŕ une autre fonction. Pour les développeurs tiers, les fonctions de rappel constituent, au sein d'une structure en cours d'exécution, des "points d'attache" qui permettent d'effectuer des opérations. Toutes les fonctions de type _IG_Fetch... prennent les fonctions de rappel en tant que paramčtres.
La plupart des exemples proposés sous cette rubrique présentent la fonction de rappel comme un littéral de fonction, c'est-ŕ-dire, comme une fonction anonyme exécutée au sein d'une fonction de type _IG_Fetch.... Exemple :
_IG_FetchContent('http://www.google.fr/', function (responseText) {
// do something
});
Toutefois, faire d'une fonction de rappel un littéral de fonction n'est pas une obligation. Si cela vous convient mieux, vous pouvez exécuter la fonction de rappel en tant que fonction nommée. Par exemple, dans cet extrait de code, la fonction de rappel se présente sous forme de fonction distincte, appelée my_callback_function() :
function my_callback_function(responseText) { if (responseText == null) return; alert(responseText.substr(0,400)); } // Here the callback is invoked by name _IG_FetchContent('http://www.google.fr/', my_callback_function);
Dans certains cas, vous voudrez peut-ętre transmettre des paramčtres supplémentaires ŕ la fonction de rappel. Pour cela, l'API Google Gadgets fournit une classe enveloppante _IG_Callback(callback, ...) qui vous permet d'ajouter ŕ la fonction de rappel des paramčtres, quel qu'en soit le nombre ou le type. Ces paramčtres supplémentaires apparaissent aprčs les paramčtres que la fonction de rappel reçoit normalement. Par exemple, dans le code ci-dessous, responseText (les données de réponse) est le premier paramčtre ŕ transmettre ŕ la fonction de rappel. Avec la fonction _IG_Callback, tous les paramčtres supplémentaires (ici, limit) apparaissent aprčs le premier paramčtre (ici, responseText). La classe enveloppante _IG_Callback peut ętre utilisée ŕ la place d'une fonction de référence et ainsi, servir de fonction de rappel. Exemple :
// Here my_callback_function takes an additional 'limit' parameter, which // specifies the upper range of the substring to be displayed in the alert // panel. function my_callback_function(responseText, limit) { if (responseText == null) return; alert(responseText.substr(0, limit)); } // You use the _IG_Callback wrapper to provide additional parameters. // In this example, '400' is passed as a parameter to indicate the upper // limit for the substring extraction. _IG_FetchContent('http://www.google.fr/', _IG_Callback(my_callback_function, 400));
La fonction la plus largement utilisée en termes de gestion de contenu Web distant est la suivante : _IG_FetchContent(url, func). Elle renvoie le contenu du site Web distant sous forme de texte.
Vous pouvez utiliser cette fonction pour extraire du code HTML de façon dynamique et pour programmer des interfaces élaborées qui permettent d'afficher ce code. Vous pouvez également programmer un gadget capable de rechercher sur un moteur de recherche les résultats d'une requęte donnée et de vous informer si l'ordre dans lequel les premiers résultats de la recherche apparaissent a été modifié.
La section précédente présentait plusieurs variantes d'un exemple assez simple qui utilisait la fonction _IG_FetchContent(). Voici un exemple de code capable de rechercher des données dans un fichier CSV (valeurs séparées par des virgules) stocké sur Google Page Creator et d'utiliser ces données pour remplir les informations relatives ŕ des contacts personnels :
// This example fetches data from a CSV file containing contact information. In the CSV file,
// each record consists of a name, email address, and phone number.
_IG_FetchContent('http://doc.examples.googlepages.com/Contacts.csv', function (responseText) {
// Set CSS for div.
var html = "<div style='padding: 5px;background-color: #FFFFBF;font-family:Arial, Helvetica;"
+ "text-align:left;font-size:90%'>";
// Use the split function to extract substrings separated by comma
// delimiters.
var contacts = responseText.split(",");
// Process array of extracted substrings.
for (var i = 0; i < contacts.length ; i++) {
// Append substrings to html.
html += contacts[i];
html += " ";
// Each record consists of 3 components: name, email, and
// phone number. The gadget displays each record on a single
// line:
//
// Mickey Mouse mickey@disneyland.com 1-800-MYMOUSE
//
// Therefore, insert a line break after each (name,email,phone)
// triplet (i.e., whenever (i+1) is a multiple of 3).
if((i+1)%3 ==0) {
html += "<br>";
}
}
html += "</div>";
// Output html in div.
_gel('content_div').innerHTML = html;
});
Pour un exemple plus élaboré, reportez-vous ŕ la page onebox.xml. Il s'agit d'un exemple de gadget illustrant la maničre d'exécuter plusieurs requętes en męme temps. Si vous entrez "_test" dans l'exemple onebox.xml, un test automatique démarre et envoie une "rafale" de requętes ŕ google.com. Les résultats de la requęte apparaissent dans l'ordre dans lequel les résultats ont été renvoyés.
_IG_FetchContent() ne renvoie aucune valeur, car, comme mentionné plus haut, elle est renvoyée immédiatement, tandis que la fonction de rappel qui lui est associée est appelée au moment oů le contenu de réponse est renvoyé. Plusieurs requętes peuvent ętre exécutées en męme temps. Si vous entrez "_test" dans l'exemple onebox.xml, un test automatique démarre et envoie une "rafale" de requętes ŕ google.com. Les résultats de la requęte apparaissent dans l'ordre dans lequel les résultats ont été renvoyés. Le gadget "onebox.xml" constitue un trčs bon exemple du mode opératoire de cette fonction.
Le DOM (Document Object Model) est une API permettant de se déplacer dans des documents HTML et XML. Vous pouvez utiliser la fonction JavaScript _IG_FetchXmlContent(url, func) de Google Gadgets afin d'extraire un document XML en tant qu'objet DOM. Une fois que vous avez récupéré l'objet, vous pouvez le manipuler ŕ l'aide de fonctions JavaScript DOM standard. Concrčtement, cela signifie que vous pouvez extraire les données voulues du fichier XML, les combiner ŕ des marqueurs HTML et CSS et faire apparaître le code HTML qui en résulte dans votre gadget.
Remarque : Avec la fonction _IG_FetchXmlContent(), vous pouvez uniquement extraire des fichiers XML et non des fichiers HTML. Pour des données HTML, servez-vous de la fonction _IG_FetchContent().
Dans l'interface DOM, le contenu Web est organisé sous la forme d'une arborescence de nśuds. Prenons comme exemple l'extrait de code HTML suivant :
<a href="http://www.google.fr/">Google's <b>fast</b> home page.</a>
Cet extrait rend compte des principaux types de nśuds dont il sera question ici :
Voici la structure DOM correspondant ŕ notre extrait de code HTML :
Pour accéder aux données d'un objet DOM, vous devez vous déplacer dans l'arborescence ŕ l'aide de fonctions DOM et ainsi passer de parents ŕ enfants jusqu'aux données recherchées.
Le fichier XML suivant contient des données correspondant ŕ une liste de composants pour un petit-déjeuner. Le nśud parent qui se trouve au sommet de la structure hiérarchique est le menu. Ce dernier possčde plusieurs nśuds enfants, les éléments food. Le nśud menu contient également un nśud attribut : title="Breakfast Menu". De chaque nśud food dépendent les nśuds enfants name, price, description et calories.
Les nśuds name, price et calories contiennent tous leurs propres nśuds enfants ("texte"). Chaque nśud description contient un nśud enfant CDATA. CDATA est un type de nśud différent car les sections CDATA servent ŕ appliquer les caractčres d'échappement appropriés ŕ des blocs de texte contenant des caractčres qui, sinon, seraient considérés comme des marqueurs (ex. : les crochets en chevron). Le seul séparateur qu'une section CDATA est capable de reconnaître est la chaîne “]]>” qui termine la section CDATA.
<?xml version="1.0" encoding="UTF-8" ?>
<menu title="Breakfast Menu">
<food>
<name>Early Bird Breakfast</name>
<price>$3.95</price>
<description><![CDATA[<div style="color:purple; padding-left:25px;">Two eggs any style with your choice of bacon
or sausage, toast or English muffin.</div>]]></description>
<calories>450</calories>
</food>
<food>
<name>Chocolate Chip Belgian Waffles</name>
<price>$7.95</price>
<description><![CDATA[<div style="color:purple; padding-left:25px;">Chocolate chip Belgian waffles covered with
chocolate syrup and whipped cream.</div>]]></description>
<calories>900</calories>
</food>
…
</menu>
Ce fichier XML est la source des données pour l'exemple de gadget suivant. Le but de ce gadget est d'afficher des menus pour petit-déjeuner et de permettre aux utilisateurs de définir une limite calorique. Toutes les indications caloriques supérieures ŕ la limite indiquée s'affichent donc en rouge. Les utilisateurs peuvent également choisir d'afficher ou non les descriptions correspondant ŕ chaque composant du menu.
Ce gadget utilise une fonction _IG_FetchXmlContent() pour extraire le fichier XML des données de petit-déjeuner sous forme d'arborescence DOM. Tout comme la fonction _IG_FetchContent(), la fonction _IG_FetchXmlContent() est asynchrone, c'est-ŕ-dire qu'elle est renvoyée immédiatement et qu'elle appelle sa fonction interne ultérieurement, une fois que l'opération de récupération des données est terminée. Cela nécessite d'inclure l'intégralité du code dépendant dans la fonction de rappel correspondante ou dans des fonctions appelées par cette derničre. Dans l'exemple suivant, toutes les opérations ont lieu au sein de la fonction de rappel. Le gadget se présente comme suit :
Le code suivant montre comment se déplacer dans l'arborescence DOM afin d'extraire les données des différents types de nśud et comment combiner ces données ŕ des marqueurs HTML et CSS afin qu'elles s'affichent dans le gadget de petit-déjeuner.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="_IG_FetchXmlContent Example"
scrolling="true"/>
<UserPref
name="mycalories"
display_name="Calorie limit"
default_value="800"/>
<UserPref
name="mychoice"
display_name="Show Descriptions"
datatype="bool"
default_value="false"/>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
function displayMenu() {
// XML breakfast menu data
var url = "http://doc.examples.googlepages.com/breakfast-data.xml";
var prefs = new _IG_Prefs(__MODULE_ID__);
// Calorie limit set by user
var calorieLimit = prefs.getString("mycalories");
// Indicates whether to show descriptions in the breakfast menu
var description = prefs.getBool("mychoice");
_IG_FetchXmlContent(url, function (response) {
if (response == null || typeof(response) != "object" ||
response.firstChild == null) {
_gel("content_div").innerHTML = "<i>Invalid data.</i>";
return;
}
// Start building HTML string that will be displayed in <div>.
// Set the style for the <div>.
var html = "<div style='padding: 5px;background-color: #ccf;font-family:Arial, Helvetica;" +
"text-align:left;font-size:90%'>";
// Set style for title.
html +="<div style='text-align:center; font-size: 120%; color: yellow; " +
"font-weight: 700;'>";
// Display menu title. Use getElementsByTagName() to retrieve the <menu> element.
// Since there is only one menu element in the file,
// you can get to it by accessing the item at index "0".
// You can then use getAttribute to get the text associated with the
// menu "title" attribute.
var title = response.getElementsByTagName("menu").item(0).getAttribute("title");
// Alternatively, you could retrieve the title by getting the menu element node
// and calling the "attributes" function on it. This returns an array
// of the element node's attributes. In this case, there is only one
// attribute (title), so you could display the value for the attribute at
// index 0. For example:
//
// var title = response.getElementsByTagName("menu").item(0).attributes.item(0).nodeValue;
// Append the title to the HTML string.
html += title + "</div><br>";
// Get a list of the <food> element nodes in the file
var itemList = response.getElementsByTagName("food");
// Loop through all <food> nodes
for (var i = 0; i < itemList.length ; i++) {
// For each <food> node, get child nodes.
var nodeList = itemList.item(i).childNodes;
// Loop through child nodes. Extract data from the text nodes that are
// the children of the associated name, price, and calories element nodes.
for (var j = 0; j < nodeList.length ; j++) {
var node = nodeList.item(j);
if (node.nodeName == "name") {
var name = node.firstChild.nodeValue;
}
if (node.nodeName == "price") {
var price = node.firstChild.nodeValue;
}
if (node.nodeName == "calories") {
var calories = node.firstChild.nodeValue;
}
// If the user chose to display descriptions and
// the child node is "#cdata-section", grab the
// contents of the description CDATA for display.
if (node.nodeName == "description" && description==true)
{
if (node.firstChild.nodeName == "#cdata-section")
var data = node.firstChild.nodeValue;
}
}
// Append extracted data to the HTML string.
html += "<i><b>";
html += name;
html += "</b></i><br>";
html += " ";
html += price;
html += " - ";
// If "calories" is greater than the user-specified calorie limit,
// display it in red.
if(calories > calorieLimit) {
html += "<font color=#ff0000>";
html += calories + " calories";
html += " </font>";
}
else
html += calories + " calories";
html += "<br>";
// If user has chosen to display descriptions
if (description==true) {
html += "<i>" + data + "</i><br>";
}
}
// Close up div
html += "</div>";
// Display HTML string in <div>
_gel('content_div').innerHTML = html;
});
}
_IG_RegisterOnloadHandler(displayMenu);
</script>
]]>
</Content>
</Module>
Ce code présente quatre des fonctions essentielles ŕ l'interaction avec des données DOM :
Dans cet exemple, seules quelques fonctions de navigation dans l'arborescence DOM sont présentées. Vous pouvez également essayer d'inclure quelques autres fonctions, telles que lastChild, nextSibling, previousSibling etparentNode.
Pour utiliser le DOM le plus efficacement possible, il faut savoir détecter les différences, parfois trčs subtiles, qui existent entre les types de nśud.
| Type de nśud | Description | Valeurs de renvoi | Explications |
|---|---|---|---|
| element | Composants essentiels de la structure d'un document tels que <p> , <b> ou <calories>. | nodeName : tout type de texte qui se trouve entre crochets en chevron. Par exemple le nom nodeName du <menu> est “menu”. nodeType : 1 nodeValue : null |
La valeur nodeValue de l'élément est null. Pour obtenir la valeur d'un nśud de type texte ou attribut associé ŕ un élément, vous devez vous déplacer jusqu'ŕ ces nśuds. Exemple : element.firstChild.nodeValue pour le texte et element.getAttribute(attrib) pour les attributs. |
text |
Texte : un nśud de type texte apparaît toujours en tant que contenu des nśuds élément. C'est l'enfant d'un élément. | nodeName : #text nodeType : 3 nodeValue : tout type de texte qui se trouve dans le nśud. |
Certains navigateurs affichent les espaces du début d'un document sous forme de nśuds de type texte de sorte que vous obtenez des nśuds texte “empty” (vide) dans votre objet DOM. Cela peut entraîner des bugs lorsque vous vous déplacez dans l'arborescence. Une solution trčs simple consiste ŕ filtrer les nśuds de type texte qui contiennent le caractčre de saut de ligne. Mais vous pouvez également opter pour une solution plus élaborée. Pour de plus amples informations ŕ ce sujet, consultez la page Whitespace in the DOM du centre des développeurs de Mozilla. |
| attribute | Paire valeur/clé qui fournit des informations supplémentaires sur un nśud élément, comme, par exemple, le titre d'un document tel que title=”my document”. Un attribut est contenu dans un nśud élément, mais il n'est pas un enfant du nśud élément. | nodeName : valeur de gauche de la paire d'attribut. Si l'attribut est title=”my document”, le nom du nśud (nodeName) est "title". nodeType : 2 nodeValue : la valeur de droite dans la paire d'attributs, soit, dans le présent exemple, “my document”. |
Bien que les attributs soient des nśuds contenus dans les nśuds de type élément, ils ne sont pas des nśuds enfants de ces éléments. Ils héritent de l'interface Node, mais ne font pas partie de l'arborescence DOM. Cela signifie que vous pouvez utiliser la plupart des fonctions de nśud sur les nśuds de type attribut (nodeName, nodeValue ou nodeType, par exemple), mais que vous ne pouvez pas accéder aux nśuds de type attribut ŕ l'aide de fonctions de navigation DOM. Pour accéder ŕ ces attributs, vous devez vous servir des fonctions attributes et getAttribute(attrib). |
| CDATA | Section dont le contenu est ignoré, donc pas interprété. Les sections CDATA servent ŕ appliquer des caractčres d'échappement ŕ des blocs de texte contenant des caractčres qui, sinon, seraient considérés comme des marqueurs. Le seul séparateur qu'une section CDATA est capable de reconnaître est la chaîne "]]>" qui termine la section CDATA. | nodeName : #cdata-section nodeType : 4 nodeValue : texte et marqueurs se trouvant entre les séparateurs de la section CDATA. |
Le texte d'une section CDATA dispose de marqueurs qui lui sont propres, ce qui peut avoir des répercussions sur la façon dont vous allez l'incorporer ŕ votre gadget. |
Vous pouvez ajouter un flux ŕ votre page iGoogle en tapant son URL dans le formulaire Ajouter une URL de l'annuaire de contenu. Pour créer un gadget correspondant ŕ un flux indiqué et l'ajouter ŕ votre page iGoogle, vous devez utiliser la prise en charge des flux intégrée ŕ l'API Google Gadget. Il s'agit d'un outil simple ŕ utiliser, qui vous permet d'appliquer toute forme de personnalisation au contenu ou ŕ son affichage. Néanmoins, vous ne pouvez pas l'utiliser pour les autres services de Google.
Pour une gestion des flux plus élaborée, l'API Google Gadgets propose la fonction _IG_FetchFeedAsJSON(url, func, num_entries, get_summaries). Cette _IG_FetchFeedAsJSON() fonction va chercher un flux RSS ou Atom et renvoie les données de flux principales sous forme d'objet JSON. JSON (JavaScript Object Notation) est une maničre simple de décrire des données de scripts JavaScript.
_IG_FetchFeedAsJSON() inclut les paramčtres suivants :
| Name | Data Type | Description |
|---|---|---|
| url | string, required | URL du flux RSS ou Atom ŕ extraire. |
| callback | function, required | Fonction de rappel ŕ exécuter une fois les données extraites. |
| num_entries | integer, optional | Nombre d'entrées de flux ŕ extraire du flux. Ce nombre peut ętre compris entre 1 et 100. La valeur par défaut est 3. |
| get_summaries | boolean, optional | Indique s'il faut extraire l'intégralité du texte des résumés pour les entrées du flux. Par défaut, sa valeur est "false". Définissez ce paramčtre sur "true" uniquement si vous avez l'intention d'utiliser les données. Les résumés complets peuvent ętre assez volumineux et ne doivent pas ętre transférés sans raison valable. |
Voici les champs de l'objet de flux JSON :
| Champ | Description |
|---|---|
| ErrorMsg | Si défini, décrit les erreurs qui se produisent. |
| URL | URL du flux RSS ou Atom. |
| Title | Titre du flux. |
| Description | Commentaire ou description du flux. |
| Link | En général, URL de la page d'accueil du flux. |
| Author | Auteur du flux. |
| Entry | Tableau des entrées de flux. Les champs suivants sont compris dans le paramčtre Entry :
|
Cet exemple montre comment utiliser la fonction _IG_FetchFeedAsJSON() pour obtenir un flux et afficher des sections des données de ce flux dans un gadget. Le gadget obtenu est présenté ci-aprčs. Il permet aux utilisateurs de spécifier les éléments suivants :
Voici le gadget obtenu lorsque les préférences utilisateur ont été définies :
Le code correspondant ŕ cet exemple est le suivant :
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="_IG_FetchFeedAsJSON Example"
title_url="http://groups.google.com/group/Google-Homepage-API" />
<UserPref name="show_date" display_name="Show Dates?" datatype="bool"/>
<UserPref name="show_summ" display_name="Show Summaries?" datatype="bool"/>
<UserPref name="num_entries" display_name="Number of Entries:" />
<Content type="html">
<![CDATA[
<style> #content_div { font-size: 80%; margin: 5px; background-color: #FFFFBF;} </style>
<div id=content_div></div>
<script type="text/javascript">
// Get userprefs
var prefs = new _IG_Prefs(__MODULE_ID__);
var showdate = prefs.getBool("show_date");
var summary = prefs.getBool("show_summ");
var entries = prefs.getInt("num_entries");
// If user wants to display more than 100 entries, display an error
// and set the value to 100, the max allowed.
if (entries > 100)
{
alert("You cannot display more than 100 entries.");
entries = 100;
}
// Use the _IG_FetchFeedAsJSON() function to retrieve core feed data from
// the specified URL. Then combine the data with HTML markup for display in
// the gadget.
_IG_FetchFeedAsJSON("http://groups.google.com/group/Google-Homepage-API/feed/rss_v2_0_msgs.xml",
function(feed) {
if (feed == null){
alert("There is no data.");
return;
}
// Start building HTML string that will be displayed in gadget.
var html = "";
// Access the fields in the feed
html += "<div><b>" + feed.Title + "</b></div>";
html += "<div>" + feed.Description + "</div><br>";
// Access the data for a given entry
if (feed.Entry) {
for (var i = 0; i < feed.Entry.length; i++) {
html += "<div>"
+ "<a target='_blank' href='" + feed.Entry[i].Link + "'>"
+ feed.Entry[i].Title
+ "</a> ";
if (showdate==true)
{
// The feed entry Date field contains the timestamp in seconds
// since Jan. 1, 1970. To convert it to the milliseconds needed
// to initialize the JavaScript Date object with the correct date,
// multiply by 1000.
var milliseconds = (feed.Entry[i].Date) * 1000;
var date = new Date(milliseconds);
html += date.toLocaleDateString();
html += " ";
html += date.toLocaleTimeString();
}
if (summary==true) {
html += "<br><i>" + feed.Entry[i].Summary + "</i>";
}
html += "</div>";
}
}
_gel("content_div").innerHTML = html;
// The rest of the function parameters, which are optional: the number
// of entries to return, and whether to return summaries.
}, entries, summary);
</script>
]]>
</Content>
</Module>
©2009 Google - Rčgles de confidentialité - Conditions générales - Ŕ propos de Google
Mis ŕ jour le