• Introduction
• Installation
• Manager
• Gabarits
• Développement
• Etudes de cas
• Annexe A
• Glossaire
• Table des Matières
• Retour à l'accueil

Chapitre 4 - Les gabarits

4.1. Structure des thèmes

Tous les thèmes sont rangés dans le dossier /manager/templates/. Chacun à son propre dossier, nommé par son identifiant. Ainsi le thème par défaut de Plume CMS est représenté par le dossier /manager/templates/default ("default" est la traduction anglaise pour "défaut") qui contient tous les fichiers nécessaires à la personnalisation graphique de l'application :

• une série de fichiers *.php ;
• un fichier nommé desc.xml ;
• un fichier image preview.png ;
• un dossier /style/ contenant la ou les feuille(s) de style *.css et images composant le thème ;
• et un dossier /inc/ contenant d'autres fichiers *.php.

4.1.1. Les fichiers PHP

Les fichiers PHP sont les gabarits : ils constituent les modèles de pages qui seront utilisés par Plume. En substance, ce sont des pages contenant du code (X)HTML dans lesquelles sont insérées des portions de code PHP, ou fonctions, permettant de générer un contenu dynamique.

• feed.atom est le gabarit qui génèrera le flux RSS du site au format *.xml. Ne vous laissez pas abuser par l'extension *.atom, ce fichier contient bien du code PHP.
• 404.php est le gabarit qui gèrera les erreurs de type 404.
• category_category.php est le gabarit affichant le contenu des catégories.
• category_homepage.php est le gabarit de la page d'accueil.
• comments_inline.php est le gabarit permettant l'affichage du formulaire de soumission de commentaires pour une ressource.
• comments_list.php est le gabarit servant à l'affichage de tous les commentaires d'une ressource.
• comments_post.php est le gabarit servant à l'aperçu des commentaires, avant soumission définitive donc.
• resource_article.php est le gabarit servant à l'affichage des ressources de type "article".
• resource_news.php est le gabarit servant à l'affichage des ressources de type "brèves".
• search.php est le gabarit grâce auquel seront affichés les résultats d'une recherche sur le site.
• sitemap.php est le gabarit servant à l'affichage d'un plan de site.

4.1.2. Les fichiers « desc.xml » et « preview.png »

Ces fichiers sont utilisés lorsque vous éditez un site via le Manager (onglet Sites). L'aperçu du thème et sa description sont respectivement issus des fichiers preview.png et desc.xml.

4.1.2.1. Le fichier « desc.xml »

Ce fichier est de la forme suivante pour le thème par défaut :

<?xml version="1.0" encoding="utf-8"?>
<theme name="default" version="1.0" active="true">
   <author>Jérémie PAPE</author>
   <label>1.2 Default theme</label>
   <desc>Default Plume CMS theme</desc>
</theme>

L'élément important de ce fichier est l'attribut name de la balise theme. Notez que le nom ici est default. Il correspond à l'identifiant du thème et est similaire au nom du répertoire dans lequel est stocké ledit thème. Admettons que vous créez un thème bleuciel, vous le placerez alors dans le dossier /manager/templates/bleuciel/ et votre fichier desc.xml ressemblera à :

<?xml version="1.0" encoding="utf-8" ?>
<theme name="bleuciel" version="1.3" active="true">
 <author>Votre nom</author>
 <label>BleuCiel</label>
 <desc>Un thème bleu ciel</desc>
</theme>

Vous pouvez attribuer un numéro de version à votre thème grâce à l'attribut version. Dans notre exemple, le thème bleuciel est dans sa version 1.3.

4.1.2.2. Le fichier « preview.png »

C'est une simple image de 388 x 151 pixels au format *.png. Laissez faire votre imagination pour produire un bel aperçu de votre thème !

4.1.3. Le dossier « /style »

Ce dossier contient les feuilles de styles CSS, et éventuellement un sous-dossier /img, lui-même contenant les images utilisées par votre thème.

En l'occurrence, le thème par défaut de Plume CMS propose deux feuilles de styles CSS:

• rss.css qui décrit la mise en forme du flux RSS de votre site ;
• style.css qui décrit la mise en forme de votre thème.

4.1.4. Le dossier « /inc »

Le dossier /inc est une subtilité introduite par défaut depuis la branche 1.2 de Plume CMS. La "raison d'être" de ce dossier est de répondre au concept de la non-duplication des données (ou, en anglais DRY pour don't repeat yourself, ne vous répétez pas).

Le principe est fort simple. Un site suit une charte qui définit son apparence et sa structure au niveau du code (X)HTML et parfois même PHP. Il est fort probable que des éléments de cette charte restent inchangés durant les différents stades de la navigation du site. Par exemple, un haut de page et un pied de page seront identiques que vous soyez à l'accueil du site ou bien en train de consulter un article.

Du point de vue des gabarits de pages, cela veut dire que les portions de code pour le haut et le pied de page sont les mêmes. Le but du DRY sera donc de ne pas écrire plusieurs fois ces portions pour chaque gabarit, mais plutôt de les en séparer. De cette façon, vous créez un fichier, *.php en l'occurrence, par morceaux de code à ne pas répéter, que vous insérez par la suite dans le gabarit contenant la présentation générale via une ligne de code PHP.

Les parties ainsi extraites pour le thème par défaut de Plume CMS sont les suivantes :

• easy-access.php est le bloc contenant le menu de navigation rapide et le formulaire de recherche ;
• footer.php est le pied de page ;
• head-link.php contient toutes les balises <link /> statiques que l'on trouve dans l'entête (X)HTML des gabarits ;
• head-meta.php contient toutes les balises;<meta /> statiques que l'on trouve dans l'entête (X)HTML des gabarits ;
• recent-news.php est un bloc affichant les 3 dernières brèves publiées ;
• rss-sitemap.php est le bloc contenant les liens vers le plan de site et le flux ATOM.

Chacun de ces fichiers est inséré dans les gabarits qui le nécessite grâce à du code PHP placé à l'endroit précis où il doit "apparaître". Le code est de la forme :

<?php include(dirname(__FILE__).'/inc/nom-du-fichier.php'); ?>

Remplacez nom-du-fichier.php par celui idoine. Si vous avez observé une arborescence correcte durant l'élaboration de votre thème aucun problème d'inclusion de fichiers ne devrait survenir. Le choix du code à séparer des fichiers de gabarits ne tient qu'à la façon dont vous avez conçu votre thème. Ce qui est proposé dans le thème par défaut est un exemple type, libre à vous de l'adapter selon vos besoins ou de l'adopter tel quel.

4.1.5. Le mécanisme sous-jacent des thèmes

Nous disions précédemment que les thèmes devaient être placés dans le dossier /manager/templates/. Toutefois, la curiosité n'étant pas forcément un vilain défaut, vous aurez sûrement remarqué en consultant le code source d'une page quelconque de votre site ce fait étrange :

<link rel="stylesheet" type="text/css" 
href="/xmedia/theme/default/style.css" 
media="screen" />

Pourquoi les feuilles de style et autres images utilisées par le thème du site sont-elles localisées à cette adresse : /xmedia/theme/default/style.css ? Cela ne tient pas du mystère, mais d'une mécanique bien huilée de Plume CMS.

Tout commence alors que vous choisissez le thème à utiliser dans le Manager (onglet Sites). À ce moment précis est alors déclenchée une routine interne qui copie les fichiers nécessaires du thème sélectionné vers le dossier /xmedia/theme/mon-theme. On désigne par fichiers nécessaires du thèmes, les feuilles de style, les images et toute autre fioriture que vous auriez pu y ajouter, tels que des fichiers JavaScript ; les gabarits sont conservés à leur place originelle. Notez que ce mécanisme de copie garde intact l'arborescence que vous avez appliqué à l'intérieur de votre dossier de thème.

Il est probable que vous vous demandiez alors, mais pourquoi existe-t-il une telle mécanique ? Dans quel but ?

La réponse réside essentiellement dans une fonctionnalité de Plume CMS : l'architecture multi-sites ! En effet, lorsque vous mettez en oeuvre une telle architecture, vous disposez d'un seul et unique Manager pour la totalité de vos sites ; et il en va de même pour les fichiers qui le constitue. Ainsi, lorsque vous installez un nouveau thème, il sera rendu disponible à l'utilisation pour tous les sites. Et lorsque le thème sera effectivement utilisé, seuls les fichiers nécessaires seront copiés dans le dossier /xmedia/theme/mon-theme du site correspondant.

À partir de là, vous pourrez, par exemple, accéder à votre feuille de style style.css à l'intérieur d'un gabarit de la manière suivante :

<link rel="stylesheet" type="text/css" 
href="<?php pxInfo('filesurl'); ?>theme/default/style.css"
media="screen" />

Ce qui rendra bien en (X)HTML la ligne suivante :

<link rel="stylesheet" type="text/css" 
href="/xmedia/theme/default/style.css" 
media="screen" />

Nota : Vous trouverez plus d'informations sur la fonction pxInfo au paragrahe 4.3.1.1. pxInfo.

4.1.6. Démystifier la chaîne de substitution

Le thème par défaut de Plume CMS est un des exemples type d'utilisation des fonctions que vous proposent l'application pour constituer vos gabarits de pages. Vous trouverez la liste exhaustive et commentée des fonctions ci-dessous. Si possible, appuyez-vous sur les fichiers du thème pendant que vous consultez cette liste. En effet, les gabarits qui y sont proposés utilisent des fonctions "fondamentales" qui, à elles seules, permettent de créer un thème conséquent pour un site des plus accessibles.

Comme vous pouvez le voir, construire ses propres gabarits se résume essentiellement à placer des fonctions PHP dans du code (X)HTML. Pour ceux que cela peut rebuter, sachez qu'il n'y a pas de difficultés insurmontables : tout est histoire de patience, de curiosité et d'astuce. Bien qu'il vous faille connaître (X)HTML et CSS pour échaffauder votre mise en page, aucun pré-requis spécifique quant à PHP n'est obligatoire. Certes, connaître au moins la syntaxe du langage est un plus, mais pas une condition sine qua non.

Toutefois, il est possible qu'une notion puisse vous effrayer, celle de la chaîne de substitution, notée %s lors de la mise en oeuvre. La majeure partie des fonctions proposées ci-dessous requièrent son utilisation, vous aimerez sûrement savoir de quoi il en retourne plutôt que de l'utiliser à l'aveuglette.

Commençons donc par voir ce qu'il en est du côté de PHP. Le système de gabarits de Plume CMS est basé sur une bibliothèque de fonctions, elle-même construite autour de la fonction PHP sprintf. On peut dire que, grossièrement, sprintf permet de renvoyer des données quelconques formatées selon certains critères. L'un de ces critères, noté %s, indique que le résultat sera traité et présenté comme une chaîne de caractères.

Dans le contexte de Plume CMS, que peut bien représenter ce %s ? En premier lieu, la chaîne de substitution indique à la fonction qui la nécessite que son résultat sera une chaîne de caractères, et qu'elle devra être présentée en tant que telle ; de la même manière que PHP donc. En second lieu, la chaîne de substitution pourra éventuellement indiquer la place où sera renvoyée les données qu'elle représente. Prenons un exemple pratique : la fonction pxPrimaryCategories. Elle permet de générer une liste non-ordonnée des catégories principales définies dans Plume CMS. Nous allons la mettre en oeuvre pour créer un menu de la forme :

<ul id="menu">
  <li class="accueil"><a href="#accueil">Retour à l'accueil</a></li>
  <li><a href="#catégorie-1">Catégorie 1</a></li>
  <li><a href="#catégorie-2">Catégorie 2</a></li>
  <!-- etc... -->
</ul>

Il faudra alors employer ladite fonction de cette manière :

<?php pxPrimaryCategories('<ul id="menu">
                           <li class="accueil"><a href="#accueil">Retour à l'accueil</a></li>
                           %s
			    </ul>') 
?>

4.2. Fonctions de boucles

Il est possible d'utiliser certaines fonctions à l'intérieur de boucles pour accéder de manière récurrente à des informations spécifiques, ce qui permet d'alléger le code source des gabarits et d'en faciliter la maintenance.

4.2.1. La boucle $res

Cette boucle est utilisable dans les gabarits de catégories. Elle permet d'obtenir les ressources contenues dans la catégorie en cours. Par exemple :

<?php while (!$res->EOF()): ?>
  <div class="resource">
  <h2><a href="<?php pxResPath(); ?>"><?php pxResTitle(); ?></a></h2>
  <?php pxResDescription(); ?>
  </div>
<?php 
$res->moveNext(); 
endwhile; ?>

4.2.1.1. pxResTitle

Cette fonction permet l'affichage du titre d'une ressource.

pxResTitle( $s )

• $s : '%s' est la chaîne de substitution.

4.2.1.2. pxResPath

Cette fonction affiche le chemin de la ressource.

pxResPath( $type )

• $type :
  • 'full' donne le chemin absolu, avec http://.
  • 'relative', par défaut il est en relatif. Il est alors inutile de préciser le paramètre.

4.2.1.3. pxResDescription

Cette fonction affiche par défaut la description complète d'une ressource. Si une limite est donnée, la description est convertie en texte brut puis la limite est appliquée.

pxResDescription( $s, $limit )

• $s : '%s' est la chaîne de substitution.
• $limit est la limite numérique du nombre de mots (le décompte s'effectue par le nombre de caractères pour le moment) afin de restreindre la description. Si vous ne voulez pas donner de limite, omettez ce paramètre.

4.2.1.4. pxResCategories

Cette fonction affiche une liste de liens vers les catégories dans lesquelles la ressource est disponible. La liste générée n'est pas une liste HTML mais est construite comme une phrase ponctuée par les délimiteurs $p1 et $p2.

pxResCategories( $s, $p1, $p2 )

• $s : '%s' est la chaîne de substitution.
• $p1 : ', ' est le premier délimiteur et est affiché par défaut.
• $p2 : ' and ' est le dernier délimiteur et est affiché par défaut.

4.2.1.5. pxResAuthor

Cette fonction affiche le nom de l'auteur.

pxResAuthor( )

4.2.1.6. pxResAuthorEmail

Cette fonction affiche l'adresse courriel publique si l'auteur l'a définie dans ses préférences. La possibilité d'encoder l'adresse permet de ne pas laisser celle-ci en clair dans le code source de la page.

pxResAuthorEmail( $s, $encoding )

• $s : 'mailto:%s' est la chaîne de substitution.
• $encoding :
  • 'link' génère un lien "mailto" encodé en hexadécimal de la forme %6c pour le caractère "l". Valeur par défaut.
  • 'text' génère un lien "mailto" encodé en entités hexadécimales de la forme &#x6c pour le caractère "l".

4.2.1.7. pxResDateModification

Cette fonction affiche la date de modification de la ressource. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxResDateModification( $dateformat )

• $dateformat : '%Y-%m-%dT%H:%M:%S+00:00' est le format de date défini par défaut, soit 2006-11-14T23:42:52+00:00.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.2.1.8. pxResDatePublication

Cette fonction affiche la date de publication de la ressource. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxResDatePublication( $dateformat )

• $dateformat : '%Y-%m-%dT%H:%M:%S+00:00' est le format de date défini par défaut, soit 2006-11-14T23:42:52+00:00.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.2.1.9. pxResAssociatedLink

Cette fonction affiche le lien associé à une brève s'il est disponible. Il faut que la brève ait été saisie avec cette information, le cas contraire, la fonction ne renvoie rien.

pxResAssociatedLink( $s, $return )

• $s : '<a href="%1$s">%2$s</a>' est la chaîne de substitution par défaut.

4.2.1.10. pxResSearchScore

Cette fonction affiche le score de pertinence d'une ressource dans le résultat d'une recherche. Elle ne peut être utilisée que dans un gabarit de recherche (search.php).

pxResSearchScore( $s )

• $s : '%s' est la chaîne de substitution.

4.2.1.11. pxResCountComments

Cette fonction affiche le nombre de commentaires affichés dans une ressource.

pxResCountComments( $s )

• $s : '%s' est la chaîne de substitution.

4.2.2. La boucle $last

Cette boucle est utilisable dans tous les gabarits, vous devez juste l'initialiser auparavant avec la fonction pxGetLastResources. Par exemple :

<?php pxGetLastResources(); ?>
<?php while (!$last->EOF() ): ?>
   <p><a href="<?php pxLastResPath(); ?>"><?php pxLastResTitle(); ?></a></p>
<?php
$last->moveNext();
endwhile; ?>

4.2.2.1. pxGetLastResources

Cette fonction extrait la liste des dernières ressources et la place dans la variable $last pour une utilisation ultérieure par la boucle $last. Cette dernière ne peut donc être utilisée qu'après un appel à la fonction pxGetLastResources.

pxGetLastResources( $limit, $type, $category )

• $limit est le nombre de ressource à afficher. Le paramètre doit donc être un entier positif. Par défaut, la limite est de 5.
• $type est le type de ressource à afficher. Par défaut, tous les types confondus sont pris en compte.
  • '' pour toutes les ressources ;
  • 'news' pour les brèves ;
  • 'articles' pour les articles.
• $category est l'identifiant de la catégorie. Vous trouverez les identifiants de catégories via le Manager. Par défaut, toutes les catégories sont prises en compte.

4.2.2.2. pxLastResTitle

Cette fonction affiche le titre de la ressource.

pxLastResTitle( $s )

• $s : '%s' est la chaîne de substitution.

4.2.2.3. pxLastResPath

Cette fonction affiche le chemin de la ressource.

pxLastResPath( $type )

• $type :
  • 'full' donne le chemin absolu, avec http://.
  • 'relative', par défaut il est en relatif. Il est alors inutile de préciser le paramètre.

4.2.2.4. pxLastResDescription

Cette fonction affiche par défaut la description complète d'une ressource. Si une limite est donnée, la description est convertie en texte brut puis la limite est appliquée.

pxLastResDescription( $s, $limit )

• $s : '%s' est la chaîne de substitution.
• $limit est la limite numérique du nombre de mots (le décompte s'effectue par le nombre de caractères pour le moment) afin de restreindre la description. Si vous ne voulez pas donner de limite, omettez ce paramètre.

4.2.2.5. pxLastResAuthor

Cette fonction affiche le nom de l'auteur.

pxLastResAuthor( )

4.2.2.6. pxLastResAuthorEmail

Cette fonction affiche l'adresse courriel publique si l'auteur l'a définie dans ses préférences. La possibilité d'encoder l'adresse permet de ne pas laisser celle-ci en clair dans le code source de la page.

pxLastResAuthorEmail( $s, $encoding )

• $s : 'mailto:%s' est la chaîne de substitution.
• $encoding :
  • 'link' génère un lien "mailto" encodé en hexadécimal de la forme %6c pour le caractère "l". Valeur par défaut.
  • 'text' génère un lien "mailto" encodé en entités hexadécimales de la forme &#x6c pour le caractère "l".

4.2.2.7. pxLastResDateModification

Cette fonction affiche la date de modification de la ressource. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxLastResDateModification( $dateformat )

• $dateformat : '%Y-%m-%dT%H:%M:%S+00:00' est le format de date défini par défaut, soit 2006-11-14T23:42:52+00:00.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.2.2.8. pxLastResDatePublication

Cette fonction affiche la date de publication de la ressource. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxLastResDatePublication( $dateformat )

• $dateformat : '%Y-%m-%dT%H:%M:%S+00:00' est le format de date défini par défaut, soit 2006-11-14T23:42:52+00:00.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.2.2.9. pxLastResAssociatedLink

Cette fonction affiche le lien associé à une brève s'il est disponible. Il faut que la brève ait été saisie avec cette information, le cas contraire, la fonction ne renvoie rien.

pxLastResAssociatedLink( $s )

• $s : '<a href="%1$s">%2$s</a>' est la chaîne de substitution.

4.2.2.10. pxLastResCategories

Cette fonction affiche une liste de liens vers les catégories dans lesquelles la dernière ressource est disponible. La liste générée n'est pas une liste HTML mais est construite comme une phrase ponctuée par les délimiteurs $p1 et $p2.

pxLastResCategories( $s, $p1, $p2 )

• $s : '%s' est la chaîne de substitution.
• $p1 : ', ' est le premier délimiteur et est affiché par défaut.
• $p2 : ' and ' est le dernier délimiteur et est affiché par défaut.

4.2.2.11. pxLastResCountComments

Cette fonction affiche le nombre de commentaires affichés dans une ressource.

pxLastResCountComments( $s )

• $s : '%s' est la chaîne de substitution.

4.3. Fonctions informatives

4.3.1. Fonctions informatives générales

4.3.1.1. pxInfo

Cette fonction affiche les informations concernant le site Web.

pxInfo( $name )

• $name :
  • 'name' retourne le nom du site Web ;
  • 'url' retourne l'adresse relative du site Web ;
  • 'fullurl' retourne l'adresse absolue du site Web ;
  • 'filesurl' retourne l'adresse relative aux images et fichiers du site Web ;
  • 'lang' retourne la langue du site Web ;
  • 'namexml' retourne le nom du site Web encodé en utf-8 ;
  • 'description' retourne la description du site web.

4.3.1.2. pxHeadLinks

Cette fonction génère les balises <link /> et <meta />, à placer dans la section <head> du gabarit.

pxHeadLinks( )

4.3.1.3. pxRssSeq

Cette fonction génère une séquence de description RSS.

pxRssSeq( )

4.3.1.4. pxRssItems

Cette fonction génère une séquence d'un item RSS.

pxRssItems( )

4.3.1.5. pxPrimaryCategories

Cette fonction affiche une liste HTML non ordonnée de liens pointant vers les catégories primaires, c'est-à-dire celles ayant la catégorie racine / comme parente.

pxPrimaryCategories( $s )

• $s : '<ul>%s</ul>' est la chaîne de substitution.

4.3.1.6 pxSubCategories

Cette fonction affiche une liste des sous-catégories sous la forme d'une liste HTML non ordonnée.

pxSubCategories( $s )

• $s : '%s' est la chaîne de substitution.

Notez que cette fonction rend une liste dont le code HTML est généré automatiquement, il n'y a donc aucunement besoin d'entourer la chaîne de substitution de balises. La liste générée sera simplement de la forme :

<ul>
  <li><a href="#le-lien">Sous catégories</a></li>
</ul>

4.3.1.7. pxSearchQuery

Cette fonction affiche la chaîne recherchée. Elle n'est utilisable que dans un gabarit de recherche search.php

pxSearchQuery( $s )

• $s : '%s' est la chaîne de substitution.

4.3.2. Fonctions informatives pour les catégories courantes

4.3.2.1. pxSingleCatTitle

Cette fonction affiche le titre de la catégorie en cours.

pxSingleCatTitle( $s )

• $s : '%s' est la chaîne de substitution.

4.3.2.2. pxSingleCatDescription

Cette fonction affiche la description de la catégorie en cours.

pxSingleCatDescription( )

4.3.2.3. pxSingleCatPath

pxSingleCatPath( $s, $feed )

• $s : '%s' est la chaîne de substitution.
• $feed est un booléen dont la valeur par défaut est false. Mis à true, le chemin renvoyé sera alors celui du flux RSS de la catégorie courante.

Par exemple, ce code placé dans le gabarit category_category.php

<a href="<?php pxSingleCatPath('%s', true); ?>">Flux RSS de la catégorie.</a>
<a href="<?php pxSingleCatPath('%s'); ?>">Chemin relatif de la catégorie.</a>

retournera le code (X)HTML suivant lors de l'affichage du contenu d'une catégorie :

<a href="/plume/?/feed/categorie-A/">Flux RSS de la catégorie.</a>
<a href="/plume/?/categorie-A/">Chemin relatif de la catégorie.</a>

Nota : Cet exemple est basé sur une installation de Plume du type http://www.mon-site.tld/plume.

4.3.2.4. pxSingleCatNbResources

Cette fonction donne le nombre de ressources de la catégorie en cours lorsqu'une page de catégorie est affichée.

pxSingleCatNbResources( $no, $one, $more )

• $no est la chaîne lorsqu'il n'y a aucune ressources, par défaut 'no resources'.
• $one est la chaîne dans le cas où il y a une seule ressource, par défaut '1 resource'.
• $more est la chaîne de substitution dans le cas où il y deux ressources ou plus, par défaut '%s resources'.

4.3.2.5. pxSingleCatGetNbResources

Cette fonction retourne le nombre de ressources de la catégorie courante, alors que vous êtes sur une page de catégories. Si vous êtes sur une page de ressource, elle renvoie le nombre de ressources de sa catégorie courante. Cette fonction est notamment utile à l'intérieur d'une boucle php if.

pxSingleCatGetNbResources( )

4.3.2.6. pxSingleCatNextPage

Cette fonction génère les liens "suivant" et "précédent", seulement si ces pages existent.

pxSingleCatNextPage( $dir, $s )

• $dir donne la "direction" du lien :
  • -1 indique les pages précédentes ;
  • 1 indique les pages suivantes.
• $s : '%s' est la chaîne de substitution.

4.3.2.7. pxSingleCatListPages

Cette fonction affiche l'énumération des pages d'une catégories, comme un moteur de recherches. Par exemple : Page précédent 1, 2, 3, 4, 5 Page suivante.

pxSingleCatListPages ( $s, $prev, $next, $sep )

• $s : '<p>Pages: %s</p>' est la chaîne de substitution.
• $prev : la chaîne indiquant la page précédente, par défaut 'Prev'.
• $next : la chaîne indiquant la page suivante, par défaut 'Next'.
• $sep : le séparateur utilisé pour l'énumération des pages, par défaut ', '.

4.3.2.8. pxSingleCatTree

Cette fonction affiche la liste des catégories, faisant ainsi office de fil d'Ariane. Par exemple : Accueil >> catégorie >> sous-catégorie

pxSingleCatTree( $s )

• $s : '<ol>%s</ol>' est la chaîne de substitution.

4.3.3. Fonctions informatives pour les catégories parentes

4.3.3.1. pxParentCatTitle

Cette fonction affiche le nom de la catégorie parente, hormis pour la page d'accueil.

pxParentCatTitle( $s )

• $s : '%s' est la chaîne de substitution.

4.3.3.2. pxParentCatDescription

Cette fonction affiche la description de la catégorie parente, hormis pour la page d'accueil.

pxParentCatDescription( )

4.3.3.3. pxParentCatPath

Cette fonction affiche le chemin de la catégorie parente, hormis pour la page d'accueil.

pxParentCatPath( $s )

• $s : '%s' est la chaîne de substitution.

4.4. Fonctions de ressources

4.4.1. Fonctions de ressources pour les articles

Ces fonctions sont à utiliser dans les gabarits d'articles, tel que resource-article.php.

4.4.1.1. pxArtTitle

Cette fonction affiche le titre d'un article.

pxArtTitle( $s )

• $s : '%s' est la chaîne de substitution.

4.4.1.2. pxArtDescription

Cette fonction affiche la description d'un article.

pxArtDescription( )

4.4.1.3. pxArtAuthor

Cette fonctions affiche le nom de l'auteur.

pxArtAuthor( )

4.4.1.4. pxArtPath

Cette fonction affiche le chemin de la page de l'article.

pxArtPath( $type )

• $type :
  • 'full' donne le chemin absolu, avec http://.
  • 'relative', par défaut il est en relatif. Il est alors inutile de préciser le paramètre.

4.4.1.5. pxArtAuthorEmail

Cette fonction affiche l'adresse courriel publique si l'auteur l'a définie dans ses préférences. La possibilité d'encoder l'adresse permet de ne pas laisser celle-ci en clair dans le code source de la page.

pxArtAuthorEmail( $s, $encoding )

• $s : 'mailto:%s' est la chaîne de substitution.
• $encoding :
  • 'link' génère un lien "mailto" encodé en hexadécimal de la forme %6c pour le caractère "l". Valeur par défaut.
  • 'text' génère un lien "mailto" encodé en entités hexadécimales de la forme &#x6c pour le caractère "l".

4.4.1.6. pxArtDateCreation

Cette fonction affiche la date de création de l'article. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxArtDateCreation( $dateformat )

• $dateformat : '%A %e %B %Y' est le format de date défini par défaut, soit Wednesday December 2006.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.1.7. pxArtDatePublication

Cette fonction affiche la date de publication de l'article. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxArtDatePublication( $dateformat )

• $dateformat : '%A %e %B %Y' est le format de date défini par défaut, soit Wednesday December 2006.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.1.8. pxArtDateModification

Cette fonction affiche la date de modification de l'article si, et seulement si, elle est plus récente que la date de publication. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxArtDateModification( $dateformat, $s )

• $dateformat : '%A %e %B %Y - %T' est le format de date défini par défaut, soit Wednesday December 2006 - 22:01:50.
• $s : 'Modified the %s' est la chaîne de substitution par défaut.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.1.9. pxArtDateEnd

Cette fonction affiche la date de fin de validité de l'article si, et seulement si, une date de fin a été précisée. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxArtDateEnd( $dateformat, $s )

• $dateformat : '%A %e %B %Y - %T' est le format de date défini par défaut, soit Wednesday December 2006 - 22:01:50.
• $s : 'End the %s' est la chaîne de substitution par défaut.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.1.10. pxArtKeywords

Cette fonction affiche les mots-clés ou le sujet de l'article.

pxArtKeywords( $s )

• $s : '%s' est la chaîne de substitution.

4.4.1.11. pxArtCategories

Cette fonction affiche une liste de liens vers les catégories dans lesquelles l'article est disponible. La liste générée n'est pas une liste HTML mais est construite comme une phrase, ponctuée par les délimiteurs $p1 et $p2.

pxArtCategories( $s, $p1, $p2 )

• $s : '%s' est la chaîne de substitution.
• $p1 : ', ' est le premier délimiteur et est affiché par défaut.
• $p2 : ' and ' est le dernier délimiteur et est affiché par défaut.

4.4.1.12. pxArtPageIsFirst

Cette fonction renvoie la valeur true si la page en cours est la première d'un article, sinon false. Elle est essentielle pour la présentation structurée de l'article.

pxArtPageIsFirst( )

Vous pourrez l'utiliser dans un bloc d'instructions conditionnelles de la façon suivante :

<?php if (pxArtPageIsFirst()): ?>
    //SI nous sommes dans la première page de l'article
    //afficher le contenu de telle manière
<?php else: ?>
    //SINON c'est que nous ne sommes pas dans la première 
    //page de l'article, afficher le contenu d'une autre manière
<?php endif; ?>
    //FIN du bloc d'instructions conditionnelles

4.4.1.13. pxArtPageTitle

Cette fonction affiche le titre du chapitre courant.

pxArtPageTitle( $s )

• $s : '%s' est la chaîne de substitution.

4.4.1.14. pxArtPageContent

Cette fonction affiche le contenu du chapitre courant.

pxArtPageContent( )

4.4.1.15. pxArtListPages

Cette fonction affiche une liste HTML ordonnée de liens pointant vers les autres pages, ou chapitres, de l'article. La page en cours est distinguable grâce à la classe CSS current attribuée à l'élément <li> correspondant.

pxArtListPages( $s )

• $s : '%s' est la chaîne de substitution.

Un exemple de code généré :

<ol>
   <li><a href="/cat/my-article">Page 1</a></li>
   <li class="current"><a href="/cat/my-article2">Page 2</a></li>
   <li><a href="/cat/my-article3">Page 3</a></li>
</ol>

4.4.1.16. pxArtCountComments

Cette fonction affiche le nombre de commentaires affichés dans l'article.

pxArtCountComments( $s )

• $s : '%s' est la chaîne de substitution.

4.4.1.17. pxArtNextPage

Cette fonction génère les liens "suivant" et "précédent" pour des articles comportant plusieurs chapitres.

pxSingleCatNextPage( $dir, $s )

• $dir donne la "direction" du lien :
  • -1 indique les pages précédentes ;
  • 1 indique les pages suivantes.
• $s : '%s' est la chaîne de substitution.

4.4.2. Fonctions de ressources pour les brèves

Ces fonctions sont à utiliser dans les gabarits de brèves, tel que resource-news.php.

4.4.2.1. pxNewsTitle

Cette fonction affiche le titre de la brève.

pxNewsTitle( $s )

• $s : '%s' est la chaîne de substitution.

4.4.2.2. pxNewsContent

Cette fonction affiche le contenu d'une brève.

pxNewsContent( )

4.4.2.3. pxNewsKeywords

Cette fonction affiche les mots-clés ou le sujet d'une brève.

pxNewsKeywords( $s )

• $s : '%s' est la chaîne de substitution.

4.4.2.4. pxNewsDateCreation

Cette fonction affiche la date de création de la brève. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxNewsDateCreation( $dateformat )

• $dateformat : '%A %e %B %Y' est le format de date défini par défaut, soit Wednesday December 2006.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.2.5. pxNewsDatePublication

Cette fonction affiche la date de publication de la brève. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxNewsDatePublication( $dateformat )

• $dateformat : '%A %e %B %Y - %T' est le format de date défini par défaut, soit Wednesday December 2006 - 22:01:50.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.2.6. pxNewsDateModification

Cette fonction affiche la date de fin de modification de la brève si, et seulement si, elle est plus récente que la date de publication. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxNewsDateModification( $dateformat, $s )

• $dateformat : '%A %e %B %Y - %T' est le format de date défini par défaut, soit Wednesday December 2006 - 22:01:50.
• $s : 'Modified the %s' est la chaîne de substitution par défaut.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.2.7. pxNewsDateEnd

Cette fonction affiche la date de fin de validité de la brève si, et seulement si, une date de fin a été précisée. Les syntaxes de formatage des dates sont clairement expliquées sur strftime.

pxNewsDateEnd( $dateformat, $s )

• $dateformat : '%A %e %B %Y - %T' est le format de date défini par défaut, soit Wednesday December 2006 - 22:01:50.
• $s : 'Modified the %s' est la chaîne de substitution par défaut.

Voici quelques combinaisons possibles :

• '%Y-%m-%d - %H:%M' : 2006-11-14 - 23:42 ;
• 'le %d/%m/%Y à %Hh%M' : le 14/11/2006 à 23h42 ;
• '%x %I.%M%p %z' : 11/14/06 11.42PM Paris, Madrid.

4.4.2.8. pxNewsAuthor

Cette fonction affiche le nom de l'auteur.

pxNewsAuthor( )

4.4.2.9. pxNewsAuthorEmail

Cette fonction affiche l'adresse courriel publique si l'auteur l'a définie dans ses préférences. La possibilité d'encoder l'adresse permet de ne pas laisser celle-ci en clair dans le code source de la page.

pxNewsAuthorEmail( $s, $encoding )

• $s : 'mailto:%s' est la chaîne de substitution.
• $encoding :
  • 'link' génère un lien "mailto" encodé en hexadécimal de la forme %6c pour le caractère "l". Valeur par défaut.
  • 'text' génère un lien "mailto" encodé en entités hexadécimales de la forme &#x6c pour le caractère "l".

4.4.2.10. pxNewsPath

Cette fonction affiche le chemin de la page de la brève.

pxNewsPath( $type )

• $type :
  • 'full' donne le chemin absolu, avec http://.
  • 'relative', par défaut il est en relatif. Il est alors inutile de préciser le paramètre.

4.4.2.11. pxNewsCategories

Cette fonction affiche une liste de liens vers les catégories dans lesquelles la brève est disponible. La liste générée n'est pas une liste HTML mais est construite comme une phrase, ponctuée par les délimiteurs $p1 et $p2.

pxNewsCategories( $s, $p1, $p2 )

• $s : '%s' est la chaîne de substitution.
• $p1 : ', ' est le premier délimiteur et est affiché par défaut.
• $p2 : ' and ' est le dernier délimiteur et est affiché par défaut.

4.4.2.12. pxNewsCountComments

Cette fonction affiche le nombre de commentaires affichés dans la brève.

pxNewsCountComments( $s )

• $s : '%s' est la chaîne de substitution.

4.4.2.13. pxNewsAssociatedLink

Cette fonction affiche le lien associé à une brève s'il est disponible. Il faut que la brève ait été saisie avec cette information, le cas contraire, la fonction ne renvoie rien.

pxNewsAssociatedLink( $s, $return )

• $s : '<a href="%1$s">%2$s</a>' est la chaîne de substitution par défaut.

4.4.3. Fonctions de ressources pour les commentaires

Ces fonctions sont utilisables pour les gabarits de commentaires comments_inline.php, comments_list.php et comments_post.php qui sont eux-mêmes inclus dans les gabarits de ressources. Plus d'informations à ce sujet sont consultables à la section 4.1.1. de ce même chapitre.

4.4.3.1. pxCtEnabled

Cette fonction retourne la valeur true si les commentaires sont autorisés pour la ressource courante. Elle est essentielle pour tester le statut des commentaires et agir en fonction.

pxCtEnabled( )

Vous pourrez l'utiliser dans un bloc d'instructions conditionnelles de la façon suivante :

<?php if (pxCtEnabled()): ?>
   //SI les commentaires sont actifs, 
   //afficher le formulaire
<?php else: ?>
   //SINON, c'est que les commentaires sont inactifs,
   //afficher un message indiquant le statut clos des commentaires
<?php endif; ?>
   //FIN du bloc d'instructions conditionnelles

4.4.3.2. pxCtAuthor

Cette fonction affiche l'auteur du commentaire en cours.

pxCtAuthor( $s )

• $s : '%s' est la chaîne de substitution.

4.4.3.3. pxCtEmail

Cette fonction retourne l'adresse courriel de l'auteur du commentaire en cours.

pxCtEmail( $s, $encoding )

• $s : 'mailto:%s' est la chaîne de substitution.
• $encoding :
  • 'link' génère un lien "mailto" encodé en hexadécimal de la forme %6c pour le caractère "l". Valeur par défaut.
  • 'text' génère un lien "mailto" encodé en entités hexadécimales de la forme &#x6c pour le caractère "l".

4.4.3.4. pxCtWeb

Cette fonction affiche le site Web de l'auteur du commentaire en cours.

pxCtWeb( $s )

• $s : '%s' est la chaîne de substitution.

4.4.3.5. pxCtContent

Cette fonction affiche le contenu du commentaire en cours.

pxCtContent( $s, $format )

• $s : '<span class="px-comment">%s</span>' est la chaîne de substitution.
• $format désigne le format à appliquer au contenu :
  • 'safe' est le paramètre par défaut ;
  • 'textarea'.

4.4.3.6. pxCtErrors

Cette fonction affiche les erreurs potentielles d'un commentaire.

pxCtErrors( $s )

• $s : '%s' est la chaîne de substitution.

4.4.3.7. pxCtAction

Cette fonction retourne le contenu de l'attribut action pour la balise HTML <form>.

pxCtAction( )

4.4.3.8. pxCtRedirect

Cette fonction retourne l'adresse de redirection pour l'attribut value de la balise HTML <input type="hidden" />.

pxCtRedirect( ) 

4.4.4. Fonctions de ressources pour les plans de site

Ces fonctions sont utilisables dans les gabarits de plans de site, tel que sitemap.php

4.4.4.1. pxSitemapShowCatContent

Cette fonction affiche le contenu d'une catégorie.

pxSitemapShowCatContent( $category, $limit, $type )

• $category : identifiant de la catégorie dont le contenu doit être affiché ;
• $limit : nombre entier indiquant le nombre de ressources à afficher (10 par défaut) ;
• $type :
  • '' ou 'all' : affiche tous les types de ressources (brèves et articles) ;
  • 'news' : affiche les brèves ;
  • 'articles' : affiche les articles.

Contribution : Nicolas Lassalle

4.4.4.2. pxSitemapCategoriesList

Cette fonction retourne les sous-catégories de la catégorie désignée.

pxSitemapCategoriesList( $category )

• $category : la catégorie désignée.

Contribution : Nicolas Lassalle

4.4.4.3. pxSitemapGetCatTitle

Cette fonction retourne le titre d'une catégorie sans balises HTML (pas de <hx> ou de <li>)

pxSitemapGetCatTitle( $name, $vals )

• $name :
• $vals :

Contribution : Nicolas Lassalle

4.4.4.4. pxSitemapShowCategory

Cette fonction affiche le plan d'une catégorie donnée.

pxSitemapShowCategory( $category, $limit, $type )

• $category : la catégorie dont le contenu doit être affiché ;
• $limit : nombre entier indiquant le nombre de ressources à afficher (10 par défaut) ;
• $type :
  • '' ou 'all' : affiche tous les types de ressources (brèves et articles) ;
  • 'news' : affiche les brèves ;
  • 'articles' : affiche les articles.

Contribution : Nicolas Lassalle

4.4.4.5. pxSitemapShowPrimaryCategory

Cette fonction retourne le plan d'une catégorie principale.

pxSitemapShowPrimaryCategory( $category, $type, $limit )

• $category : la catégorie dont le contenu doit être affiché ;
• $limit : nombre entier indiquant le nombre de ressources à afficher (10 par défaut) ;
• $type :
  • '' ou 'all' : affiche tous les types de ressources (brèves et articles) ;
  • 'news' : affiche les brèves ;
  • 'articles' : affiche les articles.

Contribution : Nicolas Lassalle

4.4.4.6. pxShowSitemap

Cette fonction affiche le plan de site général du site.

pxShowSitemap( $limit, $type )

• $limit est le nombre maximum de ressources à afficher, dans l'ordre décroissant de publication. Par défaut, il sera affichée 10 ressources.
• $type désigne le type de ressources à afficher :
  • '' ou 'all' pour toutes les ressources confondues ;
  • 'articles' pour les articles ;
  • 'news' pour les brèves.

Contribution : Nicolas Lassalle

4.5. Fonctions générales

Ces fonctions servent à initialiser la gestion du cache et du gabarit. Bien qu'elles soient à la base de l'affichage du contenu, elles ne produisent aucunes sorties directes. Pour cela elles doivent être combinées avec les fonctions de ressources.

4.5.1. Fonctions générales pour le système de cache

Vous pouvez mettre en cache une partie ou la totalité d'une page et en gérer la durée. Dans les gabarits fournis par défaut toutes les pages sont entièrement mises en cache.

4.5.1.1. Cache complet de la page

Débutez votre gabarit par :

<?php
   if ($cache->processPage(3600)):
?>

et terminez-le par :

<?php
   $cache->endCache();
   endif;
?>

La valeur 3600 indique le durée totale de la mise en cache en secondes.

4.5.1.2. Cache partiel de la page

Débutez la section à mettre en cache par :

<?php
   if ($cache->processSegment(3600)):
?>

Et terminez-la par :

<?php
   $cache->endCache();
   endif;
?>

Si vous avez plusieurs sections avec des temps de mise en cache différents pour certaines, vous devez remplacer la valeur 3600, représentant la durée en secondes, pour chacune des sections concernées.

4.5.2. Fonctions générales pour l'initialisation des gabarits

L'initialisation du gabarit permet d'agir sur la gestion des ressources à afficher : classement, nombre et langue. Elle se fait par l'appel d'une fonction particulière.

4.5.2.1. pxTemplateInit

Cette fonction n'a aucun paramètre défini par défaut. Cependant, plusieurs peuvent être fournis en même temps et ainsi constituer ce qui s'apparentera à une chaîne longue. Dans ce cas, vous devrez alors les séparer par le caractère | (pipe de son appelation anglaise). Notez qu'il est essentiel d'appeler cette fonction après chaque utilisation des fonctions relatives au système de cache.

pxTemplateInit( $params )

• order_res_manual : Pour classer manuellement les ressources par leur titre dans les pages de catégories.
• order_cat_manual : Pour classer manuellement les catégories par leur nom dans les listes de catégories.
• remove_numbers : Pour enlever les nombres du début d'un titre de ressource ou de catégorie. Si vous placez par exemple 01., 10. ou 17. au début du nom d'une catégorie ou d'une ressource, ce nombre servira à son classement manuel mais ne sera pas affiché.
• res_per_page:XX : Nombre de ressources par pages. Changez XX par le nombre de ressources désirées.
• set_lang:XX : Définit la localisation du gabarit en cours. Changez XX par les deux lettres du code ISO de la langue. Si une partie de votre site est en français alors que le reste est en anglais, vous pouvez créer de nouveaux gabarits pour les catégories, articles et brèves et les utiliser en passant l'argument set_lang:fr. C'est fort utile pour gérer le nom des jours/mois dans le bon langage. Les curieux pourront regarder la fonction PHP setlocale, l'argument LC_ALL est utilisé.

Dans la pratique, cette fonction pourrait être utilisée de telle sorte :

pxTemplateInit('remove_numbers|order_cat_manual|set_lang:fr');

Notez que l'ordre des paramètres n'a aucune pertinence.

4.5.3. Fonctions relatives au gestionnaire de liens

Le gestionnaire de liens vous permet, comme décrit dans le chapitre précédent, d'organiser une rubrique de liens via le Manager. Le rendu sur le site de ces liens est, quant à lui, pris en charge par les fonctions pxLink::linkList et pxLink::linkListByCategory.

4.5.3.1. pxLink::linkList

Cette fonction affiche la globalité des catégories de liens et liens saisis via le gestionnaire de liens.

<?php pxLink::linkList( $category, $block, $item ); ?>

• $category représente le titre d'une catégorie de lien. Par défaut, la valeur est '<h3>%s</h3>'.
• $block représente le bloc qui contiendra les différents liens. Par défaut, la valeur est '<ul>%s</ul>'.
• $item représente une occurrence de liens. Par défaut, la valeur est '<li>%s</li>'.

Le rendu HTML par défaut de la fonction sera de la forme suivante (commentaires exclus), en considérant qu'une seule catégorie de liens n'existe :

<!-- Une catégorie de liens : -->
<h3>Ma catégorie</h3>
<!-- Les liens dans une liste non-ordonnée <ul> : -->
<ul>
  <li><a href="http://www.plume-cms.net/" hreflang="en" title="Site
       officiel de Plume CMS">Plume CMS</a>
  </li>
  <li><a href="http://www.fsf.org/" hreflang="en" title="Site de la
       Free Software Foundation">FSF</a>
  </li>
</ul>
<!-- À chaque nouvelle catégorie, un nouveau titre et
une nouvelle liste. -->

4.5.3.2. pxLink::linkListByCategory

Cette fonction permet l'affichage d'une catégorie précise de liens.

<?php pxLink::linkListByCategory( $category_name, $category, $block, $item ); ?>

• $category_name représente le nom exact de la catégorie voulue.
• $category représente le titre d'une catégorie de lien. Par défaut, la valeur est '<h3>%s</h3>'.
• $block représente le bloc qui contiendra les différents liens. Par défaut, la valeur est '<ul>%s</ul>'.
• $item représente une occurrence de liens. Par défaut, la valeur est '<li>%s</li>'.

Le rendu HTML par défaut est identique à celui de la fonction pxLink::linkList.