Ceci est une ancienne révision du document !
Table des matières
Développement de thèmes DokuWiki
mise à jour en cours. Se reporter à la page d'origine pour avoir l'information la plus récente.
Vous pouvez personnaliser l'apparence de DokuWiki en créant un nouveau thème (template). Un thème est principalement déterminé par quelques fichiers PHP et CSS stockés dans un répertoire à l'intérieur de <dokuwiki>/lib/tpl/
.
Guide de démarrage
La façon la plus simple pour créer un nouveau thème est de se baser sur un thème déjà existant. Il est recommandé de prendre comme exemple le thème starter de DokuWiki car il est propre, simple et respecte les standards de conception d'un template DokuWiki.
- Installer le thème starter (la branche “minimale” est une option possible comme point de démarrage propre)
- Renommer le répertoire
lib/tpl/starter
enlib/tpl/monnouveautemplate
- Sélectionnez votre nouveau thème depuis le Gestionnaire de configuration
- Changer ensuite votre thème selon vos envies. Pour comprendre comment les thèmes de DokuWiki sont construits, jetez un œil aux fichiers qui composent le thème et la façon dont DokuWiki manipule ses feuilles de style.
Conventions de nommage des thèmes
Le nom (nom du répertoire) d'un thème valide :
- Ne doit contenir que les caractères a-z and 0-9.
- Les caractères point “.” ou trait souligné “_” ne sont pas autorisés car :
- l'infrastructure logicielle de DokuWiki ne les prend pas en charge partout
- utiliser le trait souligné “_” donnera la valeur zéro à la cote de popularité.
- Si le même nom est utilisé par deux thèmes différents
- ils s'excluent mutuellement et sont intrinsèquement incompatibles,
- en outre, seulement l'un deux peut avoir une page d'accueil sur dokuwiki.org.
Il est important d'avoir une valeur de champ de données unique (i.e. le nom du thème) dans le template.info.txt ou celle d'un thème déjà existant dont le nom puisse être écrasé.
Structure du répertoire d'un thème
Chaque template devrait suivre la structure suivante (tous les chemins sont relatifs au répertoire du template).
Les fichiers CSS sont spécifiés dans le fichier style.ini
. Vous pouvez avoir autant de fichiers que vous le souhaitez mais vous devriez avoir au moins un fichier CSS pour l'affichage standard (écran) et un autre dédié à l'impression.
<dokuwiki>/lib/tpl/<template>/
<nom de fichier>.css
– template's stylesheets (selon le nombre de fichiers fournis, il peut s'avérer utile de les grouper dans un répertoirecss/
)script.js
– optionnel, si votre thème nécessite JavaScriptmain.php
– le fichier principal qui sert à afficher les pagesdetail.php
– la page de détail d'une imagemediamanager.php
– le Gestionnaire de médiasimages/
– toutes les images utilisées pour le thème (s'il y en a)conf/
– fichiers de configuration (optionnel, si une configuration est utilisée)metadata.php
– configuration metadata décrit les propriétés des paramètres utilisés par le Gestionnaire de configuration
lang/
– fichiers de langue<code de langue>/lang.php
– chaînes de caractères utilisées dans le thème (optionnel, à utiliser quand nécessaire)<code de langue>/settings.php
– chaînes de caractères utilisées dans le Gestionnaire de configuration (si une configuration est utilisée)
style.ini
– voir Style.inifavicon.ico
– favicon (peut être écrasé en téléversant un autre à la racine ou dans l'espace de noms wiki quand tpl_favicon() est utilisé)template.info.txt
– Un fichier texte avec information du thème est requis !
la manipulation des paramètres de configuration est analogue aux plugins. Employez tpl_getConf(<paramètre>)
pour récupérer un paramètre personnalisé du template. Les paramètres locaux sont sauvegardés dans le fichier global conf/local.php
de DokuWiki.
Fonctions
Une liste des fonctions disponibles est accessible dans la documentation de l'API. Certaines sont listées ci-dessous.
tpl_content()
Cette fonction affiche le contenu d'une page du wiki, y compris la table des matières. Il est possible d'empêcher cela en passant le paramètrefalse
quand on appelle la fonction :tpl_content(false);
C'est utile si on souhaite séparer la table des matières du contenu de la page. On peut alors la placer n'importe où dans le template. Pour l'afficher, on utilisera la fonction
tpl_toc()
ci-dessous.
tpl_toc()
Par défaut, c'est la fonctiontpl_content()
qui s'occupe d'afficher la table des matières, en la plaçant juste avant le contenu d'une page. Mais si vous souhaitez afficher la table des matières à un autre endroit, par exemple dans une barre latérale, il vous faudra utiliser la fonctiontpl_toc()
. Quand on l'utilise, il ne faut pas oublier de passer le paramètrefalse
à la fonctiontpl_content()
.
Exemple:
<div id="content"> <?php tpl_content(false)?> </div> <div id="sidebar"> <?php tpl_toc()?> </div>
La fonction tpl_toc()
construit la table des matières depuis trois sources différentes :
- une variable d'environnement globale
- les métadonnées de la page
- la méthode
getTOC()
utilisée par les plugins d'administration
Comme il n'y a pas de métadonnées pour les anciennes révisions ou l'aperçu, la fonction tpl_toc()
ne peut utiliser que la variable d'environnement globale dans ces cas précis. Et comme la variable d'environnement globale est remplie par le moteur de rendu de la page, cela ne marche que quand la fonction tpl_toc()
est appelée après la fonction tpl_content()
. Si votre template ne permet pas cela, vous pouvez utiliser la mémoire tampon pour palier à ce problème.
Exemple:
<?php // render the content into buffer for later use ob_start(); tpl_content(false); $buffer = ob_get_clean(); ?> <div id="sidebar"> <?php tpl_toc()?> </div> <div id="content"> <?php echo $buffer?> </div>
tpl_getConf('key')
Cette fonction est utilisée pour accéder aux paramètres de configuration depuis le template.
tpl_getLang('key')
Cette fonction est utilisée pour accèder aux chaines de caractères locales du thème. Pour les détails, voir le chapitre localization de la documentation développement.
- Further many other useful template functions are available. Please have a look in API documentation.
Variables globales et constantes
Pour une liste complète des Variables globales et des constantes, consultez la page environment.
Indexation automatisée
Presque à la fin du fichier main.php
du template par défaut, vous verrez un appel à la fonction tpl_indexerWebBug()
. Elle génère une balise HTML <IMG>
qui fait une requête à lib/exe/indexer.php
. C'est une partie vitale de DokuWiki qui fournit une indexation automatique de la page pour l'outil de recherche et d'autres fonctions importantes comme la génération d'une carte du site en XML (utilisée par les moteurs de recherche internet) ou la mise à jour des méta-données. Tous les templates doivent inclure cette fonction, sans quoi le wiki pourrait ne pas fonctionner correctement (par exemple, la recherche ne fonctionnera pas).
Hooks
Les hooks (hameçons en français) permettent d'inclure du contenu statique dans votre DokuWiki sans avoir besoin de toucher au template. Vous pouvez par exemple les utiliser pour ajouter une bannière, le logo de votre entreprise ou un avertissement en bas de chaque page.
Le template par défaut de DokuWiki cherche des fichiers spécifiques dans le répertoire lib/tpl/default/
et se contente de les inclure au bon endroit quand on affiche une page. Vous pouvez y mettre n'importe quel code HTML ou PHP.
Hooks disponibles
Tous ces fichiers sont recherchés dans le répertoire lib/tpl/default/
.
Nom de fichier | Emplacement du fichier HTML inclu dans le template |
---|---|
meta.html | Dans la balise <head>, à utiliser pour inclure de nouveaux fichiers CSS ou des balises <meta> |
topheader.html | Au tout début de la page, juste après la balise <body> |
header.html | Au dessus de la barre bleue du haut, juste en dessous du nom de page et du nom du wiki |
pageheader.html | En dessous du fil d'ariane, juste au dessus du contenu d'une page |
pagefooter.html | Au dessus de la barre bleue du bas, juste en dessous de la date de dernière modification |
footer.html | À la fin de la page, juste avant la balise </body> |
DokuWiki est fourni avec un exemple de fichier footer.html
qui contient quelques boutons et la licence.
Publier un thème sur dokuwiki.org
Mise à jour de la page en cours
- — Digitalin 2016-05-13 10:52
phrases laissées de côté le temps de la mise à jour de la page
- (voir
tpl_getConf()
) - Voila un petit script pour déterminer dans quel partie du site vous êtes:
$url_blog= preg_replace('/\\?.*/', '', $_SERVER['REQUEST_URI']); if(substr($url_blog, 0, strlen('/blog/'))=='/blog/'){ $ma_page="blog"; } //Utilisez switch pour plusieurs catégories. [...] if($ma_page=="blog"){ echo '<aside>';//balise HTML 5 tpl_toc(); echo '</aside>'; }