Plugins pour récupérer des informations sur des sites web

Les plugins sont utilisés pour aller chercher sur des sites web des informations relatives à des éléments de collection. Les champs sont ainsi remplis automatiquement avec toutes les informations qu’il est possible d’obtenir.

Cette page décrit la manière de créer de tels plugins.

N’oubliez pas les Conventions de codage lors de l’écriture d’un plugin.

Préparation

La manière la plus facile de créer un nouveau plugin est de copier un de ceux existant déjà et le modifier. Ils sont situés dans lib/gcstar/GCPlugins/GCxxx, où xxx représente le type de collection concerné. Ainsi, les plugins utilisés pour rapatrier des informations sur les films sont situés dans le répertoire lib/gcstar/GCPlugins/GCfilms.

Il est aussi possible de se baser sur un template fourni avec les sources de GCstar. Il s’agit de GCSiteTemplate.pm, situé dans le répertoire des templates.

Le nom donné au fichier est libre mais il devrait être explicite. Les deux premières lettres doivent toujours être GC, et l’extension .pm.

La première ligne du plugin est de cette forme :

package GCPlugins::GCxxx::GCyyy;

puis, quelques lignes plus bas :

package GCPlugins::GCxxx::GCPluginyyy;

Il faut modifier yyy de manière à ce qu’il corresponde au nom de fichier du plugin (sans l’extension).

Interface

Voici une liste des méthodes que votre plugin peut mettre en œuvre. La construction est faite selon un modèle objet, c’est à dire que le premier paramètre fait toujours référence à un objet. Cet objet est une instance de votre package, celui qui devra faire le travail. Une même instance pourrait être utilisée plusieurs fois durant une session utilisateur, mais il n’y a aucune garantie à ce sujet. Par conséquent votre package devrait être préparé pour ce genre de situation et fonctionner dans tous les cas. Cela signifie que vous êtes censé nettoyer les valeurs des données qui devraient être remises à zéro et éviter de les stocker entre deux travaux de récupération d’information.

new

Paramètres
Nom du package.
Renvoie
Une référence consacrée (blessed) de l’objet créé (elle doit être une table de hachage). Vous devrez utiliser le constructeur pour la classe de base, GCPlugins::GCxxx::GCxxxPluginsBase.
Description
C’est le constructeur de l’objet du plugin. Vous pouvez initialiser ici toutes les valeurs internes que vous désirez. Vous êtes aussi censé initialiser un champ (hasField) contenant une référence à une table de hachage où les clefs sont les noms des champs qu’une recherche renverra. Ces champs se trouvent dans le fichier .gcm décrivant le modèle de collection (situés dans lib/gcstar/GCModels/), et sont placés entre des balises results (dans collection>options>fields). La valeur associée est de 1 lorsque le plugin renvoie une valeur pour le champ lors d’une recherche, et 0 dans le cas contraire.

getName

Paramètres
Aucun.
Renvoie
Une chaîne contenant le nom du plugin.
Description
Le nom renvoyé est celui qui sera affiché dans l’application. Il doit donc être unique et suffisamment explicite afin d’éviter toute confusion.

getAuthor

Paramètres
Aucun.
Renvoie
Une chaîne contenant le nom de l’auteur.
Description
Renvoie le nom ou le surnom de l’auteur du plugin. La chaîne renvoyée sera affichée dans l’application lorsque l’utilisateur sélectionne un plugin.

getLang

Paramètres
Aucun.
Renvoie
Une chaîne contenant la langue du site web.
Description
Permet d’informer l’utilisateur sur la langue du plugin concerné. Cette valeur est aussi utilisée par GCstar pour sélectionner automatiquement les plugins correspondant à la langue de l’utilisateur. Elle doit être un code de langue à 2 lettres. Dans le cas où la langue est déjà en fonction dans GCstar, le code doit être le même que celui utilisé pour la traduction.

getCharset

Paramètres
Aucun.
Renvoie
Une chaîne contenant le charset du site web.
Description
Cette information devrait se trouver dans l’entête HTML des pages du site web. La valeur par défaut est ISO-8859-1

getSearchUrl

Paramètres
Le texte à rechercher.
Renvoie
L’URL de la page présentant les résultats de la recherche. Éventuellement les paramètres POST.
Description
Cette méthode est utilisée pour générer l’URL de la page correspondante aux résultats de la recherche demandée par l’utilisateur. La valeur obtenue est préalablement préparée pour être utilisée directement dans l’URL sans aucune conversion complémentaire (c.-à-d. tous les caractères spéciaux ont été échappés).
Si un site web utilise la méthode GET pour son formulaire de recherche, toute l’information transite par l’URL. Mais certains sites utilisent la méthode POST, alors des informations complémentaires à l’URL doivent être envoyés. Les paramètres doivent être contenus dans une référence à un tableau de clefs/valeur.

Voici un exemple de getSearchUrl pour un formulaire de site web utilisant POST, où deux paramètres (query et type) sont transmis avec leurs valeurs associées.

sub getSearchUrl
{
    my ($self, $word) = @_;
    return ('http://www.example.com/search.php', ['query' => $word, 'type' => 'movies']);
}

getItemUrl

Paramètres
Une URL, un élément, ou rien du tout.
Renvoie
L’URL complète de la page décrivant un élément.
Description
cette méthode peut être appelée dans deux contextes différents. Pour une recherche, le résultat ne contiendra que l’URL relative de la page contenant une description. Il faudra donc ajouter l’adresse du site web pour obtenir une URL complète. Le deuxième cas intervient lors d’un cliqué-glissé d’une URL d’un navigateur Web vers GCStar. L’application appellera cette méthode sans aucun paramètres et tentera de trouver une correspondance entre l’URL fournie et celle d’un plugin existant. Ainsi, en cas de correspondance, GCStar saura quel plugin utiliser pour l’analyse syntaxique (« parsing »)de la page.

preProcess

Paramètres
Le contenu complet d’une page.
Renvoie
Le contenu modifié d’une page.
Description
Avant l’analyse syntaxique (« parsing ») d’une page, il est possible avec cette méthode d’apporter des changements au contenu, comme enlever des parties inutilisées ou traiter des problèmes de balises. Vous pouvez aussi tester $self->{parsingList} comme décrit plus bas.

L'analyse des pages

Les plugins sont basés sur des analyseurs (« parsers ») HTML qui parcourent une page HTML et réagissent, selon les évènements rencontrés, à l’aide de fonctions particulières.

Lorsqu’une balise débute, comme <p> ou <a href=...>, la méthode appelée est start ; quand il y a un contenu textuel, la méthode appelée est text et lorsque une balise de fin est rencontrée, la méthode appelée est end. Consultez la documentation sur HTML::Parser pour plus d’information, d’autant plus que c’est le package de base de votre package (en admettant que vous n’ayez pas supprimé la clause use base durant sa création).

Nous partons du principe que la référence à l’objet en cours se trouve dans la variable $self.

Dans ces méthodes, il y a deux blocs principaux dépendants de la valeur de $self->{parsingList}. Si cette valeur est true, cela signifie que nous analysons une page de résultats (la liste des éléments correspondants à une recherche). Si la valeur est false, alors c’est que nous analysons l’information relative à un élément donné.

Quand une analyse concerne une page de résultat, vous devez remplir un tableau nommé $self->{itemsList}. Chaque élément du tableau est une référence à une table de hachage. Chaque clef de la table de hachage est le nom du champ (le même que celui dans $self->{hasField} initialisé dans la méthode new ). Les valeurs sont celles qui ont été extraites à partir de la page analysée.

Lors de l’analyse de la description d’un élément, les valeurs sont stockées dans $self->{curInfo}->{fieldName}, où fieldName est le même nom que celui utilisé dans le fichier .gcm.

Prévenir les webmasters

Bien que GCstar ne fait rien de plus que ce que ferait un navigateur Internet, il est toujours mieux de prévenir le webmaster de ce que vous être en train de faire. Consultez simplement la page des contacts du site afin d’envoyer un email pour les informer. Vous pouvez leur envoyer un lien vers la page contenant les informations pour webmasters (en anglais).

Comme il n’est pas forcément évident de comprendre ce que fait GCstar, vous aurez peut-être besoin d’insister sur le fait que c’est uniquement pour un usage personnel. Egalement, il n’est absolument pas question de cacher aux utilisateurs quel site est utilisé. Et ils sauront toujours d’où proviennent les informations. Ces sites existent grâce à un très bon travail qu’il ne faut pas occulter.

 
fr/websites_plugins.txt · Dernière modification: 03/07/2011 07:59 par Tian



Si avez rencontré un problème avec GCstar, vous pouvez ouvrir un rapport de bug ou demander de l'aide sur les forums GCstar.