Découvrir DokuWiki
Options avancées
Pour les entreprises
Notre Communautée
Suivez-nous sur Facebook, Twitter et les autres résaux sociaux.
Découvrir DokuWiki
Options avancées
Pour les entreprises
Notre Communautée
Suivez-nous sur Facebook, Twitter et les autres résaux sociaux.
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/
.
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 thème DokuWiki.
lib/tpl/starter
en lib/tpl/monnouveauthème
Le nom (nom du répertoire) d'un thème valide :
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é.
Chaque thème devrait suivre la structure suivante (tous les chemins sont relatifs au répertoire du thème).
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épertoire css/
) 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 configurationlang/
– 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 thème. Les paramètres locaux sont sauvegardés dans le fichier global conf/local.php
de DokuWiki.
Une liste des fonctions disponibles est accessible dans la documentation de l'API. Certaines sont listées ci-dessous.
tpl_content()
false
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 thème. Pour l'afficher, on utilisera la fonction tpl_toc()
ci-dessous.
tpl_toc()
tpl_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 fonction tpl_toc()
. Quand on l'utilise, il ne faut pas oublier de passer le paramètre false
à la fonction tpl_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 ou 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 thème 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')
tpl_getLang('key')
Pour une liste complète des variables globales et des constantes, consultez la page environnement.
Presque à la fin du fichier main.php
du thème 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/taskrunner.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 thèmes doivent inclure cette fonction, sans quoi le wiki pourrait ne pas fonctionner correctement (par exemple, la recherche ne fonctionnera pas).
Une classe nommée dokuwiki
devrait être ajoutée à certains contenus entourant l'élément (soit autour de tout ou au moins autour de tpl_content()
) dans main.php, detail.php et mediamanager.php de chaque thème.
Ceci pour être sûr que les styles de DokuWiki n'interfèrent pas avec d'autres styles dans le cas d'intégration à un autre site, ceci pouvant poser potentiellement des conflits entre fichiers CSS.
Les connecteurs (hooks), littéralement «hameçons» en français permettent d'inclure du contenu statique dans votre DokuWiki sans avoir besoin de toucher au thème. 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 thème par défaut de DokuWiki cherche des fichiers spécifiques dans le répertoire lib/tpl/dokuwiki/
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. Bien entendu, cela ne fonctionne qu'en utilisant le thème par défaut ou un thème supportant les mêmes appels de hooks(comme le thème starter).
Si vous manquez d'idées ou de compétences en design, vous pouvez aussi convertir des thèmes existants. Il y a de nombreuses options disponible pour ce faire. Si vous souhaitez publier l'un de ceux-là, merci de vérifier qu'il est bien GPL2-compatible.
Voici quelques problèmes que les développeurs de thèmes rencontrent et comment ils peuvent être évités:
Ceci inclut onLoad
et d'autres. Bien qu'ignorer cette règle n'affecte pas du tout Firefox, Internet Explorer (même IE7) aura des erreurs Javascript à cause du Javascript requis pour l'édition de page, ceci causant des problèmes d'affichage et rendant manquante la barre d'édition au moment de l'édition souhaitée d'une page.
Certains développeurs de thèmes ont rencontré des problèmes avec la mise en cache de fichiers CSS et JS de DokuWiki à cause de cette option active, bien que cela a été difficile à cerner. Pour être tranquille, désactiver cette option temporairement.
Pour ce faire, appuyez sur Ctrl+F5 ou en maintenant enfoncées les touches Maj-Ctrl-Alt tout en cliquant sur le bouton “rafraîchir” du navigateur.
Ceci n'est pas dû à DokuWiki mais plutôt au fonctionnement des navigateurs actuels concernant le cache. Les navigateurs mettent en cache les feuilles de style, d'où cette nécessaire manipulation.
Si vous créez un thème, merci de le partager avec la communauté. Il vous suffit de créer une page du nom de votre thème dans l'espace de noms template. Par exemple, si votre répertoire de thème s'appelle sample
, créer la page template:sample
dans ce wiki.
La page mérite de contenir toute la documentation sur l'installation et l'utilisation du thème. Ajouter une capture d'écran est aussi une bonne idée.
En haut de la page de thème, quelques champs de métadonnées ont besoin d'être renseignés. Une description de chacun d'eux est disponible sur la page de dépôt des extensions.
Depuis la version Ponder Stibbons, un signalement de mise à jour automatique est possible. Pour que ce processus marche convenablement, il est indispensable que la date sur le champ “Last updated on” de la page du thème corresponde à la date indiquée par le fichier template.info.txt situé dans le fichier source tarball / zip du thème.
Les téléversements (upload) ne sont pas autorisés sur dokuwiki.org, ce qui vous oblige à héberger votre thème ailleurs. Nous recommandons de gérer la source avec un logiciel de gestion de versions comme git
. Utiliser un dépôt public comme GitHubest le moyen le plus simple de gérer un dépôt public en vous offrant en même temps un suivi de bug pour votre dépôt.
Si vous voulez convertir un thème WordPress en thème DokuWiki, vous pouvez vous appuyer sur cette documentation .