DokuWiki

It's better when it's simple

Outils pour utilisateurs

Outils du site


Panneau latéral

Traductions de cette page?:

Découvrir DokuWiki

Options avancées

Pour les entreprises

Notre Communautée


Suivez-nous sur Facebook, Twitter et les autres résaux sociaux.

Notre politique de confidentialité

fr:devel:templates

Ceci est une ancienne révision du document !


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 thème DokuWiki.

  1. Installer le thème starter (la branche “minimale” est une option possible comme point de démarrage propre)
  2. Renommer le répertoire lib/tpl/starter en lib/tpl/monnouveauthème
  3. Sélectionnez votre nouveau thème depuis le Gestionnaire de configuration
  4. 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.
  5. Lorsque votre thème est prêt, vous pouvez le publier sur la page des thèmes de DokuWiki.

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 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>.csstemplate'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 JavaScript
    • main.php – le fichier principal qui sert à afficher les pages
    • detail.php – la page de détail d'une image
    • mediamanager.php – le Gestionnaire de médias
    • images/ – 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)
    • lang/ – fichiers de langue
      • <code de langue>/lang.phpchaînes de caractères utilisées dans le thème (optionnel, à utiliser quand nécessaire)
      • <code de langue>/settings.phpchaînes de caractères utilisées dans le Gestionnaire de configuration (si une configuration est utilisée)
    • style.ini – voir Style.ini
    • favicon.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.

Fonctionnement interne détaillé

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ètre 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()
    Par défaut, c'est la fonction 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 :

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_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.
  • De très nombreuses autres fonctions utiles pour les thèmes sont disponibles. Merci de jeter un œil dans la documentation de l'API.

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 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/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 thèmes doivent inclure cette fonction, sans quoi le wiki pourrait ne pas fonctionner correctement (par exemple, la recherche ne fonctionnera pas).

classe 'dokuwiki'

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.

Inclure des Hooks (hameçons)

Les hooks (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/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. 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).

Convertir des thèmes existants

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.

Problèmes courants à éviter

Voici quelques problèmes que les développeurs de thèmes rencontrent et comment ils peuvent être évités:

Don't put JavaScript commands in the <body> tag of a page

This includes onLoad and others. Although breaking this rule doesn't affect FireFox at all, Internet Explorer (even IE 7) will have JavaScript errors due to the JavaScript required for page editing, and this can result in pages that won't display correctly, and you will find the editing bar will be missing when you need it.

Turn off "Compact CSS and JavaScript files" while developing a template

Some template developers experience problems with DokuWiki cacheing CSS and JS files due to this option being on, although this has been hard to pinpoint. To be safe, turn this off temporarily.

Use "forced refreshing" after you make changes to CSS files

You can accomplish this by pressing Ctrl+F5 or by holding down shift-control-alt and hitting the refresh button in your browser.

This is not due to how DokuWiki works, but how current browsers cache files. Browsers cache stylesheets even when new versions are available, so you will need to do this.

Publier un thème sur dokuwiki.org

If you created a template, please share it with the community. Just create a page named after your template in the template namespace. E.g. if your template folder is named sample create a page template:sample here in the wiki.

The page should contain all needed documentation on how to install and use the template. Adding screenshots might be a good idea as well.

At the top of the template page a few metadata fields have to be filled in. A description of each field can be found on the Repository Plugin page.

From version Ponder Stibbons on an automated update signalling is possible. For the update process to work properly it is necessary that the date “Last updated on” on the template's wiki page equals the date in the file template.info.txt in the source tarball/zip file. If this is not the case the update will not take place or the “Update” signal persists.

Uploads are not allowed on dokuwiki.org, so you need to host your template files somewhere else. We recommend to manage your source with a Revision Control System like git. If you do, it's easiest to use a public repository host like GitHub which also offers a bug tracker for your repository.

Mise à jour de la page en cours

phrases laissées de côté le temps de la mise à jour de la page

  • 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>';
}
fr/devel/templates.1466356752.txt.gz · Dernière modification: 2016-06-19 19:19 par Digitalin