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-06-19 19:16]
Digitalin mise à jour
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é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 16: Ligne 14:
   - 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 52: Ligne 50:
     * ''​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é)     * ''​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 [[devel:template info|information du thème]] **est requis !**+    * ''​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 thème. 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.
  
 ===== Fonctionnement interne détaillé ===== ===== Fonctionnement interne détaillé =====
Ligne 61: Ligne 59:
 ==== Fonctions ==== ==== Fonctions ====
  
-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.+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 thème. 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 [[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()''​.+  * **''​[[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 82: 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 thème 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.
Ligne 119: Ligne 114:
 ==== 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 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 [[:​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).+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'​ ==== ==== classe '​dokuwiki'​ ====
Ligne 139: Ligne 134:
 ===== Convertir des thèmes existants ===== ===== Convertir des thèmes existants =====
  
-Si vous manquez d'​idées ou de qualités ​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]].+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]].
  
-  * [[WP_to_DW_template|How to convert a WordPress theme to a DokuWiki template]]+  * [[devel:​wp_to_dw_template|How to convert a WordPress theme to a DokuWiki template]]
  
  
Ligne 148: Ligne 143:
 Voici quelques problèmes que les développeurs de thèmes rencontrent et comment ils peuvent être évités: 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=== ​ +===Ne mettez pas de commandes Javascript dans l'étiquette ​<​body> ​d'​une ​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===+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.
  
-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.+===Désactiver "​Compact ​CSS and JavaScript ​files" quand vous développez un thème===
  
-===Use "​forced refreshing" ​after you make changes to CSS files=== +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. 
-You can accomplish this by pressing Ctrl+F5 or by holding down shift-control-alt and hitting the refresh button in your browser.+  
 +=== Utiliser ​"​forced refreshing" ​après avoir fait des changements aux fichiers ​CSS===
  
-This is not due to how DokuWiki worksbut how current browsers cache files. Browsers cache stylesheets even when new versions are available, so you will need to do this.+Pour ce faireappuyez 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 =====
-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.+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.
  
-At the top of the template ​page a few metadata fields have to be filled inA description of each field can be found on the [[plugin:​repository#​template_entry|Repository Plugin]] page.+La page mérite de contenir toute la documentation sur l'​installation et l'​utilisation du thèmeAjouter une capture d'​écran est aussi une bonne idée.
  
-From version Ponder Stibbons on an automated update signalling is possibleFor 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 [[devel:template_info|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.+En haut de la page de thème, quelques champs de métadonnées ont besoin d'​être renseignésUne description de chacun d'eux est disponible sur la page de [[plugin:repository#​template_entry|dépôt des extensions]].
  
-Uploads are not allowed on dokuwiki.orgso you need to host your template files somewhere elseWe recommend to manage your source with a Revision Control System like [[git]]. If you doit's easiest to use a public repository host like [[https://github.com|GitHub]] which also offers a bug tracker for your repository.+Depuis la version Ponder Stibbonsun signalement de mise à jour automatique est possiblePour que ce processus marche convenablementil 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.
  
 +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 =====
  
-===== Mise à jour de la page en cours  =====+  * Actualisation et traduction --- [[user>​Digitalin|Digitalin]] //​2016-05-13 10:52// et //​2016-07-23 13:00//
  
-  *  --- [[user>​Digitalin|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: 
-<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.1466356615.txt.gz · Dernière modification: 2016-06-19 19:16 par Digitalin