Le système de modèle de page de DotClear n'est pas ce qui se fait de plus simple à l'usage mais reste abordable pour peu de bien lire la documentation.
Le fonctionnement est très simple, il s'agit de fonctions PHP qui se chargent d'afficher l'information qu'on lui demande.
Parfois un motif est utilisé pour formater l'information affichée. Ce motif constitue une marque de substitution, généralement identifiée par %s. Pour de plus amples détails, suivrent la documentation de la fonction PHP, sprintf. Pour chaque fonction utilisant un motif, nous expliquerons comment le remplir.
Les fonctions suivantes permettent d'afficher des renseignements divers sur le blog ou les billets.
void dcInfo ([$name='name'])
Fonction affichant une information sur le blog. La propriété name peut prendre les valeurs suivantes :
Exemple :
<h1><?php dcInfo(); ?></h1>
<a href="<?php dcInfo('rss'); ?>">fil rss</a>
void dcDayDate ([$s='%s'])
Cette fonction affiche la date du jour. Elle est utilisée dans la boucle des billets et n'affiche la date que lors du premier billet du jour. Cela permet d'afficher la date du jour au dessus de plusieurs billets du même jour.
On peut entourer la date de marqueur ou de texte grâce à la chaîne de substitution s passée en argument. Par exemple:
<?php dcDayDate('<h2>%s</h2>'); ?>
void dcCalendar ()
Cette fonction affiche un calendrier contextuel (mois, année, jour). Le calendrier est un tableau dans une balise <div> dont la classe CSS est cal. Les nom des jours sont indiqués avec des cellules d'en-tête (th) et le titre avec (caption).
Exemple d'utilisation :
<?php dcCalendar(); ?>
void dcHeadLinks ()
Cette fonction affiche les liens (link) dans l'en-tête du fichier HTML. Elle génère automatiquement les liens de naviguation dans le blog. Il suffit de la placer dans l'en-tête du document :
<head> <?php dcHeadLinks(); ?> </head>
void dcSinglePostTitle ([$s='%s'])
Cette fonction affiche le titre d'un billet si on est sur une page présentant un billet (/blog/yyyy/mm/dd/titre par exemple).
On l'utilisera dans la balise <title> du document. Par exemple:
<title><?php dcSinglePostTitle(); ?></title>
void dcSingleCatTitle ($s)
Cette fonction affiche le nom de la catégorie s'il y a lieu de l'afficher. On peut l'utiliser dans le titre, comme dcSinglePostTitle.
void dcSingleMonthTitle ($s)
Cette fonction affiche le mois et l'année en cours s'il y a lieu de l'afficher. S'utilise aussi dans le titre comme dcSinglePostTitle.
Voici un exemple de commun de balise <title> à partir des fonctions précédentes :
<title><?php dcSinglePostTitle('%s - ').dcSingleCatTitle('%s - ').
dcSingleMonthTitle('%s - ').dcInfo(); ?></title>
void dcCatList ()
Cette fonction affiche une liste des catégories avec les liens pour y accéder. La liste générée est une liste non ordonnée (<ul>), il est donc très simple de la mettre en forme par la suite.
void dcMonthsList ()
Cette fonction affiche la liste des mois contenant les archives. Si on se trouve dans une catégorie, seuls les mois de cette catégorie seront affichés.
void dcSearchString ([$s='%s'])
Cette fonction affiche la chaîne de recherche lorsque qu'une recherche vient d'être effectuée.
Les fonctions suivantes doivent être utilisées uniquement dans un contexte de billet. Cela signifie qu'on l'utilisera si $mode vaut 'post' ou dans une boucle de billet. Exemple:
<?php if ($mode == 'post') : ?> on peut utiliser les fonctions. <?php endif; ?>
L'affichage des listes de billets est géré par une boucle très simple à mettre en place. Voici un exemple qui affiche le titre des billets :
<?php while (!$news->EOF()) : ?> <h3><?php dcPostTitle(); ?></h3> <?php $news->moveNext(); endwhile; ?>
void dcPostURL ()
Cette fonction affiche l'URI du billet, son permalien. On l'utilisera dans l'affichage d'un billet (boucle ou pas). Par exemple:
<a href="<?php dcPostURL(); ?>">lien permanent</a>
void dcPostID ()
Cette fonction affiche l'ID du billet (son numéro identifiant unique).
void dcPostTitle ()
Cette fonction affiche le titre d'un billet, avec chaîne de substitution possible. Exemple:
<h2><?php dcPostTitle(); ?></h2>
void dcPostCatTitle ()
Dans le contexte du billet, cette fonction affiche le nom de la catégorie du billet.
void dcPostCatURL ()
Cette fonction affiche l'URL de la catégorie d'un billet. Ne s'utilise que dans le contexte d'un billet. Par exemple:
<a href="<?php dcPostCarURL(); ?>"><?php dcPostCatTitle(); ?></a>
void dcPostContent ($part)
Cette fonction affiche le contenu d'un billet (sans son chapô). On peut limiter le nombre de mots affichés avec le paramère part. Si part vaut 0 alors on affiche tout le billet.
void dcPostChapo ([$s='%s <hr />'])
Cette fonction affiche le chapô d'un billet s'il existe, sinon elle n'affiche rien. Le paramètre s permet d'ajouter des information lors de l'affichage du chapô. Exemple:
<?php dcPostChapo('<h3>Chapô</h3> %s'); ?>
void dcPostAbstract ([$s='%s'],[$l='<p><a href="%s">lire la suite</a></p>'])
Cette fonction affiche le chapô du billet s'il y en a un sinon elle affiche le contenu du billet. Si elle affiche le chapô, le paramètre l permet de définir un texte à afficher après le chapô. Dans le paramètre l la chaîne %s indique le lien vers le billet. On pourra donc par exemple faire ceci :
<?php dcPostAbstract('%s','<p><a href="%s">lire la suite</a></p>'); ?>
On notera que cette fonction trouve sa place dans un affichage de liste de billets, plutôt que dans l'affichage d'un seul billet.
void dcPostAuthor ()
Cette fonction affiche le nom canonique de l'auteur du billet. Le nom canonique est défini en fonction des informations données par le rédacteur. Si un pseudo est présent, il sera utilisé, sinon, le prénom et le nom seront utilisés.
void dcPostDate ([$format=''])
Cette fonction affiche la date d'un billet. On peut changer le formatage de la date en changeant le paramètre format. Par défaut, ce paramètre utilisera le format donné dans la configuration du blog.
Voir strftime pour les formats possible de date.
void dcPostTime ()
Cette fonction affiche l'heure d'un billet en utilisant le format donné dans la configuration du blog.
void dcPostNbComments ($zero,$one,$more)
Cette fonction affiche le nombre de commentaires d'un billet. Les trois arguments permettent de définir le texte affiché pour respectivement aucun, un ou plusieurs commentaires. Par exemple:
<?php dcPostNbComments('aucun commentaire','un commentaire',
'%s commentaires'); ?>
void dcPostNext ([$dir=1],[$s='%1$s %2$s %3$s'])
Cette fonction permet d'afficher une information sur le billet suivant ou précédent. Le paramètre dir indique la direction dans laquelle chercher le billet (1 pour suivant, -1 pour précédent). Le paramètre s est une chaîne de substitution permettant de formater l'affichage des informations concernant le billet. Il y a trois paramètres à cette chaîne, donnant respectivement l'ID, le titre et l'url du billet suivant ou précédent. Cette fonction n'affiche rien si elle ne trouve pas de billet.
On peut l'utiliser pour l'affichage individuel des billets, par exemple:
<?php dcPostNext(1,'<a href="%3$s" title="%2$s">Billet suivant</a>'); ?>
Ceci affichera un lien vers le billet suivant s'il existe et ayant pour titre le titre du billet.
boolean dcPostOpenComments ()
Cette fonction indique si les commentaires sont autorisés pour un commentaire. On peut l'utiliser dans un test par exemple.
void dcPostTrackbackURI ()
Cette fonction affiche l'URI à pinger pour faire un trackback sur un billet.
void dcPostTrackbackAutoDiscovery ()
Cette fonction affiche le commentaire HTML contenant les informations RDF permettant de réaliser la découverte automatique de l'URL de trackback. On l'utilisera dans l'en-tête du document de préférence.
Le traitement des commentaires est régis par la même système de boucle que les billets. Les fonctions suivantes ne s'utilisent que dans une boucle de commentaires sauf dcCommentFormError et dcCommentFormValue qui peuvent être utilisés partout.
Exemple d'une boucle de commentaires affichant son contenu
<?php while (!$comments->EOF()) : ?> <?php dcCommentContent(); ?> <?php $comments->moveNext(); endwhile; ?>
void dcCommentContent ()
Cette fonction affiche le contenu d'un commentaire.
void dcCommentContentTransform ()
Cette fonction affiche un commentaire de type trackback avec le lien vers l'article dans le corps du commentaire (autour du titre). Sinon, il affiche que le commentaire comme dcCommentContent().
void dcCommentDate ([$format=''])
Cette fonction affiche la date d'un commentaire. On peut changer le formatage de la date en changeant le paramètre format. Par défaut, ce paramètre utilisera le format donné dans la configuration du blog.
Voir strftime pour les formats possibles de date.
void dcCommentTime ()
Cette fonction affiche l'heure d'un commentaire en utilisant le format donné dans la configuration du blog.
void dcCommentAuthor ()
Cette fonction affiche le pseudo de l'auteur d'un commentaire.
void dcCommentID ()
Cette fonction affiche l'ID d'un commentaire
void dcCommentAuthorLink ($s)
Cette fonction affiche le nom de l'auteur avec un lien vers son adresse email s'il en a laissé une.
void dcCommentAuthorSite ($s)
Cette fonction affiche un lien vers le site de l'auteur d'un commentaire s'il en a laissé un.
void dcCommentFormError ($s)
Cette fonction affiche les erreurs qui ont pu se produire lors de la soumission d'un commentaire. Il est conseillé de la laisser.
void dcCommentFormValue ($var)
Cette fonction affiche la valeur d'une variable pour le formulaire de commentaire. Elle permet par exemple de rappeler les valeurs en cas d'erreur. Les valeurs possibles de var sont :
On pourra utiliser par exemple:
<input name="c_nom" id="c_nom" type="text" size="30" maxlength="255"
value="<?php dcCommentFormValue('c_nom'); ?>" />
void dcCommentFormRedir ()
Cette fonction donne l'url vers laquelle on redirige le client une fois le commentaire posté.
boolean dcCommentIsTrackBack ()
Cette fonction indique si un commentaire est un trackback.
void dcCommentTrackBackURL ()
Cette fonction retourne l'URL du trackback. Il s'agit en fait de l'URL du site dans le commentaire. Elle fait simplement un test supplémentaire pour vérifier que le commentaire est bien un trackback.