Meta-Press.es

Moteur de recherche décentralisé & revue de presse automatisée

Comment ajouter de nouvelles sources à Meta-Press.es

lang.: en

Si vous êtes un programmeur, ajoutez simplement une entrée dans le fichier json/sources.json.

Ce document est là pour vous guider pas à pas dans cette opération.

Pour tester votre travail avant de l’envoyer, vous pouvez importer vos propres sources depuis les paramètres de l’extension.

Voici quelques exemples utiles, listés en haut du fichier json/sources.json :

  • Mediapart.fr est un bon exemple, de source "normale" utilisant des sélecteurs CSS

  • News.mn/en est un exemple de source fournissant ses résultats au format RSS

  • News.mn étend la définition de source News.mn/en

  • ArretSurImages fourni ses résultats en JSON

  • The Japan News utilise la méthode HTTP POST

  • Helsinky Times a besoin de sélecteurs XPaths pour récupérer certains champs

1. Méthodologie

  • Tout d’abord, vérifier que la source n’est pas déjà présente de Meta-Press.es en vérifiant :

    • Dans la liste des sources de l’extension (volet « Recherche avancée », bouton « Liste des sources »)

    • Dans la liste des sources incompatibles.

    • Dans la liste des sources cassées…

  • Puis charger la page de la source et noter son adresse (en HTTPS si possible) ;

  • Trouver et tester la fonctionnalité de recherche proposée par le site :

    • Vérifier si les résultats sont accessibles en RSS (ou ATOM) en utilisant les outils de Développeurs de Firefox (touche F12, onglet par défaut Inspecteur, rechercher "rss") c’est plus rapide à intégrer ;

      • si c’est le cas : la source est "type": "XML" et il n’est pas nécessaire de préciser le fuseau horaire ("tz") de la source dans les tags

    • vérifier que cette URL fourni des résultats triés du plus récent au plus ancien, ou chercher à obtenir ce tri, sinon la source est dite incompatible, voir l’encart ci-dessous

    • si l’URL des résultats ne comporte pas vos termes de cherche, c’est que cette source utilise la méthode HTTP POST, vous pouvez alors vous inspirer de la source The Japan News

    • vérifier que les résultats sont bien renvoyés avec la page HTML via l’onglet « Réseau » des outils Développeurs de Firefox, partie Réponse de la requête. Si les résultats ne sont pas dans la page, ils arrivent probablement via une 2e requête (XHR) formatés en JSON. Voir Arrêt sur Images pour un exemple

    • tester le fonctionnement de la recherche pour reconnaître son comportement : faîtes une recherche avec plusieurs termes d’un coup, est-ce que la source renvoie des résultats contenant tous vos termes, ou seulement un des termes ? Le résultat permettra de choisir quelle étiquette mettre à la source : tags techniques.

    • noter un terme de recherche donnant des résultats au choix parmi : europe, paris, new, via, 1, 2000. Si aucun de ces termes ne donne de résultat, contacter l’équipe de développeurs.

    • vérifier si cette source peut fournir des résultats de différent types (text, image, video, audio), si c’est le cas, il est possible de créer une source par type de résultat (ce qui est rapide en étendant la première définition).

  • Chercher le flux RSS principal de la source.

  • Chercher le favicon de la source (la plus petite version disponible, idéalement 32px de large).

Si quelques chose se passe mal, comme par exemple :

  • pas de fonctionnalité de recherche

  • pas de date sur les résultats

  • pas de tri par date

Il est important de contacter la source en question pour lui proposer de faire évoluer sa fonctionnalité de recherche, puis de lister la source parmi les sources incompatibles où l’on peut également noter l’état d’avancement de sa tentative de retour utilisateur auprès de la source.

Il est également possible de contacter les sources n’ayant pas encore été contactées, et n’ayant donc pas encore d’information concernant le statu du retour utilisateur à leur formuler.

Une fois ces premiers tests effectués, vous pouvez vous lancer sereinement dans la rédaction de votre définition de source. Il y a 4 sortes d’informations à fournir :

  • informations générales : le nom, le fuseau horaire, la langue et autres à la fin ;

  • gros titres : une entrée pointant vers le flux RSS principal de la source ;

  • recherche : l’URL du moteur de recherche de la source ;

  • analyse des résultats : 5 entrées pour décrire les champs des résultats (les deux dernières étant facultatives) :

    • titre : r_h1

    • lien : r_url

    • date : r_dt

    • extrait : r_txt

    • auteur : r_by

Chacune que ces entrées peut être suivie d’une entrée du même nom mais suffixée _attr ou _re, afin de préciser un attribut de balise HTML (ou un attribut JavaScript de node HTML [1]) à lire, ou effectuer un remplacement du texte pointé par motif d’expression rationnelle (via la fonction .replace() du JavaScript). La version _re doit donc définir une liste de deux éléments : le premier est la chaîne de caractère permettant de créer l’expression rationelle (RegEx) en question, et le second est le motif de remplacement (il y a des exemples un peu plus bas).

Il est encore possible de donner une entrée suffixée par _xpath pour utiliser un sélecteur XPath au lieu d’un sélecteur CSS.

1.1. Pense-bête des vérifications post-création

Quand on pense avoir fini une source, et avant de l’envoyer à l’équipe de dévelopement pour contribution, il peut être utile de vérifier les points suivants, qui ne se voient pas au premier coup d’œil sur une source qui donne des résultats :

  • le champs news_rss_url a-t-il été renseigné (est-il applicable ? Y a-t-il un flux RSS indexant les nouveautés de cette source ?)

  • le champs res_nb a-t-il été renseigné ? (la source affiche-t-elle le nombre de résultats d’une recherche ? On a malheureusement pas cette information dans le cas des sources de type XML)

  • est-ce que la recherche est bien triée par date sur la source ?

  • est-ce qu’un clic sur un résultat dans Meta-Press.es ouvre un onglet sur la bonne page de la source ?

  • est-ce que les étiquettes many words, one word ou approx ont bien été renseignées ?

    • pour vérifier si la sources est many words : faire une recherche sur un seul terme (noter le nombre de résultats), puis faire une recherche avec 2 termes et vérifier qu’il y a moins de résultats dans la 2e recherche (voir aucun résultat, si le 2e terme est inconnu, ex: zorglub). Si c’est le cas, la source croise vraisemblablement les termes de cherche au lieu de les additionner

    • pour vérifier qu’une source est one word : faire un recherche sur un terme ambiguë (comme "bid") et vérifier si les résultats retournés contiennent exactement le terme cherché, ou une approximation (comme "biden")

    • si la source n’est ni l’un ni l’autre, elle est considérée comme approx. Dans ce cas, il faut encore vérifier si on peut appliquer un filter_results sur cette source (voir le paragraphe correspondant)

  • si le contenu est accessible sans inscription on peut ajouter l’étiquette access content, s’il accessible depuis Meta-Press.es on peut ajouter direct content

  • si la sources est illustrée, il faut encore vérifier que l’attribut alt= est bien rempli et ajouter un champs r_img_alt sinon (qui peut pointer sur le titre s’il n’y a rien de plus pertinent à disposition)

2. Exemples

2.1. Définition de source basée RSS

{
	"https://news.mn/en": {
		"favicon_url": "https://news.mn/en/wp-content/uploads/2019/07/NE-16.jpg",
		"news_rss_url": "https://news.mn/en/feed/",
		"search_url": "https://news.mn/en/search/{}/feed", (1)
		"search_url_web": "https://news.mn/en/?s={}", (2)
		"type": "XML", (3)
		"tags": { … } (4)
	}
}
1 Dans cette URL, Meta-Press.es remplacera le jeton {} par vos termes de recherche.
2 Cette 2e URL permet de renvoyer les utilisateurs vers la page web de leur recherche, pour approfondir leur recherche sur une source donnée.
3 Quand il n’y a pas de type défini pour une source, les résultats de la source sont traités comme étant du HTML. Ici, on précise que la source répond en XML mais ça pourrait encore être du JSON.
4 Les tags sont expliqués plus bas

2.2. Extension de vos propres définitions de source

	"https://news.mn": {
		"extends": "https://news.mn/en", (1)
		"favicon_url": "https://news.mn/wp-content/uploads/2019/07/favicongr-16.jpg",
		"new_rss_url": "https://news.mn/feed/",
		"search_url": "https://news.mn/search/{}/feed",
		"search_url_web": "https://news.mn/?s={}",
		"tags": { … }
	}
1 Ici "https://news.mn/en" est la clé de la source à étendre, la première chaîne de caractère d’une source.

Dans ce cas, on part de la source à étendre https://news.mn/en et on redéfinit certaines entrées "localement" pour https://news.mn.

Si vous avez besoin de retirer un élément fournit par la source étendue, vous pouvez le déclarer dans la nouvelle source et lui attribuer la valeur null. L’élément ne sera pas considéré par Meta-Press.es

2.3. Définition de source basées sur JSON

Pour diagnostiquer un cas de chargement des résultats via une requête AJAX et travailler sur l’objet JSON correspondant il est possible de s’appuyer sur les outils développeurs de Firefox. La touche F12 permet d’ouvrir la fenêtre correspondante, puis se rendre dans la console JavaScript. Les requêtes XHR qui ont lieu après le chargement initial de la page inspectée y apparaissent. Une fois la requête repérée, l’outil permet de déplier les informations associées, dont le contenu de la réponse reçue (ici c’est donc un objet JSON) de parcourir ce contenu voire effectuer des recherches dedans.

Si la requête inspectée contient bien les résultats de notre recherche on dispose de son adresse et il reste à préciser les chemins d’accès à chaque information.

	"https://www.arretsurimages.net": {
    "favicon_url": "https://www.arretsurimages.net/assets/img/favicon/favicon-32x32.png",
    "news_rss_url": "https://api.arretsurimages.net/api/public/rss/all-content",
    "type": "JSON",
    "search_url": "https://api.arretsurimages.net/api/public/search?q={}&sort=last_version_at&limit={<100}", (1)
    "search_url_web": "https://www.arretsurimages.net",
    "res_nb": "hits -> total", (2)
    "results": "hits -> hits", (3)
    "r_h1": "title -> text",
    "r_url": "path",
    "r_dt": "last_version_at",
    "r_txt": "tease",
    "r_by": "authors", (4)
    "r_by_attr": "name", (4)
    …
1 Meta-Press.es remplacera le jeton {<100} par la plus petite valeur entre le nombre indiqué entre les accolades et le nombre maximum de résultats à lire depuis cette source (configuré dans les paramètres de l’extension).
2 Lorsqu’on analyse un objet JSON, on peut préciser un chemin pour accéder à un sous élément en séparant les éléments du chemin par des " → " (flèches espacées).
3 Ce chemin mène à la liste des résultats, Meta-Press.es va la parcourir.
4 L’entrée r_by pointe une liste JSON et l’entrée r_by_attr désigne un attribut des objets de la liste. Meta-Press.es formera donc une chaîne de caractère en rassemblant l’attribut en question de chaque élément de la liste pointée. On récupère ici en pratique la liste complète des auteurs.

2.3.1. json_to_html

Les résultats peuvent également être envoyés sous forme de HTML valide embarqué dans un objet JSON.

Dans ce cas il est possible de préciser dans une entrée json_to_html un chemin JSON pointant vers la chaîne de caractère HTML à parser.

Pour l’instant un seul chemin est utilisable mais il se pourrait que la chose soit déclinée champs par champs (r_h1_html, r_url_html…).

2.4. Définition de source basées sur des sélecteurs CSS

	"https://www.mediapart.fr": {
		"favicon_url": "https://www.mediapart.fr/assets/front/favicon/journal/favicon-32x32.png",
		"news_rss_url": "https://www.mediapart.fr/articles/feed",
		"search_url": "https://www.mediapart.fr/search?search_word={}&sort=date&order=desc",
		"res_nb": ".sub-title",
		"res_nb_re": ["^(\\d+?) ", "$1"], (1)
		"results": "ul.search > li", (2)
		"r_h1": "h2",
		"r_url": "h2 > a",
		"r_url_attr": "href", (3)
		"r_dt": ".author",
		"r_dt_fmt_1": [
			"\\s(\\d+?)[erèm]*? (.+?) (\\d{4})",
			"$3-{$2}-$1"
		], (4)
		"r_txt": "p",
		"r_by": ".author a[rel=author]",
		"tags": { … }
	},
1 res_nb peut lui aussi être accompagné d’une entrée complémentaire _re, ici cela permet d’extraire le nombre de résultats au début d’une chaîne plus grande
2 C’est cette expression CSS qui permet d’extraire les résultats de la page, elle pointe directement vers les résultats, attrapés grâce un querySelectorAll(). Notons l’utilisation d’un sélecteur CSS strict (avec >) pour s’assurer qu’on n’attrapera pas des éléments indésirés éventuellement présents ailleurs sur la page
3 r_url_attr permet de cibler l’attribut href
4 r_dt_fmt_1 :

  • Ici nous capturons les différents éléments de la date pour les remettre dans l’ordre attendu par JavaScript. De plus le nom du mois est entouré d’accolades dans le motif de remplacement {$2} et il sera converti en son numéro de mois.

  • On peut noter que la barre oblique inversée (ou anti-slash) est le caractère d’échappement en JavaScript, et qu’il est du coup nécessaire de l’échapper lui-même pour l’encoder dans une chaîne de caractères, d’où les : \\s et \\d.

  • Enfin, comme le nom du champ le laisse supposer, il est possible de définir autant de format de date que nécessaire, dans le cas où la source en utilise plusieurs (notamment des formats de date relative pour les résultats récent : « il y a 1h » ou « hier » à traduire en anglais).

2.5. Définition de source basées sur la méthode HTTP POST

	"https://the-japan-news.com": {
		"favicon_url": "https://the-japan-news.com/favicon.ico",
		"method": "POST", (1)
		"body": "siteSearchInput={}&x=7&y=11&span=365", (2)
		"search_url": "https://the-japan-news.com/news/search",
		…
		"r_dt": "time", (3)
		"r_dt_attr": "datetime", (3)
		…
	}
1 En plus de l’habituel search_url, il y a ici besoin de l’entrée method positionnée à POST
2 Et d’un body pour la requête. C’est une chaîne de caractère l’équivallente à la query string des paramètres de requête GET. Ce format est nommé application/x-www-form-urlencoded. Les données doivent parfois être envoyée en JSON et il faut alors ajouter une entrée search_ctype contenant la chaîne 'application/json'. Un 3e cas a également été rencontré, le formatage des données du body en multipart/form-data (comme LaVie.fr).
3 On peut noter que quand une balise HTML <time datetime=""> est présente il est préférable de l’utiliser car elle évite d’avoir a reformater la date à l’aide d’un motif de remplacement, et aussi d’avoir à préciser le fuseau horaire de la source dans les tags.

2.6. Définition de source basée sur des chemins XPath : *_xpath

XPath est un langage très puissant et peut être utilisé pour remplacer tous les sélecteurs CSS.

   "https://www.helsinkitimes.fi": {
		"favicon_url": "https://www.helsinkitimes.fi/templates/ja_teline_v/favicon.ico",
		"news_rss_url": "https://www.helsinkitimes.fi/?format=feed&type=rss",
		"search_url": "https://www.helsinkitimes.fi/search1332318146.html?searchword={}&ordering=newest&searchphrase=all",
		"res_nb": ".searchintro .bagde",
		"results": ".result-title",
		"r_h1": "a",
		"r_url": "a",
		"r_url_attr": "href",
		"r_dt_xpath": "./following-sibling::dd[@class='result-created'][1]/strong", (1)
		"r_txt_xpath": "./following-sibling::dd[@class='result-text'][1]",
		"r_by_xpath": "./following-sibling::dd[@class='result-category'][1]/span",
		"tags": { … }
	}
1 À la place d’une entrée r_dt normale, ici on a une entrée r_dt_xpath. Ce champs n’est donc pas défini par un sélecteur CSS mais par un sélecteur de chemin XPath. Dans ce cas précis, cela nous permet de désigner l’élément suivant relativement à l’élément courant, ce qui n’est pas possible en CSS.

On peut également noter que :

  • XPath permet de chercher un élément en fonction de s’il contient du texte, et même du texte qu’il contient

  • XPath permet d’atteindre l’élément parent de l’élément courant

  • Xpath permet d’accéder à un élément précédent sur la page

  • XPath permet d’accéder aux commentaires d’une page HTML

  • XPath est également nécessaire pour désigner des balises XML dont le nom fait partie d’un espace de nommage, comme c’est le cas du champs Auteur de la plupart des flux RSS (étendus via la DTD Dublin Core).

3. Expressions Rationnelles : *_re

Les expressions rationnelles (ou régulières, RegEx) sont un sujet complexe. Voici à nouveau un peu de documentation à ce propos : Expressions Régulières.

Si vous avez déjà travaillé avec des RegEx voici un rappel des quelques points à garder en tête concernant l’usage qui en est fait avec Meta-Press.es :

  • les motifs de reconnaissance doivent être délimités de chaque côté pour attraper tout et non pas une partie seulement de ce que vous souhaitez, par exemple ici : "\\s(\\d+?) " il y a n’importe quel blanc (\s espace ou tabulation) avant et après le groupe de chiffres à attraper.

  • vous aurez principalement besoin de : \\d+? \\w+? \\s+? (pour décrire des nombres, des mots et des blancs)

  • ensuite vous aurez principalement besoin de : () ()? (?:) pour extraire les motifs entre parenthèse, spécifier des motifs facultatifs suivit d’un ? et spécifier un motif à ne pas extraire, avec ?: au début de la parenthèse.

Les motifs à extraire sont ré-injectables dans le motif de remplacement via l’expression $1 pour le premier motif entre parenthèses, $2 pour le suivant…

4. Images : r_img

L’intégration des images dans les résultats de Meta-Press.es est possible via les champs r_img_src, r_img_alt et r_img_title, plus le raccourci r_img dans le cas d’une source HTML.

r_img permet de récupérer directement tous les champs d’une image. Il faut que le champs cible une balise HTML d’image <img … comportant l’attribut src et optionnellement un texte alternatif dans l’attribut alt et un titre dans l’attribut title.

S’il faut aller chercher ces informations ailleurs (comme pour Euronews où les valeurs sont à retrouver dans les attributs data-src, data-alt et data-title, ou Die Press où les valeurs sont éparpillées entre plusieurs balises) il est possible de compléter la définition de l’image avec les champs r_img_src, r_img_alt et r_img_title, éventuellement suivis des champs r_img_src_attr, r_img_alt_attr et r_img_title_attr.

Pour les sources de type JSON qui ont des images (telles que La Croix ou Les Echos), r_img n’est pas utilisable, r_img_src est obligatoire et il est recommandé d’ajouter r_img_alt et r_img_title s’il sont disponibles.

Il est tout à fait possible d’utiliser des expressions régulières sur ces champs avec re (ex. _El Mercurio(fotos)) ou des templates avec tpl (ex. _Les Echos).

5. Format de date

Meta-Press.es supporte tous les formats de date acceptés par l’instruction JavaScript : new Date("date_string") ainsi que les dates relatives anglaises comme 2 minutes ago, 8 hours ago et même today et yesterday.

5.1. Langues

Pour les sources d’autres langues, les dates doivent être converties dans l’un des formats supportés (c’est généralement le format ISO 8601 : aaaa/mm/jj hh:mm:ss tz qui est utilisé).

5.2. Multiple : r_dt_fmt_*

De plus de nombreuses sources utilisent un format qui varie en fonction de l’age des résultats. Il arrive ainsi que l’on rencontre un format de date relatif (« il y a 1h » « hier ») pour les dates proches et un format absolu (la date elle même) passé un certain temps. Pour faire face à tous les cas de figure il est possible de préciser plusieurs formats de date, numérotés ainsi : r_dt_fmt_1 r_dt_fmt_2 …

Ce "format" est tout simplement un motif de remplacement par expression rationnelle qui doit aboutir à un format supporté. Pour chaque résultat de la source en question, les formats de date seront essayés les uns après les autres en s’arrêtant au premier qui donne un résultat valide.

5.3. Fuseaux horaires : tz

Concernant les fuseaux horaires, Meta-Press.es utilise la fonction timezoned_date() du fichiers js/BOM_utils.js, elle-même construite autour de la fonction toLocaleTimeString() pour créer des dates appartenant à un fuseau horaire précis (celui fourni par l’entrée "tz" des "tags" s’il n’est pas inclu dans le format de date attrapé). Une fonction native de l’API JavaScript serait bienvenue dans ce domaine.

5.4. Conversion des noms de mois

Comme signalé en commentaire de l' exemple à base de sélecteur CSS, il est possible de convertir un nom de mois en son numéro en le faisant apparaitre dans le format de sortie, entouré d’accolades : $3-{$2}-$1.

Toutefois, si votre date est en anglais dans un journal de japonais, il faudra préciser une date_locale dans les tags pour que la conversion des noms de mois fonctionne.

Une date_locale est notamment mise en œuvre pour Arabnews.jp.

Le Corriere della Sera en utilise également une, avec une valeur spéciale : browser ; qui signifie que les dates sont servies dans la locale du navigateur web de l’utilisateur.

6. Étiquettes : tags

6.1. Étiquettes obligatoires

Il est impératif de reproduire au moins l’ensemble suivant d’étiquettes de classement (ou tags) pour chaque source définie :

"tags": {
	"name": "Mediapart.fr",
	"lang": "pt", (1)
	"country": "br", (2)
	"themes": [
		"general",
		"politics"
	],
	"tech": [ (3)
		"one word",
		"fast"
	],
	"src_type": [ (4)
		"Press",
		"Reference Press"
	],
	"res_type": [ (5)
		"text"
	],
	…
1 Le digramme de la langue selon la norme ISO 639. Dans cet exemple on imagine que Mediapart est brésilien pour illustrer la différence entre lang et country.
2 Le digramme du pays selon la norme ISO 3166. Dans cet exemple on imagine que Mediapart est brésilien pour illustrer la différence entre lang et country.
3 Les étiquettes de l’entrée "tech" fonctionnent principalement par paires :

  • one word ou many words dépendent de la capacité de la source donner des résultats correspondant à un mot ou à tous les mots d’une recherche. Si même pour un seul mot la source renvoie des résultats non pertinents ou approximatifs, on lui attribue l’étiquette approx, ces sources sont généralement décevantes si on les interroge sur des sujets pour lesquels elles n’ont pas de contenu, mais restent pertinentes pour les sujets largement couverts par la presse. Si la source est configurée pour renvoyer des résultats correspondant exactement à l’expression recherchée (par exemple parce qu’elle est intégrée avec des guillemets autour des termes de recherche dans son URL) on l’étiquette exact

  • fast ou slow dépend pour l’instant de la vitesse de chargement des résultats à froid sur le poste du développeur principal. Si les résultats mettent moins de 3s à arriver alors l’étiquette fast est attribuée. Il est prévu d’implémenter un test de vitesse à lancer sur le poste de chaque utilisateur afin d’avoir une meilleur répartition

  • indep. : si une source ne fait pas partie d’un grand groupe sans activité journalistique, ni n’est détenue par un état ou un groupe coté en bourse, elle peut être définie comme indépendante via cette étiquette

  • access content : quand la source fourni son contenu sur le web sans abonnement

  • direct content : quand la source livre son contenu intégral avec ses réponses et qu’il est donc lisible entièrement dans Meta-Press.es

  • for kids les sources "pour enfants" sont les seules disponibles lorsque le "mode enfant" est activé. Vous êtes également encouragés à préciser l’une des deux étiquettes : for kids < 9 ou for kids > 9 pour affiner en fonction de l’age, le public cible de la source

  • l’étiquette broken permet d’éviter une source (par exemple si elle vient d’être rapportée comme étant défectueuse) elle n’est alors plus disponible
4 Se référer à l’interface de Meta-Press.es en anglais pour la liste des types de source connus et utilisés
5 Se référer à l’interface de Meta-Press.es en anglais pour la liste des types de résultat connus et utilisés

6.2. Étiquettes optionnelles

	…
	"tz": "Europe/Paris", (1)
	"charset": "gb2312", (2)
	"date_locale": "en" (3)
}
1 Le fuseau horaire tz est une étiquette utile seulement si la date lisible dans les résultats ne comporte pas déjà cette information.
2 L’encodage des caractères (ou charset) n’est utile que pour les sources ne servant pas leurs page web en UTF8.
3 Préciser une locale spécifique aux dates n’est utile que si vous avez un nom de mois à convertir en son nombre et que la date n’est pas écrite dans la même langue que le reste du journal.

7. Pré-traitement sur les données : raw_rep_re

Les résultats sont parfois envoyés par le serveur dans un format hybride ou invalide.

Il est alors possible de spécifier un motif de remplacement par expression rationnelle afin d’extraire la portion de réponse utile (le code JSON contenu dans un JSONP ou un fichier RSS débarrassé de son entête invalide).

Cette fonctionnalité est pour l’instant implémentées pour les sources de type JSON et XML.

Plusieurs API de recherche tierces (Queryly, Algolia) permettent de préciser dans la requête HTTP GET un callback à exécuter lors de la réception des résultats. Quand ce paramètre est défini les résultats arrivent sous forme de JSONP, et il suffit donc de retirer ce paramètre de la requête pour que les résultats arrivent sous forme de JSON tout propre.

8. Rassembler plusieurs éléments pour un champs : *_tpl

Parfois l’information que l’on souhaite mettre dans un champs se retrouve éparpillée à plusieurs endroit sur la page de résultats, par exemple une date, éclatée en 3 morceaux…

Pour faire ça il est possible de définir une liste d’éléments (chemins JSON ou sélecteurs CSS…) pour le champs visé (exemple : r_txt) et d’ajouter une entrée r_txt_tpl, contenant une chaîne de caractère. Cette chaîne de caractère peut alors contenir des jetons de remplacement de la forme $1, $2 … correspondant à la valeur respective des éléments décrits dans la liste.

  "r_txt": ["description", "city"]
  "r_txt_tpl": "$1 ($2)"

De plus, il est possible de définir un r_txt_attr avec une liste de nom d’attributs à récupérer sur les éléments pointés.

Enfin, si le dernier attribut est manquant dans la liste, c’est le textContent de l’élément qui sera récupéré.

Voir arretsurimages.net ou publicsenat.fr pour des exemples.

9. Demander la permission d’une redirection : redir_url

Il arrive qu’une source ait besoin d’effectuer une redirection HTTP pour fournir ses résultats. S’il est possible de viser directement la 2e URL, ça reste le plus simple. Mais si ce n’est pas possible, comme avec le LeSoir.be alors on peut ajouter un champs redir_url dans la définition de la source. Meta-Press.es demandera alors également la permission d’hôte pour cette URL.

10. Configurer une requête préliminaire : token_url

Certaines sources ont besoin d’un jeton généré lors de l’affichage de leur page de recherche pour servir des résultats. D’autres ont besoin d’une requête préliminaire pour pouvoir configurer la langue dans laquelle seront servis les résultats.

Dans ces différents cas il est possible de définir une requête à réaliser avant de lancer la recherche.

Cette requête peut être aussi bien configurée que la recherche elle même :

	"token": {
		"token_url": "https://www.…",
		"token_method": "POST",
		"token_ctype": "application/json",
		"token_body": "{\\"lang\\": \\"fr\\"}"
	},

Un champs token_sel est également disponible afin d’extraire un élément de la page chargée et de pouvoir l’injecter dans l’URL de recherche de la source via le jeton de remplacement "{T}".

    "token": {
      "token_url": "https://www. … .com/search",
      "token_sel": "body > script:nth-of-type(8)",
      "token_sel_re": [
        "\"searchToken\":\"([^\"]+)\"",
        "$1"
      ]
    },
    "search_url": "https://www. … .com/search/api?qs={}&t={T}&sortBy=date",

11. Préciser le domaine : domain_part

Si une source utilise des URL relatives dans ses attributs href, mais que ces URL ont besoin d’être complétées d’un préfix contenant le domaine et des sous dossiers, vous pouvez ajouter un champs "domain_part" dans la définition de la source. Par exemple :

	"domain_part": "http://china.dailynk.com/chinese"

12. Filtrer les résultats d’une source approximative : filter_results

Certaines sources renvoient des résultats ne contenant pas exactement vos termes de recherche, elles sont étiquetées "approx" pour approximatives.

Parmi elles, certaines affichent (pour chaque résultat de recherche) la portion de texte contenant vos termes de recherche (ou leur version approximée). Il est donc possible, pour ces sources, de vérifier si les résultats contiennent vraiment les termes recherchés, et de ne garder que ces résultats là. Pour obtenir ce comportant, il faut ajouter l’entrée suivante dans la définition de la source :

	"filter_results": true,

13. Assistance

Si vous avez des questions auxquelles cette documentation ne répond pas au sujet de l’ajout de nouvelles sources dans Meta-Press.es, vous pouvez les poser (par ordre de préférence) :

  • soit dans une "Issue" du dépôt de code Framagit de Meta-Press.es ;

  • soit sur IRC : #meta-press.es@geeknode.org (de préférence en semaine aux horaires de bureau) ;

  • soit par courriel : meta-press.es /\ d12s [] fr

14. Documentations sur CSS, RegEx et XPath

14.1. JSON

La syntaxe JSON chez Mozilla ou json.org : gardez juste en tête qu’il faut utiliser des guillemets doubles et ne pas laisser de virgules trainantes.

14.2. Sélecteurs CSS

Documentation Mozilla concernant les sélecteur CSS

Une seconde doc. sur le sujet CSS selectors complète et bien illustrée, mais en anglais sur medium.com

14.3. RegEx : expressions rationelles

Expressions Régulières, par Mozilla.

Vue d’ensemble en anglais.

14.4. XPath

Documentations Mozilla en français.

XPath vision d’ensemble, en anglais

1. Ce qui permet par exemple de préciser innerHTML afin de récupérer quelque chose dans le texte d’un commentaire HTML.

Ressources

Installation via Mozilla

Sources via Framagit

Sponsor via Liberapay

Sponsor via HelloAsso

Social via Mastodon

Flux via RSS

Sponsors

Wau Holland Stiftung

Région Nouvelle Aquitaine

NLnet (NGI)

CopiePublique.fr