====== Fonctionnement des gabarits ======



===== Introduction =====

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.

===== Les modes =====

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''
<code php><?php if ($mode == 'machin') : ?>
afficher ce que l’on veut voir dans le mode machin 
<?php endif; ?></code>

==== $mode == 'post' ====
  *Fichier inclus((la mention du « fichier inclus » concerne bien sûr le thème par défaut)) : ''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.

==== $mode == 'cat' ====
  *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.

==== $mode == 'search' ====
  *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.

==== $mode == 'month' – $mode == 'day' ====
  *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.

==== $mode == 'home' ====
  *Fichier inclus : ''list.php''

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

===== Un centre d’aiguillage =====
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.

==== Ajouter un aiguillage ====
On peut très bien intervenir à cet instant, **après la condition du message d’erreur**,((Ce point est très important. Il faut en effet que le message en cas d’erreur ait la priorité absolue sur l’affichage à opérer dans la page.)) 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 [[http://petit.dotclear.net/pages/2004/12/02/27-creer-une-page-daccueil-differente|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.

==== Invités ====
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 informatives =====

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




==== dcInfo ====

<code php>void dcInfo([$name='name'])</code>

=== Parametres ===

    * 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

=== Exemple ===

<code php><h1><?php dcInfo(); ?></h1>

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

<note>vous pouvez faire un lien vers le fil RSS ou Atom d'une catégorie très facilement en ajoutant l'identifiant de la catégorie à l'URL, comme ceci par exemple :

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

==== dcDayDate ====

<code php><void dcDayDate([$s='%s'])</code>

=== Parametres ===

    * 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:

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


==== dcCalendar ====

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

=== Parametres ===

    * 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).

=== Exemple d'utilisation ===

<code php><?php dcCalendar(); ?></code>

==== dcHeadLinks ====

<code php>void dcHeadLinks()</code>

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 :

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

==== dcSinglePostTitle ====

<code php>void dcSinglePostTitle([$s='%s - '])</code>

=== Parametres ===

    * 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:

<code php><title><?php dcSinglePostTitle(); ?></title></code>

==== dcSingleCatTitle ====

<code php>void dcSingleCatTitle([$s='%s - '])</code>

=== Parametres ===

    * 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.

==== dcSingleMonthTitle ====

<code php>void dcSingleMonthTitle([$s='%s - '])</code>

=== Parametres ===

    * 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.

==== dcCustomTitle ====

<code php>void dcCustomTitle([$s='%s - '])</code>

=== Parametres ===

    * 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 :

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

==== dcLangList ====

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

=== Parametres ===

    * 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.

==== dcCatList ====

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

=== Parametres ===

    * 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.

==== dcMonthsList ====

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

=== Parametres ===

    * 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.

==== dcSelection ====

<code php>void dcSelection([$block='<ul>%s</ul>'], [$item='<li><a href="%2$s">%1$s</a></li>'], [$limit=ilimité])</code>

=== Parametres ===

    * 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().

==== dcSearchString ====

<code php>void dcSearchString([$s='%s'])</code>

=== Parametres ===

    * s - Chaîne de substitution

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

==== dcAdminLink ====

<code php>void dcAdminLink([$s='<ul><li><a href="%s">admin</a></li></ul>'])</code>
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).


===== Traitement des billets =====

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:

<code php><?php if ($mode == 'post') : ?>
on peut utiliser les fonctions.
<?php endif; ?></code>

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 :

<code php><?php while ($news->fetch()) : ?>
<h3><?php dcPostTitle(); ?></h3>
<?php endwhile; ?></code>

==== dcPostURL ====

<code php>void dcPostURL()</code>

Cette fonction affiche l'URI du billet, son permalien. On l'utilisera dans l'affichage d'un billet (boucle ou pas). Par exemple:

<code php><a href="<?php dcPostURL(); ?>">lien permanent</a></code>

==== dcPostID ====

<code php>void dcPostID()</code>

Cette fonction affiche l'ID du billet (son numéro identifiant unique).

==== dcPostTitle ====

<code php>void dcPostTitle()</code>

Cette fonction affiche le titre d'un billet, avec chaîne de substitution possible. Exemple:

<code php><h2><?php dcPostTitle(); ?></h2></code>

==== dcPostCatTitle ====

<code php>void dcPostCatTitle()</code>

Dans le contexte du billet, cette fonction affiche le nom de la catégorie du billet.

==== dcPostCatURL ====

<code php>void dcPostCatURL()</code>

Cette fonction affiche l'URL de la catégorie d'un billet. Ne s'utilise que dans le contexte d'un billet. Par exemple:

<code php><a href="<?php dcPostCarURL(); ?>"><?php dcPostCatTitle(); ?></a></code>

==== dcPostContent ====

<code php>void dcPostContent($part)</code>

=== Parametres ===

    * 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.


==== dcPostChapo ====

<code php>void dcPostChapo([$s='%s <hr />'])</code>

=== Parametres ===

    * 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:

<code php><?php dcPostChapo('<h3>Chapô</h3> %s'); ?></code>

==== dcPostAbstract ====

<code php>void dcPostAbstract([$s='%s'], [$l='<p><a href="%s" title="%s">Read next</a></p>'])</code>

=== Parametres ===

    * 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 :

<code php><?php dcPostAbstract('%s','<p><a href="%s" title="Lire %s">Lire la suite</a></p>'); ?></code>

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.

==== dcPostAuthor ====

<code php>void dcPostAuthor()</code>

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.

==== dcPostDate ====

<code php>void dcPostDate([$format=''])</code>

=== Parametres ===

    * 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.

==== dcPostTime ====

<code php>void dcPostTime()</code>

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

==== dcPostLang ====

<code php>void dcPostLang()</code>

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.

==== dcPostNbComments ====

<code php>void dcPostNbComments($zero, $one, $more)</code>

=== Parametres ===

    * 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:

<code php><?php dcPostNbComments('aucun commentaire','un commentaire',
'%s commentaires'); ?></code>

==== dcPostNbTrackbacks ====

<code php>void dcPostNbTrackbacks($zero, $one, $more)</code>

=== Parametres ===

    * 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:

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

==== dcPostNext ====

<code php>void dcPostNext([$dir=1], [$s='%1$s %2$s %3$s'])</code>

=== Parametres ===

    * 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:

<code php><?php dcPostNext(1,'<a href="%3$s" title="%2$s">Billet suivant</a>'); ?></code>

Ceci affichera un lien vers le billet suivant s'il existe et ayant pour titre le titre du billet.

==== dcPostOpenComments ====

<code php>boolean dcPostOpenComments()</code>

Cette fonction indique si les commentaires sont autorisés pour un billet. On peut l'utiliser dans un test par exemple.

==== dcPostOpenTrackbacks ====

<code php>boolean dcPostOpenTrackbacks()</code>

Cette fonction indique si les trackbacks sont autorisés pour un billet. On peut l'utiliser dans un test par exemple.

==== dcPostTrackbackURI ====

<code php>void dcPostTrackbackURI()</code>

Cette fonction affiche l'URI à pinger pour faire un trackback sur un billet.

==== dcPostTrackbackAutoDiscovery ====

<code php>void dcPostTrackbackAutoDiscovery()</code>

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.


===== Traitement des commentaires =====

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

<code php><?php while ($comments->fetch()) : ?>
<?php dcCommentContent(); ?>
<?php endwhile; ?></code>

==== dcCommentContent ====

<code php>void dcCommentContent()</code>

Cette fonction affiche le contenu d'un commentaire.

==== dcCommentContentTransform ====

<code php>void dcCommentContentTransform()</code>

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

==== dcCommentDate ====

<code php>void dcCommentDate([$format=''])</code>

=== Parametres ===

    * 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.

==== dcCommentTime ====

<code php>void dcCommentTime()</code>

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


==== dcCommentAuthor ====

<code php>void dcCommentAuthor($s)</code>

=== Parametres ===

    * 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

<code php>void dcCommentID()</code>

Cette fonction affiche l'ID d'un commentaire

==== dcCommentAuthorLink ====

<code php>void dcCommentAuthorLink($s)</code>

=== Parametres ===

    * 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.

==== dcCommentAuthorSite ====

<code php>void dcCommentAuthorSite($s)</code>

=== Parametres ===

    * 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.

==== dcCommentPreview ====

<code php>void dcCommentPreview()</code>

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

==== dcCommentFormError ====

<code php>void dcCommentFormError($s)</code>

=== Parametres ===

    * 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.

==== dcCommentFormMsg ====

<code php>void dcCommentFormMsg($s)</code>

=== Parametres ===

    * 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.

==== dcCommentFormValue ====

<code php>void dcCommentFormValue($var)</code>

=== Parametres ===

    * 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:

<code php><input name="c_nom" id="c_nom" type="text" size="30" maxlength="255"
value="<?php dcCommentFormValue('c_nom'); ?>" /></code>


==== dcCommentFormRedir ====

<code php>void dcCommentFormRedir()</code>

Cette fonction donne l'url vers laquelle on redirige le client une fois le commentaire posté.

==== dcCommentIsTrackBack ====

<code php>boolean dcCommentIsTrackBack()</code>

Cette fonction indique si un commentaire est un trackback.

==== dcCommentTrackBackURL ====

<code php>void dcCommentTrackBackURL()</code>

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.


===== Traitement des trackbacks =====

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

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

==== dcTBContent ====

<code php>void dcTBContent()</code>

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

==== dcTBDate ====

<code php>void dcTBDate([$format=''])</code>

=== Parametres ===

    * 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.

==== dcTBTime ====

<code php>void dcTBTime()</code>

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

==== dcTBAuthor ====

<code php>void dcTBAuthor()</code>

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

==== dcTBID ====

<code php>void dcTBID()</code>

Cette fonction affiche l'ID d'un trackback