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 leur 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, suivre la documentation de la fonction PHP, sprintf. Pour chaque fonction utilisant un motif, nous expliquerons comment le remplir.

Pour savoir quel fichier afficher dans la partie #main, DotClear définit des modes. En fonction du mode, le moteur du blog va varier son comportement.

Les modes sont testés dans le template à l’aide de la variable $mode

<?php if ($mode == 'machin') : ?>
afficher ce que l’on veut voir dans le mode machin 
<?php endif; ?>

• Fichier inclus¹⁾ : post.php
• Accès : url directe (url-de-monblog/année/mois/jour/numéro-[titrefacultatif]), lien sur le titre du billet ou la zone « post-info-co » depuis un affichage en liste, ou, s’il y figure, depuis la liste des billets « À retenir » dans le sidebar.

C’est le mode dans lequel le billet s’affiche tout seul, en entier, avec ses commentaires et trackbacks, son formulaire pour ajouter un commentaire.

• Fichier inclus : list.php
• Accès : url directe (url-de-mon-blog/Categorie ou url-de-mon-blog?Categorie selon que le format est Path Info ou Query String), lien dans les infos situées sous le titre du billet, lien direct depuis le sidebar.

Affiche la liste des billets en effectuant un tri sur la catégorie. Le nombre de billets par page est limité par le paramètre indiqué dans Outils –> Configuration de DotClear.

• Fichier inclus : list.php
• Accès : url directe (url-de-mon-blog/?q=\[mot-cherché]) ou via le formulaire de recherche dans le sidebar.

Le moteur opère un tri sur les critères indiqués dans le champ de recherche et les affiche en liste selon la forme définie dans le fichier list.php. A savoir : dans ce mode, le nombre de billets par page n'est pas limité par l’indication que vous aurez donnée dans Outils –> Configuration de DotClear.

• Fichier inclus : list.php
• Accès :
  • url directe (url-de-mon-blog/année/mois/), ou via la liste des mois du sidebar pour month,
  • url directe (url-de-mon-blog/année/mois/jour), ou clic sur la date dans le calendrier du sidebar pour day.

Month pour les billets d’un mois donné, day pour une date précise, comme pour le mode search, le tri s’effectue sur le mois (ou le jour pour le mode day) choisi sans limitation du nombre d’entrées. C’est en cela que ce mode est celui qui est tout indiqué pour visiter les archives.

• Fichier inclus : list.php

C’est le mode qui correspond à l’accueil du blog.

En observant le fichier template.php du thème par défaut, on remarque que juste après l’ouverture du bloc central du blog (<div id="main">) des codes indiquent ce que doit afficher le moteur en fonction de telle ou telle circonstance. Cette suite de if et elseif, après avoir traité le cas d’une erreur quelconque ou du postage de commentaire par un visiteur détermine deux cas : le mode n'est pas post ou il l’est. Dans le premier cas, on affiche une liste de billets (list.php), sinon le billet seul (fichier post.php). C’est la raison pour laquelle (si ces instructions ne sont pas modifiées) toutes les listes de billets sont organisées de la même façon.

On peut très bien intervenir à cet instant, après la condition du message d’erreur,²⁾ pour appeler un fichier précis en telle ou telle circonstance. C’est par exemple ce qu’on fait lorsqu’on installe une page spécifique en interceptant le mode home (voir le tuto qui va bien).

Sur le même principe, on pourrait imaginer une condition supplémentaire (elseif) qui déterminerait un autre fichier appelé pour le mode month (appelons-le month.php histoire de ne pas se compliquer la vie) et qui serait constitué de façon à n’afficher, par exemple, que les titres des billets du mois.

Il existe un certain nombre de plugins qui créent un mode spécialement pour eux. Exemples répandus : Gallery, qui permet d’afficher des images sous forme d’album, Table des matières, pour constituer un sommaire des billets, Related, qui offre la possibilité d’adjoindre des pages connexes au blog.

Pour afficher leur(s) pages, eux aussi vont s’intercaler après la condition du message d’erreur et signaler au moteur que le fichier à afficher est celui-ci ou celui-là.

Les fonctions suivantes permettent d'afficher des renseignements divers sur le blog ou les billets.

void dcInfo([$name='name'])

• name - Nom de la propriété à afficher

Fonction affichant une information sur le blog. La propriété name peut prendre les valeurs suivantes :

• name : non du weblogue
• theme : chemin vers le répertoire du thème
• img : chemin vers les images
• url : URL de la home page du blog
• rss : chemin vers le fil RSS
• atom : chemin vers le fil Atom
• search : chemin de l'action pour le moteur de rechercher
• logo : chemin vers l'image du logo
• encoding : Encodage des caractères
• lang : langue principale du weblogue

<h1><?php dcInfo(); ?></h1>
 
<a href="<?php dcInfo('rss'); ?>">fil rss</a>

<a href="<?php dcInfo('rss'); ?>?cat=General">RSS général</a>

<void dcDayDate([$s='%s'])

• s - Chaine de substition

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 balise ou de texte grâce à la chaîne de substitution s passée en argument. Par exemple:

<?php dcDayDate('<h2>%s</h2>'); ?>

void dcCalendar([$block='<div class="cal"><table summary="calendrier">%s</table></div>'])

• block - Chaine de substitution pour pour le tableau

Cette fonction affiche un calendrier contextuel (mois, année, jour). Le calendrier est un tableau dans une balise <div> dont la classe CSS|Cascading Style Sheet est cal. Les nom des jours sont indiqués avec des cellules d'en-tête (th) et le titre avec (caption).

<?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 navigation dans le blog. Il suffit de la placer dans l'en-tête du document :

<head>
<?php dcHeadLinks(); ?>
</head>

void dcSinglePostTitle([$s='%s - '])

• s - Chaîne de substitution

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='%s - '])

• s - Chaîne de substitution

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='%s - '])

• s - Chaîne de substitution

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.

void dcCustomTitle([$s='%s - '])

• s - Chaîne de substitution

Cette fonction affiche le contenu de la variable globale $dc_custom_title. Cette variable peut-être assignée par un plugin. Exemples d'usage des fonctions pour la balise <title> ¶

Voici un exemple de commun de balise <title> à partir des fonctions précédentes :

<title><?php dcSinglePostTitle('%s - '); dcSingleCatTitle('%s - ');
dcSingleMonthTitle('%s - '); dcCustomTitle('%s - '); dcInfo(); ?></title>

void dcLangList([$block='<ul>%s</ul>'], [$item='<li>%s</li>'])

• block - Chaine de substitution pour pour la liste
• item - Chaine de substitution pour un élément

Cette fonction affiche une liste des langues définies dans les billets. Les langues s'affichent uniquement si au moins deux langues différentes existent. Ceci permet d'offrir une navigation par langue dans le weblogue.

void dcCatList([$block='<ul>%s</ul>'], [$item='<li>%s</li>'])

• block - Chaine de substitution pour pour la liste
• item - Chaine de substitution pour un élément

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([$block='<ul>%s</ul>'], [$item='<li>%s</li>'])

• block - Chaine de substitution pour pour la liste
• item - Chaine de substitution pour un élément

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 dcSelection([$block='<ul>%s</ul>'], [$item='<li><a href="%2$s">%1$s</a></li>'], [$limit=ilimité])

• block - Chaine de substitution pour pour la liste
• item - Chaine de substitution pour un élément
• limit - Nombre de titres à afficher

Cette fonction affiche une liste des billets sélectionnés, avec simplement le titre et un lien vers le billet. L'affichage par défaut produira une liste, vous pouvez l'appeler tout simplement par dcSelection().

void dcSearchString([$s='%s'])

• s - Chaîne de substitution

Cette fonction affiche la chaîne de recherche lorsque qu'une recherche vient d'être effectuée.

void dcAdminLink([$s='<ul><li><a href="%s">admin</a></li></ul>'])

Parametres

• s - Chaine de substitution

Cette fonction affiche un lien vers l'espace d'administration du blog dans le cas ou une session d'administration est ouverte (et seulement dans ce cas).

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->fetch()) : ?>
<h3><?php dcPostTitle(); ?></h3>
<?php 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)

• part - Nombre de mots à afficher

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 />'])

• s - Chaine de substitution

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" title="%s">Read next</a></p>'])

• s - Chaîne de substitution du chapô
• l - Chaîne affichée après le chapô

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 première chaîne %s indique le lien vers le billet et la seconde le titre du billet. On pourra donc par exemple faire ceci :

<?php dcPostAbstract('%s','<p><a href="%s" title="Lire %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=''])

• format - Masque de formatage de la date

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 dcPostLang()

Cette fonction affiche l'attribut lang="" pour un billet. Vous pouvez le positionner dans n'importe quelle balise. Rien n'est affiché si la langue n'est pas présente.

void dcPostNbComments($zero, $one, $more)

• zero - Texte affiché pour 0 commentaire
• one - Texte affiché pour 1 commentaire
• more - Texte affiché plusieurs commentaires

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 dcPostNbTrackbacks($zero, $one, $more)

• zero - Texte affiché pour 0 trackback
• one - Texte affiché pour 1 trackback
• more - Texte affiché plusieurs trackbacks

Cette fonction affiche le nombre de trackbacks d'un billet. Les trois arguments permettent de définir le texte affiché pour respectivement aucun, un ou plusieurs trackbacks. Par exemple:

<?php dcPostNbTrackbacks('aucun trackback','un trackback',
'%s trackbacks'); ?>

void dcPostNext([$dir=1], [$s='%1$s %2$s %3$s'])

• dir - Direction
• s - Chaîne de substitution

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 billet. On peut l'utiliser dans un test par exemple.

boolean dcPostOpenTrackbacks()

Cette fonction indique si les trackbacks sont autorisés pour un billet. 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->fetch()) : ?>
<?php dcCommentContent(); ?>
<?php 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=''])

• format - Masque de formatage de la date

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($s)

• s - Chaîne de substitution, uniquement si l'auteur a laissé une URL

Cette fonction affiche le pseudo de l'auteur d'un commentaire. Avec un lien si l'auteur a laissé une URL dcCommentID

void dcCommentID()

Cette fonction affiche l'ID d'un commentaire

void dcCommentAuthorLink($s)

• s - Chaîne de substitution

Cette fonction affiche le nom de l'auteur avec un lien vers son adresse email s'il en a laissé une.

void dcCommentAuthorSite($s)

• s - Chaîne de substitution

Cette fonction affiche un lien vers le site de l'auteur d'un commentaire s'il en a laissé un.

void dcCommentPreview()

Cette fonction affiche la prévisualisation d'un commentaire. Elle affiche les émoticones et le formatage tel qu'il sera affiché.

void dcCommentFormError($s)

• s - Chaîne de substitution

Cette fonction affiche les erreurs qui ont pu se produire lors de la soumission d'un commentaire. Il est conseillé de la laisser.

void dcCommentFormMsg($s)

• s - Chaîne de substitution

Cette fonction affiche un message après la soumission d'un commentaire. Le seul message actuellement est la confirmation de la réception du commentaire quand ceux-ci sont modérés. Si vous ne modérez pas les commentaires, cette fonction peut ne pas être utilisée.

void dcCommentFormValue($var)

• var - Nom de la variable à afficher

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 :

• c_nom : nom
• c_mail : adresse email
• c_site : site web
• c_content : contenu du commentaire

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.

Le traitement des trackbacks suit le même fonctionnement que les commentaires. Les fonctions suivantes ne s'utilisent que dans une boucle de trackbacks.

Exemple d'une boucle de trackbacks affichant son contenu

<?php while ($trackbacks->fetch()) : ?>
<?php dcTBContent(); ?>
<?php endwhile; ?>

void dcTBContent()

Cette fonction affiche un trackback avec le lien vers l'article dans le corps du commentaire (autour du titre).

void dcTBDate([$format=''])

• format - Masque de formatage de la date

Cette fonction affiche la date d'un trackback. 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 dcTBTime()

Cette fonction affiche l'heure d'un trackback en utilisant le format donné dans la configuration du blog.

void dcTBAuthor()

Cette fonction affiche le nom de l'auteur d'un trackback.

void dcTBID()

Cette fonction affiche l'ID d'un trackback