Citriq : une extension pour WordPress

citriq-wordpress-plugin

Vous utilisez WordPress pour votre blog littéraire ? L’extension Citriq pour WordPress peut vous aider à mieux référencer vos articles en créant automatiquement des liens entre vos critiques et d’autres critiques du même livre sur d’autres sites littéraires ! Citriq.net est aussi un moteur de recherche qui recensent des dizaines milliers de critiques littéraires issues de centaines de sites et blogs.

Installation

La première chose à faire est d’inscrire votre blog sur Citriq.net (si ce n’est pas déjà fait).

Citriq pour WordPress est disponible dans l’annuaire des extensions de WordPress, ce qui vous permettra de l’installer facilement et de bénéficier des mises à jour automatique à chaque nouvelle version. Rendez-vous dans l’onglet Extensions de WordPress, cliquer sur Rechercher et entrez Citriq comme mot-clé. Repérez l’extension, cliquez sur Installer maintenant puis sur Activez l’extension, et c’est tout !

Si vous préférez installer l’extension manuellement, voici la marche à suivre :

  1. Téléchargez le fichier zip de la dernière version de l’extension.
  2. Sur la page des extensions de WordPress, en haut à droite, cliquez sur Ajouter.
  3. Dans les onglets sous Installer des extensions, cliquez sur Envoyer.
  4. Sélectionnez sur votre ordinateur le fichier zip téléchargé plus tôt, puis cliquez sur Installez maintenant.
  5. Une fois l’installation terminée, cliquez sur Activer l’extension.
  6. L’extension est activée et prête à être utilisée !

Utilisation

Une fois l’extension installée et activée sur votre blog, il vous faudra utiliser les champs personnalisés de WordPress pour que l’extension sache lesquels de vos articles doivent être référencés sur Citriq, et à quel livre correspond la critique.

Il faudra donc, dans un premier temps, activer les champs personnalisés (si ce n’est pas déjà fait) en cliquant, sur la page d’écriture des articles, sur Options de l’écran (en haut à droite) puis en cochant la case Champs personnalisés.

citriq-wordpress-1

Pour signaler à l’extension qu’un article est une critique à référencer, il vous faudra renseigner l’ISBN du livre en créant un champ personnalisé isbn. Repérez la zone la zone Ajouter un champ personnalisé puis entrez isbn (en minuscule, c’est important) dans le champ Nom et l’ISBN du livre critique dans le champ Valeur. Cliquez enfin sur Mettre à jour pour enregistrer les modifications de votre article.

citriq-wordpress-2

NB : L’ISBN est un numéro unique attribué à chaque livre publié, long de 13 chiffres et commençant toujours par 978 ou 979. On le trouve dans les premières pages du livre ou au dos, généralement près du code barre. Il peut être entré avec ou sans tiret.

Répétez ensuite cette opération pour chaque article à référencer dans Citriq.

 Résolution des problèmes

Pour vérifiez que l’extension fonctionne correctement, ajoutez ?debug=1 ou &debug=1 à l’adresse de la page de l’article dans la barre de votre navigateur. Le widget Citriq affichera un message d’erreur détaillant le problème s’il y a lieu.

citriq-wordpress-debug

Si vous parvenez pas à résoudre le problème, n’hésitez pas poster le message d’erreur en commentaire à cet article (avec l’adresse de l’article posant problème), je tâcherai de vous aider.

Pour aller plus loin

Pour envoyer plus d’information à Citriq, il est possible d’utiliser d’autres champs personnalisés. Le champ isbn est le seul obligatoire, mais voici d’autres champs que vous pouvez utiliser :

  • excerpt : un extrait de la critique (jusqu’à 500 caractères) ;
  • reviewer : l’auteur de la critique (s’il y en a plusieurs sur le site) ;
  • source : support dont est issue la critique (si différent du site) ;
  • rating : permet d’indiquer une note (un entier, sur 100) ;

citriq-wordpress-custom-params

Historique des modifications

1.0.3 (13/02/2014)
  • Les liens s’affichent désormais aussi si la critique est affiché sur une page avec d’autres articles (accueil, catégorie, tag) mais l’adresse de la critique n’est pas enregistrée dans ce cas (paramètre ‘ignore’)
  • Ajout d’un paramètre ‘plugin’ pour détecter les blogs utilisateurs de l’extension à des fins statistiques
  • La date de publication de l’article est désormais transmise avec le paramètre ‘date’
1.0.2 (11/02/2014)
  • Suppression du fichier inutile wp_auto_update.class.php
1.0.1 (10/02/2014)
  • Suppression de la mise à jour automatique
1.0 (08/02/2014)
  • Première version de l’extension

Les blogs qui utilisent l’extension WordPress

N’hésitez pas à me signaler toute utilisation de cette extension (en précisant la version de WordPress utilisée). Outre le fait que ça me fera plaisir, je pourrais vérifier que tout fonctionne correctement et lister sur cette page les blogs utilisants l’extension.

Citriq : automatiser le référencement de vos critiques littéraires avec PHP

Si votre site ou blog utilise php, il est facile de lui faire écrire le petit code JavaScript permettant de référencer automatiquement vos critiques dans Citriq. Cela vous évitera d’avoir à les entrer une par une.

Voici une fonction qui permet de faire écrire automatiquement le code widget à PHP en fonction des paramètres reçus. Elle nécessite PHP 5.

Cette fonction permet notamment via deux nouveaux paramètres excerpt et rating d’envoyer à Citriq un extrait (jusqu’à 500 caractères) de la critique et une note (sur 100). Ces paramètres étaient jusqu’à présent réservés aux critiques entrées manuellement.  La fonction se charge en outre de l’encodage du texte dans les paramètres du widget de manière à ce que les caractères soient correctement pris en charge par Citriq.

La fonction

function citriq($params) {
  if(empty($params["uid"])) $error = "Le paramètre uid est obligatoire";
  elseif(empty($params["isbn"])) $error = "Le paramètre isbn est obligatoire";
  else return '<script type="text/javascript" src="http://citriq.net/w/crawl?'.http_build_query($params).'"><script>';
  if($params["debug"] == 1 && isset($error)) die("Erreur Citriq : ".$error); 
}

Utilisation

Cette fonction prend comme seule valeur un tableau php (array) dont les clés sont les différents paramètres du widget Citriq. Sauf mention contraire, ils sont tous facultatifs. Notez que les noms des paramètres sont toujours en minuscules.

  • uid (obligatoire) : l’identifiant unique de la critique dans votre base ;
  • isbn (obligatoire) : le code IBSN du livre critiqué ;
  • excerpt : un extrait de la critique (jusqu’à 500 caractères) ;
  • reviewer : l’auteur de la critique (s’il y en a plusieurs sur le site) ;
  • source : support dont est issue la critique (si différent du site) ;
  • rating : permet d’indiquer une note (un entier, sur 100) ;
  • date : la date de publication de la critique ;
  • ignore : permet d’afficher le widget sans enregistrer la page en cours ;
  • debug : si ce paramètre facultatif est égal à 1, Citriq affichera des informations statistiques et un éventuel message d’erreur sur votre site.

La fonction retourne le code javascript du widget préparé qu’on peut récupérer dans une variable ou afficher immédiatement avec l’instruction echo.

Exemple

Ci-dessous, un exemple de code (fictif) qui permettrait de référencer la critique publiée sur cette page, pour le résultat sur cette page.

$params["uid"] = 3601;
$params["isbn"] = 9782277492830;
$params["excerpt"] = "Quand, voici quelques mois, les jeunes éditions Dystopia Workshop publièrent Le Prophète et le vizir, la surprise fut de taille. On ne s’attendait pas le moins du monde à voir le couple Rémy revenir à l’écriture et publier de l’inédit. Il avait eu une assez belle carrière dans les années 70, dont plus d’un se serait satisfait, mais il semblait qu’elle fût désormais de...";
$params["reviewer"] = "Jean-Pierre Lion";
$params["source"] = "Bifrost 71";
$params["rating"] = "80"; // Equivaut à 4 étoiles sur 5
echo citriq($params);

Exemple avec WordPress

Il est possible d’utiliser les champs personnalisés de WordPress pour faire générer automatiquement le code du widget Citriq par WordPress. On trouvera plus d’information à ce sujet dans l’article Automatiser le référencement de vos critiques avec WordPress.

MAJ du 08/02/2014 : il existe aussi une extension WordPress pour Citriq, qui utilise cette fonction php mais est beaucoup plus simple à mettre en oeuvre.

$params["uid"] = get_the_id(); // L'identifiant de l'article WordPress
$params["isbn"] = get_post_meta(get_the_id(), "isbn", true); // Le champ personnalisé "isbn"
$params["reviewer] = get_the_author(); // L'auteur de l'article WordPress
$params["excerpt] = get_post_meta(get_the_id(), "extrait", true); // Le champ personnalisé "extrait"
if(is_singular()) echo citriq($params);

Résolution des problèmes

Si le code du widget ne s’affiche pas correctement, vous pouvez utilisez le paramètre facultatif debug pour afficher un message d’erreur. Si vous ne comprenez pas le message d’erreur, n’hésitez pas à poser la question dans les commentaires ci-dessous.

Bonus : l’équivalent en Python (merci Joachim)

Citriq : automatiser le référencement des critiques avec WordPress

Si vous avez un blog de critiques littéraires sous WordPress, il est possible d’automatiser simplement le référencement de vos critiques dans Citriq. La manipulation consiste à utiliser les champs personnalisés de WordPress pour associer à chaque critique l’ISBN du livre critiqué, puis de modifier votre thème pour qu’il génére automatiquement le code du widget Citriq en utilisant cet ISBN.

MAJ du 08/02/2014 : Il existe désormais une extension WordPress pour Citriq, bien plus facile à mettre en oeuvre, et qui vous évitera d’avoir à modifier votre thème.

Avant toute chose, il faut bien entendu, si ce n’est pas déjà fait, que votre blog soit inscrit à Citriq.

Marche à suivre

1. Choisissez une critique de votre blog déjà en ligne mais encore non référencée sur Citriq. Cliquez sur Modifier pour accéder à la page d’édition de l’article.

2. Cliquez en haut à droite de la fenêtre d’édition sur Options de l’écran, puis cochez la case Champs personnalisés pour faire apparaître la section correspondante sur la page d’édition, sous la zone de texte.

citriq-wordpress-1.jpg

3. Repérez la zone Ajouter un champ personnalisé et entrez isbn (en minuscules, c’est important) dans le champ Nom et entrez l’ISBN du livre critiqué dans le champ Valeur. Cliquez sur Mettre à jour pour enregistrer votre article.

citriq-wordpress-2.jpg

NB : L’ISBN est un numéro unique attribué à chaque livre publié, long de 13 chiffres et commençant toujours par 978 ou 979. On le trouve dans les premières pages du livre ou au dos, généralement près du code barre. Il peut être entré avec ou sans tiret.

Il va falloir ensuite modifier votre thème pour permettre à WordPress de générer automatiquement le code du widget Citriq. La manipulation peut varier selon le thème utilisé, dans les exemples ci-dessous, j’utilise le thème par défaut Twenty Twelve.

4. Rendez-vous dans le menu Apparence puis dans le sous-menu Éditeur pour modifier le thème actuellement utilisé. Dans la liste des fichiers à droite, ouvrez celui qui gère l’affichage des articles (ici content.php, parfois content-single.php).

citriq-wordpress-3.jpg

5. Repérez l’endroit où vous voulez faire apparaître le widget Citriq, probablement après le contenu du billet (affiché par la fonction the_content()). Copiez-collez-y le code php ci-dessous.

<?php 
    $isbn = get_post_meta(get_the_id(), "isbn", true);
    if(is_singular() && $isbn != '') echo '<script type="text/javascript" src="http://citriq.net/w/crawl?uid='.get_the_id().'&isbn='.get_post_meta(get_the_id(),'isbn',true).'"></script>'; 
    ?>

6. Cliquez sur Mettre à jour le fichier pour enregistrer vos modifications.

7. Vous pouvez à présent afficher le code source de l’article pour vérifier que le code Citriq est bien généré. Pensez à vider votre cache et celui de WordPress si le code ne s’affiche pas.

citriq-wordpress-4.jpg

8. Afin que le référencement automatique fonctionne, il faut que j’active l’option de mon côté dans Citriq pour votre blog. Une fois que vous avez ajouté le widget à votre thème et associé au moins un ISBN à une critique, contactez-moi pour que je vérifie que tout est en ordre et que j’active le référencement automatique.

9. Vous pourrez ensuite ajouter facilement d’autres critiques à Citriq. Il suffira à chaque fois d’indiquer l’ISBN du livre concerné dans le champ personnalisé isbn de chaque critique.

Si le code du widget n’apparaît pas dans le code source

  • Vérifiez que vous avez bien le nom du champ personnalisé isbn en minuscule et non en majuscule.
  • Vérifiez que le fichier que vous avez modifié (content.php dans l’exemple) est bien celui qui gère l’affichage d’un article seul, par exemple en effectuant d’autres modifications pour voir si elles apparaissent.
  • Si vous utilisez une extension pour gérer le cache, pensez à le vider.
  • Effectuez les vérifications décrites sur cette page (en anglais).

Résolution des problèmes

Si le code du widget est correctement généré mais que le référencement ne fonctionne pas, ajoutez ?debug=1 ou &debug=1 à l’adresse de la page de l’article dans la barre de votre navigateur. Le widget Citriq affichera un message d’erreur détaillant le problème s’il y a lieu.

citriq-wordpress-5.jpg

Pour aller plus loin

Nous avons vu ci-dessus un cas simple d’utilisation du widget, mais il est également possible d’utiliser d’autres champs personnalisés pour communiquer à Citriq d’autres informations lors du référencement de la critique. Il faut pour cela modifier le code du widget pour ajouter d’autres paires clés/valeurs et créer les nouveaux champs personnalisés équivalents. Par défaut, le code du widget se présente ainsi :

<script type="text/javascript" src="http://citriq.net/w/crawl?uid=9&isbn=978-2-207-11266-3"></script>

Avec deux variables obligatoires : uid qui est un identifiant unique (ici on utilise l’identifiant de l’article dans la base WordPress affiché grâce à la fonction get_the_id()) et isbn qui correspond à l’ISBN du livre concerné (notre champ personnalisé, affiché grâce à la fonction get_post_meta()).

Il existe trois autres variables facultatives :

  • reviewer : le nom de l’auteur de la critique (utile si plusieurs chroniqueurs interviennent sur le même blog)
  • source : la source originelle de la critique (par exemple, nooSFere référence, en plus de ses propres critiques, des critiques issues de Bifrost, Galaxies, etc.)
  • note : la note donnée au livre, qui doit être sur 100 (3/5 = 60, 18/20 = 90, etc.)
  • excerpt : un extrait de la critique (500 caractères maximum). Pour un résultat optimal, il vaut mieux encoder le texte, par exemple avec la fonction php urlencode().

Pour utiliser une variable, il suffit de d’ajouter les variables sous la forme &clé=valeur au code du widget, par exemple :

<script type="text/javascript" src="http://citriq.net/w/crawl?uid=9&isbn=978-2-207-11266-3&reviewer=Clément&note=75"></script>

Il faudra pour cela ajouter un premier champ personnalisé reviewer et un deuxième note à chaque article, puis utiliser la fonction get_post_meta() pour générer le code du widget en utilisant ces champs. Voici le code php à insérer dans ce cas :

<?php

    $isbn = get_post_meta(get_the_id(), "isbn", true);
    if(is_singular() && $isbn != '') echo '<script type="text/javascript" src="http://citriq.net/w/crawl?uid='.get_the_id().'&isbn='.get_post_meta(get_the_id(),'isbn',true).'&reviewer='.get_post_meta(get_the_id(),'reviewer',true).'&note='.get_post_meta(get_the_id(),'note',true).'&excerpt='.urlencode(get_post_meta(get_the_id(),'excerpt',true)).'"></script>';

?>

Bien sûr, il n’est pas toujours pertinent d’utiliser les champs personnalisés. Pour l’auteur de la critique (reviewer), on utilisera plus probablement l’auteur de l’article dans WordPress, en utilisant la fonction the_author() plutôt que la fonction get_post_meta().

Voici un exemple de code qui ne transmettra à Citriq que l’ISBN (d’après le champ personnalisé isbn) et le nom de l’auteur du billet :

<?php

    $isbn = get_post_meta(get_the_id(), "isbn", true);
    if(is_singular() && $isbn != '') echo '<script type="text/javascript" src="http://citriq.net/w/crawl?uid='.get_the_id().'&isbn='.get_post_meta(get_the_id(),'isbn',true).'&reviewer='.the_author().'"></script>';

?>

Quelques blogs sous WordPress qui utilisent le référencement automatique

CITRIQ ouvert au public

J’en parlais dans la dernière Lettre d’Ys : mon projet CITRIQ avance peu, faute de temps libre pour avancer dessus. Mais la partie moteur de recherche est déjà fonctionnelle, c’est pourquoi j’ai décidé d’ouvrir le site au public, bien qu’il ne soit pas finalisé. N’hésitez donc pas à me faire part de vos retours dans les commentaires de ce billet !

En attendant le beta-test public (où tout un chacun pourra ajouter les critiques de son blog à CITRIQ), je teste l’intégration de gros sites de l’envergure de ceux qui participaient à SEDNA (la condition requise étant de disposer des ISBN dans la base de données pour pouvoir automatiser l’ajout des critiques). Si vous êtes rédacteur ou responsable d’un site de ce genre, n’hésitez pas à me contacter !

http://citriq.net/