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édentesRévision précédente
Prochaine révision
Révision précédente
Prochaine révisionLes deux révisions suivantes
fr:devel:templates [2016-05-15 11:28] – lien template_info Digitalinfr:devel:templates [2018-05-12 21:04] – [Fonctions] lien xref Digitalin
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écente 
  
 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 [[: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.
  
   * ''<dokuwiki>/lib/tpl/<template>/''   * ''<dokuwiki>/lib/tpl/<template>/''
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.txt · Dernière modification : 2023-08-13 14:44 de Klap-in

Sauf mention contraire, le contenu de ce wiki est placé sous les termes de la licence suivante : CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki