Steve Frécinaux

Dotclear : comment utiliser le plug-in Métadonnées de billets ?

Samedi, vous découvriez ici-même une première version du plug-in Métadonnées de billets pour Dotclear 1.2. Un mot avait alors été donné sur l’interface d’administration, mais au niveau des modifications à apporter au gabarit, rien, si ce n’est une succinte description des deux fonctions principales. Pour ceux qui bloquent, voici donc à présent deux petits exemples d’utilisations : l’affichage de la valeur d’un champ unique (en l’occurence l’endroit où le billet a été écrit) d’une part, et une implémentation très simple des désormais incontournables tags.

Afficher la valeur d’un champ unique

Admettons que vous soyez un carnettiste itinérant, qui écrit le plus souvent depuis son fauteuil dans sa maison de Maubeuge (Tout ça n’vaut pas…), mais aussi depuis les endroits les plus divers où il part en voyage toutes les mois. Dans ce cadre, il peut être intéressant de renseigner, auprès de chaque billet, l’endroit où vous vous trouvez lors de sa rédaction.

Sachant que le plug-in n’oblige aucunement à remplir un champs tel qu’il soit, on va dire qu’un billet dont le champs location n’aura pas été renseigné aura d’office été écrit à Maubeuge, qui sera en quelque sorte la valeur par défaut du champs. Ceci permettra d’éviter quelques clics dans le cas le plus courant, et aussi de rendre sans importance un oubli (En effet, des erreurs auraient pu surgir si on était parti du principe que le champs était d’office renseigné). Une fois ces détails déterminés, nous allons définir une fonction sur le modèle de celles fournies par Dotclear pour usage dans le gabarit : la fonction myPostLocation() :

<?php
# Afficher l'endroit d'où le billet a été rédigé
function myPostLocation($default)
{
	# On récupère la valeur du champs "location"
	$location = twPostMeta::field('location', TWPM_F_FIRST);
	
	# Si le champs n'est pas défini -> valeur par défaut
	if ($location === false)
		$location = $default;

	# Affichage
	echo (htmlspecialchars($location));
}
?>

L’argument TWPM_F_FIRST fait en sorte que la fonction renvoie la première valeur définie pour le champs. Si le champs n’est pas défini, la valeur retournée est alors false, et on affiche la valeur par défaut, fournie en argument.

Insérez le code de cette fonction dans le fichier prepend.php de votre thème, et vous pourrez utiliser la fonction, tant dans les boucles (fichier list.php) que dans le billet (fichier post.php). Il suffit alors de l’appeler, par exemple :

<p class="post-info">Par <?php dcPostAuthor(); ?>,
<?php dcPostDate(); ?> &agrave; <?php dcPostTime(); ?>
<span class="added"><span>::</span> <?php myPostLocation('Maubeuge (France)'); ?></span>
<span>::</span> <a href="<?php dcPostCatURL(); ?>"><?php dcPostCatTitle(); ?></a>
</p>

Reste un petit détail à régler, la question des performances. Là, c’est simple, on va ajouter un appel de fonction au début du fichier de gabarit pour initialiser le cache, c’est à dire récupérer tout ce qu’il faut dans la base de données directement, plutôt que d’attendre qu’on en ait effectivement besoin. Ajoutez donc ceci tout en haut du fichier template.php de votre thème :

<php twPostMeta::cache(); ?>

Les tags, simplement

Le principe est le même que précédemment. Seule différence notable : on peut définir plusieurs tags pour un même billet (sans quoi ils n’auraient pas le moindre intérêt), ce qui se traduit par des valeurs multiples pour notre champs tag. Dans le code de notre fonction myPostTags, ça se traduit par un argument différent lors de l’appel de la fonction twPostMeta::field() :

<?php
# Afficher les tags attribués au billet courant
function myPostTags()
{
 	$tags = twPostMeta::f('tag', TWPM_F_ALL);

	# S'il y a des tags définis, on les affiche par ordre alphabétique
	if ($tags && count($tags))
	{
		usort($tags, create_function('$x,$y', 'return strcmp(strtolower($x),strtolower($y));'));
		echo (htmlspecialchars(implode(', ',$tags))); 
	}
}
?>

Comme d’habitude cette fonction est à placer dans le fichier prepend.php de votre thème. TWPM_F_ALL fait que la valeur renvoyée par twPostMeta::field() est un tableau contenant toutes les valeurs définies pour le champs, vide si le champs n’est pas défini. Le reste se passe de commentaires.

Cerise sur le gâteau, une autre fonctionnalité que je n’ai pas encore commentée au sujet du plug-in Métadonnées de billets est le fil RSS mis à disposition. Celui-ci liste les derniers billets dont le champs $key a la valeur $value. Il se trouve au même endroit que le fil par défaut (le répertoire d’installation de Dotclear), et s’appelle comme ceci : /dotclear /rss-meta.php?key=$key&value=$value. Dans notre cas, ça veut dire qu’on peut lister les derniers billets comportant le tag dotclear avec le fil /dotclear/rss-meta.php?key=tag&value=dotclear.

Mise à jour : Le même sous forme de plug-in.

NB.: L’article décrivant la fonctionnalité “Planet” est postposé pour cause de changements profonds à ce niveau pour la prochaine version. Ceci dit, l’idée générale est de définir une liste de mots-clefs prédéfinis, auxquels correspondent des fils RSS pouvant être réutilisés par les scripts d’agrégation du type planète. La chose à savoir, c’est que dans ce cas, $key = 'planet'.

J’espère que ce petit article vous aura permis d’y voir plus clair dans le fonctionnement du plug-in côté gabarit. Comme d’habitude, si quelque chose vous chagrine, n’hésitez pas à poser une question, les commentaires sont faits pour ça ;-)