DokuWiki

It's better when it's simple

Outils pour utilisateurs

Outils du site


fr:devel:templates

Différences

Ci-dessous, les différences entre deux révisions de la page.

Lien vers cette vue comparative

Les deux révisions précédentes Révision précédente
Prochaine révision
Révision précédente
fr:devel:templates [2016-05-15 11:39]
Digitalin
fr:devel:templates [2018-05-12 21:04] (Version actuelle)
Digitalin [Fonctions] lien xref
Ligne 1: Ligne 1:
 ======Développement de thèmes DokuWiki====== ======Développement de thèmes DokuWiki======
- 
-:!: mise à jour en cours. Se reporter à la [[devel:​templates|page d'​origine]] pour avoir l'​information la plus ré 
  
 Vous pouvez personnaliser l'​apparence de [[fr:​DokuWiki]] en créant un nouveau [[fr:​template|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/''​. Vous pouvez personnaliser l'​apparence de [[fr:​DokuWiki]] en créant un nouveau [[fr:​template|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/''​.
Ligne 8: Ligne 6:
 ===== Guide de démarrage ===== ===== Guide de démarrage =====
  
-La façon la plus simple ​de 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 [[template:​starter|thème starter]] de DokuWiki car il est propre, simple et respecte les standards de conception d'​un ​template ​DokuWiki.+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 [[template:​starter|thème starter]] de DokuWiki car il est propre, simple et respecte les standards de conception d'​un ​thème ​DokuWiki.
  
   - Installer le thème [[template:​starter]] (la branche "​minimale"​ est une option possible comme point de démarrage propre)   - Installer le thème [[template:​starter]] (la branche "​minimale"​ est une option possible comme point de démarrage propre)
-  - Renommer le répertoire ''​lib/​tpl/​starter''​ en ''​lib/​tpl/​monnouveautemplate''​+  - Renommer le répertoire ''​lib/​tpl/​starter''​ en ''​lib/​tpl/​monnouveauthème''​
   - Sélectionnez votre nouveau thème depuis le Gestionnaire de configuration   - 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 [[#​structure du répertoire d'un thème|fichiers qui composent le thème]] et la façon dont [[fr:​DokuWiki]] manipule ses [[fr:​css|feuilles de style]].   - Changer ensuite votre thème selon vos envies. Pour comprendre comment les thèmes de DokuWiki sont construits, jetez un œil aux [[#​structure du répertoire d'un thème|fichiers qui composent le thème]] et la façon dont [[fr:​DokuWiki]] manipule ses [[fr:​css|feuilles de style]].
   - Lorsque votre thème est prêt, vous pouvez le [[#​publier_un_theme_sur_dokuwikiorg|publier]] sur la page des [[fr:​templates|thèmes]] de DokuWiki.   - Lorsque votre thème est prêt, vous pouvez le [[#​publier_un_theme_sur_dokuwikiorg|publier]] sur la page des [[fr:​templates|thèmes]] de DokuWiki.
  
-==== Conventions de nommage des thèmes ​====+=== Conventions de nommage des thèmes ===
  
 Le nom (nom du répertoire) d'un thème valide : Le nom (nom du répertoire) d'un thème valide :
Ligne 23: Ligne 21:
   * Les caractères point "​."​ ou trait souligné "​_"​ ne sont pas autorisés car :   * 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       * l'​infrastructure logicielle de DokuWiki ne les prend pas en charge partout
-      * utiliser le trait souligné "​_"​ donnera la valeur zéro à la [[:​popularity|cote de popularité]].+      * utiliser le trait souligné "​_"​ donnera la valeur zéro à la [[fr:​popularity|cote de popularité]].
   * Si le même nom est utilisé par deux thèmes différents ​   * Si le même nom est utilisé par deux thèmes différents ​
       * ils s'​excluent mutuellement et sont intrinsèquement incompatibles,​       * ils s'​excluent mutuellement et sont intrinsèquement incompatibles,​
Ligne 33: Ligne 31:
 ===== Structure du répertoire d'un thème ===== ===== 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). +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 ''​[[fr:​css#​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. Les fichiers CSS sont spécifiés dans le fichier ''​[[fr:​css#​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.
Ligne 45: Ligne 43:
     * ''​images/''​ -- toutes les images utilisées pour le thème (s'il y en a)     * ''​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)     * ''​conf/''​ -- fichiers de configuration (optionnel, si une configuration est utilisée)
-      * ''​default.php''​ -- [[devel:​configuration#​default settings]] ​(voir ''​[[#tpl_getConf]]''​)+      * ''​default.php''​ -- [[devel:​configuration#​default settings|paramètres par défaut]] pour les [[devel:​configuration#template_settings|paramètres du thème]]
       * ''​metadata.php''​ -- [[devel:​configuration#​configuration metadata]] décrit les propriétés des paramètres utilisés par le Gestionnaire de configuration       * ''​metadata.php''​ -- [[devel:​configuration#​configuration metadata]] décrit les propriétés des paramètres utilisés par le Gestionnaire de configuration
     * ''​lang/''​ -- fichiers de langue     * ''​lang/''​ -- fichiers de langue
       * ''<​code de langue>/​lang.php''​ -- [[devel:​localization#​template_localization|chaînes de caractères]] utilisées dans le thème (optionnel, à utiliser quand nécessaire)       * ''<​code de langue>/​lang.php''​ -- [[devel:​localization#​template_localization|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)+      * ''<​code de langue>/​settings.php''​ -- [[devel:​localization#​template_localization|chaînes de caractères]] utilisées dans le Gestionnaire de configuration (si une configuration est utilisée)
     * ''​style.ini''​ -- voir [[fr:​CSS#​Style.ini]]     * ''​style.ini''​ -- voir [[fr:​CSS#​Style.ini]]
 +    * ''​favicon.ico''​ -- favicon (peut être écrasé en téléversant un autre à la racine ou dans l'​espace de noms wiki quand  [[xref>​tpl_favicon()|tpl_favicon()]] est utilisé)
 +    * ''​template.info.txt''​ -- Un fichier texte avec [[fr:​devel:​template_info|information du thème]] **est requis !**
  
-la manipulation des paramètres de configuration est analogue aux [[devel:​common_plugin_functions|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. 
  
 +La manipulation des paramètres de configuration est analogue aux [[devel:​common_plugin_functions|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.
  
-===== Fonctions ​=====+===== Fonctionnement interne détaillé ​=====
  
-Une liste des fonctions disponibles est accessible dans la [[http://dev.splitbrain.org/​reference/​dokuwiki/​nav.html?​inc/​template.php.html|documentation de l'​API]]. Certaines sont listées ci-dessous.+==== Fonctions ==== 
 + 
 +Une liste des fonctions disponibles est accessible dans la [[https://xref.dokuwiki.org/​reference/​dokuwiki/​nav.html?​inc/​template.php.html|documentation de l'​API]]. Certaines sont listées ci-dessous.
  
   * **''​[[xref>​tpl_content()]]''​** \\ Cette fonction affiche le contenu d'une page du wiki, y compris la [[fr:​toc|table des matières]]. Il est possible d'​empêcher cela en passant le paramètre ''​false''​ quand on appelle la fonction :<code php>   * **''​[[xref>​tpl_content()]]''​** \\ Cette fonction affiche le contenu d'une page du wiki, y compris la [[fr:​toc|table des matières]]. Il est possible d'​empêcher cela en passant le paramètre ''​false''​ quand on appelle la fonction :<code php>
 tpl_content(false);​ tpl_content(false);​
-</​code>​ 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.+</​code>​ 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.
  
  
-  * **''​[[xref>​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()''​.+  * **''​[[xref>​tpl_toc()]]''​** \\ Par défaut, c'est la fonction ''​tpl_content()''​ qui s'​occupe d'​afficher la [[fr:toc|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:​** **Exemple:​**
Ligne 78: Ligne 80:
 </​code>​ </​code>​
  
-La fonction ''​tpl_toc()''​ construit la table des matières depuis trois sources différentes : +La fonction ''​tpl_toc()''​ construit la table des matières depuis trois sources différentes:​ une variable d'​[[devel:​environment#​$TOC|environnement]] globaleles [[devel:​metadata|métadonnées]] de la page ou la méthode ''​getTOC()''​ utilisée par les [[devel:admin_plugins|plugins d'​administration]].
-  * une variable d'​[[devel:​environment#​$TOC|environnement]] globale +
-  * les métadonnées de la page +
-  * la méthode ''​getTOC()''​ utilisée par les [[devel:admin plugins|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'​[[devel:​environment#​$TOC|environnement]] globale dans ces cas précis. Et comme la variable d'​[[devel:​environment#​$TOC|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.+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'​[[devel:​environment#​$TOC|environnement]] globale dans ces cas précis. Et comme la variable d'​[[devel:​environment#​$TOC|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:​** **Exemple:​**
Ligne 105: Ligne 104:
  
  
-  * **''​[[xref>​tpl_getConf()|tpl_getConf('​key'​)]]''​** \\ Cette fonction est utilisée pour accéder aux [[devel:​configuration|paramètres de configuration]] depuis le template.+  * **''​[[xref>​tpl_getConf()|tpl_getConf('​key'​)]]''​** \\ Cette fonction est utilisée pour accéder aux [[devel:​configuration|paramètres de configuration]] depuis le thème.
  
   * **''​[[xref>​tpl_getLang()|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 [[devel:​localization]] de la documentation développement.   * **''​[[xref>​tpl_getLang()|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 [[devel:​localization]] de la documentation développement.
  
-  * Further many other useful template functions are availablePlease have a look in [[xref>​inc/​template.php|API ​documentation]].+  * De très nombreuses autres fonctions utiles pour les thèmes sont disponiblesMerci de jeter un œil dans la [[xref>​inc/​template.php|documentation de l'API]].
  
  
  
-===== Variables globales et constantes ​=====+==== Variables globales et constantes ====
  
-Pour une liste complète des Variables ​globales et des constantes, consultez la page [[devel:​environment]].+Pour une liste complète des variables ​globales et des constantes, consultez la page [[devel:​environment|environnement]].
  
-===== Indexation automatisée ​=====+==== Indexation automatisée ====
  
-Presque à la fin du fichier ''​[[devel:​templates:​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 à ''​[[fr:​indexer|lib/​exe/​indexer.php]]''​. **C'​est une partie vitale de DokuWiki** qui fournit une indexation automatique de la page pour l'​outil de [[:​search|recherche]] et d'​autres fonctions importantes comme la génération d'une [[:​sitemap|carte du site en XML]] (utilisée par les moteurs de recherche internet) ou la [[:​metadata|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, [[fr:​search|la recherche]] ne fonctionnera pas).+Presque à la fin du fichier ''​[[devel:​templates:​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 à ''​[[fr:​indexer|lib/​exe/​indexer.php]]''​. **C'​est une partie vitale de DokuWiki** qui fournit une indexation automatique de la page pour l'​outil de [[:​search|recherche]] et d'​autres fonctions importantes comme la génération d'une [[fr:​sitemap|carte du site en XML]] (utilisée par les moteurs de recherche internet) ou la [[:​metadata|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, [[fr:​search|la recherche]] ne fonctionnera pas).
  
 +==== classe '​dokuwiki'​ ====
  
-===== Hooks =====+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 [[devel:​templates:​main.php]],​ [[devel:​templates:​detail.php]] et [[devel:​templates:​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 hooks (hameçons ​en françaispermettent d'​inclure du contenu statique dans votre [[fr:​DokuWiki]] sans avoir besoin de toucher au [[fr:​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.+==== Inclure des Hooks (hameçons) ​====
  
-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**.+Les hooks (hameçons en français) permettent d'​inclure du contenu statique dans votre [[fr:DokuWiki]] sans avoir besoin ​de toucher ​au [[fr:​template|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.
  
-==== Hooks disponibles ====+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 [[template:​dokuwiki#​supported_include_hooks|les mêmes appels de hooks]](comme le thème starter).
  
-Tous ces fichiers sont recherchés dans le répertoire ''​lib/​tpl/​default/''​. 
  
-^ Nom de fichier ​     ^ Emplacement du fichier HTML inclu dans le template ​                                           ^ +===== Convertir ​des thèmes existants =====
-| ''​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.+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 [[https://​www.gnu.org/​philosophy/​license-list.html#​GPLCompatibleLicenses|GPL2-compatible]]. 
 + 
 +  * [[devel:​wp_to_dw_template|How to convert a WordPress theme to a DokuWiki template]] 
 + 
 + 
 +===== Problèmes courants à éviter ===== 
 + 
 +Voici quelques problèmes que les développeurs de thèmes rencontrent et comment ils peuvent être évités: 
 + 
 +===Ne mettez pas de commandes Javascript dans l'​étiquette <​body>​ d'une page=== 
 + 
 +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. 
 + 
 +===Désactiver "​Compact CSS and JavaScript files" quand vous développez un thème=== 
 + 
 +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. 
 +  
 +=== Utiliser "​forced refreshing"​ après avoir fait des changements aux fichiers CSS=== 
 + 
 +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.
  
  
 ===== Publier un thème sur dokuwiki.org ===== ===== Publier un thème sur dokuwiki.org =====
----- 
  
 +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.
  
-===== Mise à jour de la page en cours  =====+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 [[plugin:​repository#​template_entry|dépôt des extensions]].
  
-  *  --- [[user>​Digitalin|Digitalin]] //2016-05-13 10:​52// ​+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 ​[[fr:​devel:​template_info|template.info.txt]] situé dans le fichier source tarball ​zip du thème.
  
-**phrases laissées ​de côté ​le temps de la mise à jour de la page**+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 [[https://​github.com|GitHub]]est ​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.  
 + 
 +===== Crédits ===== 
 + 
 +  ​Actualisation et traduction --- [[user>​Digitalin|Digitalin]] //​2016-05-13 10:52// et //​2016-07-23 13:00//
  
-  * (voir ''​[[#​tpl_getConf()]]''​) 
-  * Voila un petit script pour déterminer dans quel partie du site vous êtes: 
-<code php> 
-$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>';​ 
-} 
-</​code>​ 
fr/devel/templates.1463305188.txt.gz · Dernière modification: 2016-05-15 11:39 par Digitalin