Note :
Une bonne compréhension de HTML, CSS (et JS) est nécessaire. Beaucoup d'informations sur la conception de sites Web sont disponibles sur Internet. Nous nous concentrerons seulement sur les points qui sont propres à phpBB 3.2.x / 3.1.x.
Note :
Cette documentation est une suite logique au chapitre « Modification de styles » (en anglais) de la page « Installation et utilisation de styles » (en anglais). Lisez-la avant d'utiliser ce guide, car nous n'y reviendrons pas ici.
Astuce :
La meilleure façon d'apprendre à créer ou à modifier des styles est de prendre des d'exemples. Jetez un œil à certains des styles populaires dans la base de données de styles et voyez comment ils fonctionnent.
Petite FAQ des styles
Puis-je soumettre un style dans la base de données de styles phpBB-fr.com ?
Oui, vous pouvez soumettre un style que vous avez créé et que vous souhaitez partager avec la communauté. L'équipe des graphistes de phpBB-fr.com examinera votre soumission et, si elle est sans erreur, l'ajoutera dans notre base de données.
Existe-t-il des règles que je dois lire avant de soumettre un style dans la base de données des styles ?
Oui. Tous les auteurs doivent lire la Politique de soumission de styles (en anglais) afin de prendre connaissance des règles pour soumettre des styles dans notre base de données et comment y envoyer les fichiers.
Pourquoi mes modifications sur les templates ou les fichiers CSS ne s'affichent pas sur mon site ?
Cela est probablement dû à la mise en cache. Le moteur de template de phpBB doit traiter (compiler) les templates du style avant de pouvoir les afficher. Il s'agit d'un processus nécessitant beaucoup de ressources. De ce fait, il met en « cache » les pages traitées afin d'y accéder plus rapidement. Si vous modifiez les fichiers de templates, vous devrez purger le cache de votre forum (ou vos modifications n'apparaîtront pas). Vous pouvez le faire en vous rendant dans l'onglet « Général » du PCA puis en cliquant sur le bouton correspondant à « Purger le cache ».
De plus, votre navigateur peut également charger une ancienne version en cache des éléments du thème. Assurez-vous de « rafraîchir » votre navigateur, en utilisant une commande comme « Ctrl+F5 ».
Si un style n'a pas été mis à jour par l'auteur, puis-je le mettre à jour moi-même et le soumettre dans la base de données ?
Si l'auteur ne souhaite plus assurer le suivi de son style, il doit expressément accorder une autorisation à la personne qui reprendra son travail.
Toutefois, si l'auteur original est injoignable, vous pouvez mettre à jour le style et le soumettre (en précisant que c'est le cas dans le champ « Message à l'équipe »). Cependant, si l'auteur original du style revient, il peut alors réclamer le style s'il le souhaite. L'auteur original aurait la possibilité de conserver les mises à jour que vous auriez publiées ou de les utiliser ou de les intégrer comme il le souhaite.
Structure de fichiers
Comme mentionné dans le guide Installation et utilisation de styles (en anglais), les styles ont une structure de répertoires spécifique. Nous vous conseillons vivement d’utiliser cette même structure, afin de minimiser les chances d’obtenir des erreurs du type « fichiers non trouvés ».
- Code: Tout sélectionner
styles/ nom_de_mon_style/ template/ overall_header.html mon_script.js theme/ images/ background.jpg stylesheet.css extra.css style.cfg
Préparation
Note :
Effectuez toujours une sauvegarde des fichiers et de la base de données de votre forum avant de modifier le code. Il est généralement très difficile de fournir de l’assistance aux utilisateurs qui modifient eux-mêmes le code.
Choisir un style « parent »
La création d'un style de A à Z est un travail considérable (et nécessite beaucoup de compétences), c'est pourquoi nous vous conseillons de choisir un style existant à utiliser comme style « parent ».
Comme vous passerez probablement plusieurs heures à créer votre nouveau style, il est essentiel de choisir le bon style « parent ». Vous voulez une base solide pour votre style. Le choix le plus simple est évidemment d'utiliser le style par défaut de phpBB 3.2.x / 3.1.x (prosilver) comme parent, puisqu'il inclut toutes les nouvelles fonctionnalités et qu'il a été testé de manière approfondie.
Choisir un style (comme prosilver) qui possède tous les évènements de template (events), veillera également à ce que les extensions fonctionnent correctement. Pour plus d'informations, lisez la section Évènements de template.
Créer un « squelette »
La première chose à faire est de créer la structure de fichiers pour votre nouveau style. Lisez la section Structure de fichiers pour savoir à quoi ressemble un squelette de base.
Créez tous les répertoires requis (template, theme, images) et les fichiers style.cfg et stylesheet.css. Vous êtes maintenant prêt à copier les templates et les éléments de thème que vous souhaitez utiliser.
Note :
Nous vous conseillons de lire le reste de ce guide avant de commencer la création ou la modification de style.
Astuce :
Ne modifiez pas un style existant. Créez-en une copie et modifiez le fichier style.cfg afin qu'il hérite du style précédemment copié. Consultez les sections Héritage de template et Héritage de thème pour plus d'informations.
Style.cfg
Le fichier le plus important du style (en ce qui concerne l'installation) est le fichier style.cfg. Il fournit des informations à votre forum phpBB sur la façon d'installer et de traiter le style. Il ressemble généralement à ceci :
- Code: Tout sélectionner
# # phpBB Style Configuration File # # This file is part of the phpBB Forum Software package. # # @copyright (c) phpBB Limited <https://www.phpbb.com> # @license GNU General Public License, version 2 (GPL-2.0) # # For full copyright and license information, please see # the docs/CREDITS.txt file. # # At the left is the name, please do not change this # At the right the value is entered # # Values get trimmed, if you want to add a space in front or at the end of # the value, then enclose the value with single or double quotes. # Single and double quotes do not need to be escaped. # # # General Information about this style name = prosilver copyright = © phpBB Limited, 2007 style_version = 3.2.0 phpbb_version = 3.2.0 # Defining a different template bitfield # template_bitfield = lNg= # Parent style # Set value to empty or to this style's name # if this style does not have a parent style parent = prosilver
La majeure partie de ce contenu est assez évidente. Les valeurs les plus importantes pour nos besoins sont les champs name = et parent = qui définissent l'héritage de style.
Disons que vous voulez créer un style basé sur prosilver. Votre fichier style.cfg contiendra les lignes suivantes (les autres lignes ont été omises pour plus de clarté) :
- Code: Tout sélectionner
name = mon style parent = prosilver
Après avoir installé votre style hérité de prosilver, l'arborescence des styles de votre ACP ressemblera à ceci :
Au lieu d'utiliser prosilver en tant que style parent, vous pouvez également utiliser un autre style (par exemple : prosilver special edition, qui lui aussi hérite de prosilver). Votre fichier style.cfg contiendra alors les lignes suivantes :
- Code: Tout sélectionner
name = mon style parent = prosilver Special Edition
Après avoir installé votre style hérité de prosilver special edition, l'arborescence des styles de votre ACP ressemblera à ceci :
Éléments obligatoires
Le code de n'importe quel site Web nécessite certains éléments pour qu'il fonctionne correctement. Ceux-ci sont définis dans les spécifications HTML et CSS. Pour plus d'informations sur l'écriture de codes valide, consultez la section Validation du code.
En plus de ces éléments, phpBB 3.2.x / 3.1.x nécessite que les styles incluent certaines portions de code spécifiques afin qu'un style puisse fonctionner correctement.
Si vous utilisez un style 3.2.x / 3.1.x valide comme parent pour votre nouveau style, ces éléments obligatoires seront déjà inclus, mais étant donné qu'ils sont très importants, nous allons consacrer cette section à une description plus détaillée.
Note :
Pour plus d'informations sur la façon dont ces portions de code sont utilisées par les styles et les extensions, consultez la page Wiki de développement sur les nouvelles commandes de template pour 3.1 (en anglais).
{$STYLESHEETS}
Le système d'extension phpBB 3.2.x / 3.1.x permet aux extensions d'ajouter des fichiers CSS personnalisés (externes) au rendu final de votre page. Ceci peut être réalisé via l'utilisation de la commande de template <!-- INCLUDECSS mon_style.css -->.
Ce que cette commande fait, c'est ajouter les fichiers spécifiés à la file d'attente des fichiers qui seront chargés dans la variable de template {$STYLESHEETS}. Donc, si vous n'incluez pas cette variable dans votre template, de nombreuses extensions ne fonctionneront pas (puisque le pré-traitement du style s'appuie sur ces fichiers).
Note :
{$STYLESHEETS} doit être présent vers la fin de l'élément <head> dans le fichier overall_header.html. Idéalement avant la balise </head>.
{$SCRIPTS}
La variable de template {$SCRIPTS} fonctionne de la même manière que {$STYLESHEETS}, mais est destinée à l'inclusion des fichiers JavaScript. Les auteurs d'extension l'utilisent en ajoutant la commande de template <!-- INCLUDEJS my_scripts.js -->. Comme pour les feuilles de style, la variable {$SCRIPTS} est nécessaire pour que votre style (et vos extensions) fonctionnent correctement.
Note :
{$SCRIPTS} doit être présent vers la fin du fichier overall_footer.html. Idéalement avant la balise </body>.
JQuery
Depuis la version 3.1 de phpBB, la librairie jQuery est incluse par défaut dans le package disponible en téléchargement. Outre le fait que jQuery puisse être très pratique pour les auteurs de style, de nombreuses extensions l'utilisent aussi et dépendent du fait qu'elle soit activée.
Par conséquent, vous devez toujours inclure les instructions qui chargent jQuery dans votre template. Vous pouvez le faire en vous assurant que le code suivant est présent dans votre template overall_footer.html.
- Code: Tout sélectionner
<script type="text/javascript" src="{T_JQUERY_LINK}"></script> <!-- IF S_ALLOW_CDN --><script type="text/javascript">window.jQuery || document.write('\x3Cscript src="{T_ASSETS_PATH}/javascript/jquery.min.js?assets_version={T_ASSETS_VERSION}">\x3C/script>');</script><!-- ENDIF -->
Note :
Cet extrait de code jQuery doit idéalement être le premier script qui est chargé dans le pied de page. En tout cas, il doit être inclus avant {$SCRIPTS}.
Syntaxe et variables de template
phpBB 3.2.x / 3.1.x dispose d'un puissant moteur de template, qui vous permet d'ajouter ou modifier divers éléments de code pour le rendu final des pages.
Pour plus d'informations sur l'utilisation des différentes balises et structures de contrôle au sein des templates, nous vous conseillons de consulter le Wiki de développement de phpBB.com. À l'heure actuelle, il n'y a pas encore d'entrées dédiées spécifiquement pour les styles 3.2.x / 3.1.x, mais quelques pages importantes sont toujours applicables :
- Tutoriel de syntaxe de template (en anglais)
- Catalogue des variables de template (en anglais)
- Erreurs de template les plus fréquentes (en anglais)
Astuce :
Depuis la version 3.1, phpBB utilise Twig comme base de son moteur template. Vous pouvez utiliser la syntaxe Twig pour votre style, qui peut avoir de nombreux avantages. Pour plus d'informations, consultez la section Utilisation de Twig dans phpBB.
Événements de template
Avec l'introduction du système d'extension dans phpBB 3.1.x, les extensions peuvent insérer un code sans modifier les fichiers de template. Cela simplifie grandement les processus d'installation, de mise à jour ou de suppression de fonctionnalités pour les styles.
De nombreuses extensions utilisent ces événements de template afin d'ajouter des fonctionnalités à phpBB. Elles le font en utilisant la commande de template <!-- EVENT template_event_name -->. Si vous voulez que votre style devienne populaire, vous devriez faire en sorte qu'il inclue le plus d'événements de template « par défaut » que possible.
prosilver étant le style par défaut de phpBB 3.2.x / 3.1.x, la plupart des extensions seront principalement développées pour prosilver (et donc utiliseront les évènements de template de prosilver). En incluant ces événements (au mêmes endroits que dans prosilver), vous assurerez que les extensions futures fonctionneront avec votre style.
Note :
Une liste complète de tous les événements de template actuellement disponibles dans prosilver se trouve sur la page Event List (en anglais) du Wiki de développement.
Astuce :
Au lieu d'insérer tous les événements de template aux bons endroits dans les templates de votre style, vous pouvez utiliser l']héritage de template.
Héritage de template
L'héritage de template est sans doute l'élément le plus utile à connaître au sujet du moteur de template de phpBB pour les auteurs de style.
Si vous basez votre nouveau style à partir d'un style existant, mais que vous souhaitez ne modifier que quelques fichiers de template, vous n'êtes pas obligé de tous les copier. Cela encombrerait votre serveur de copies de fichiers identiques. Il serait également très fastidieux de reporter toutes les modifications apportées aux templates, si le style parent venait à être mis à jour.
Activer l'héritage de template, ne nécessite qu'une seule ligne dans votre fichier style.cfg.
En spécifiant un style parent dans votre fichier style.cfg, le moteur de template sait comment appeler les templates du style parent s'ils sont manquant dans votre style. Le petit plus étant que le processus est complètement transparent après la compilation du style et ne génère pratiquement aucune surcharge au cours de l'exécution.
Concrètement, cela signifie que phpBB essaiera de trouver un fichier dans le répertoire /template de votre nouveau style, mais que s'il ne le trouve pas, il recherchera le fichier dans le répertoire /template des styles parents. Ce processus peut atteindre plusieurs niveaux de profondeur. Ainsi, vous pouvez baser votre style enfant sur un style enfant d'un style enfant d'un style parent, comme les branches d'un arbre, d'où « l'arborescence des styles » (en anglais).
Note :
Avec l'introduction des événements de template, l'héritage de template est devenu beaucoup plus puissant. Nous vous conseillons de l'utiliser autant que possible.
Exemple :
Beaucoup de styles passent par la modification de styles existants (tel que prosilver), car créer un nouveau style à partir de zéro est une entreprise extrêmement chronophage. L'exemple suivant montrera à quel point il est facile (et utile) d'utiliser l'héritage.
Étude de cas : « Je souhaite modifier l'en-tête et la page d'index du style X, comment puis-je le faire ? »
La première chose à retenir, c'est que vous voulez modifier seulement ces 2 parties aujourd'hui. Vous voudrez probablement changer de plus en plus de choses à mesure que le temps passe. Donc, la meilleure manière de faire est de créer un style « enfant » (que l'on appellera Y) d'un style X parent.
- Créez la structure de fichiers (squelette) pour le style Y.
- Créez un fichier style.cfg pour le style Y qui spécifie le style X comme parent.
- Copiez les fichiers overall_header.html, simple_header.html et index_body.html à partir de ./styles/X/template/ vers ./styles/Y/template/
- Modifiez les fichiers en fonction de vos besoins.
- Transférez les fichiers de votre style sur votre serveur Web dans le répertoire styles de votre installation phpBB.
- Installez le style Y depuis le PCA de votre forum.
C'est tout ? Pas tout à fait. Vous remarquerez qu'aucune feuille de style et aucune image n'ont été chargées. Nous aborderons ce point dans la section suivante.
Héritage de thème
Le plus grand obstacle pour la plupart des auteurs de style est le fait que l'héritage de style ne fonctionne que pour les templates, et non pour les CSS. Alors, comment utiliser l'héritage des éléments du thème du style parent ?
Il existe plusieurs façons de le faire, et cela dépendra de l'opportunité ou non de prévoir des modifications vraiment significatives dans les fichiers CSS. Nous allons essayer d'expliquer les différentes façons d'hériter les thématiques du style à partir d'autres styles et leurs avantages et inconvénients.
Note :
Les éléments du thème ne peuvent pas être « hérités » de la même manière que les templates. Il n'y a pas de système automatisé ici. L'héritage de théme doit être interprété comme suit : « chargement des éléments d'un style différent, par des instructions manuelles ».
Méthode 1. Copier/coller tous les éléments du thème
La méthode la plus simple (et probablement la plus utilisée) est de simplement copier/coller tous les éléments du répertoire theme/ du style parent vers le répertoire theme/ du style enfant et d'adapter les différents fichiers CSS à vos besoins.
Bien que ce soit la méthode la plus simple, il est fortement déconseillé de l'utiliser, surtout si vous prévoyez de publier votre style publiquement, pour les raisons suivantes :
Avantages :
- Modification facile.
- Ne nécessite aucune modification de template.
- Mauvaise maintenabilité.
- Complexifie les reports de modifications lors de la mise à jour des styles parents.
- Duplication du contenu.
Méthode 2. @import avec remplacement sélectif
Si vous souhaitez apporter des modifications seulement à quelques-uns des fichiers CSS du style parent, vous ne voudrez peut-être pas copier tous les fichiers, cela encombrerait votre style. Il est possible de ne copier que les fichiers que vous voulez modifier, sans avoir des copies de fichiers identiques sur votre serveur. Dans le fichier stylesheet.css de votre style, vous pouvez inclure le code suivant :
- Code: Tout sélectionner
@import url("../../prosilver/theme/common.css"); @import url("../../prosilver/theme/links.css"); @import url("../../prosilver/theme/content.css"); @import url("../../prosilver/theme/buttons.css"); @import url("../../prosilver/theme/cp.css"); @import url("../../prosilver/theme/forms.css"); @import url("colours.css");
Cela importe les éléments CSS de prosilver, à l'exception de colours.css, que vous souhaitez charger à partir du répertoire theme/ de votre style (que vous avez donc copié depuis prosilver et modifié en fonction de vos besoins).
Avantages :
- Déduplication des éléments.
- Ne nécessite aucune modification de template.
- Les règles de chemin relatif @import sont un risque de sécurité (en anglais) potentiel ! (À éviter si possible)
- Il faut néanmoins une copie de tous les fichiers qui ne sont pas inclus dans stylesheet.css (responsive.css, fr/stylesheet.css, etc.)
Au lieu de copier les fichiers du thème parent et de les modifier, vous pouvez également écrire de nouvelles règles, dans le fichier overall_header.html de votre style, qui remplacent les règles du style parent.
- Code: Tout sélectionner
<link href="{ROOT_PATH}styles/prosilver/theme/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet"> <Link href="{T_STYLESHEET_LINK}" rel="stylesheet">
Note :
Nous utilisons {T_ASSETS_VERSION} comme forme rudimentaire de contrôle du cache du navigateur.
Note :
Bien que {T_SUPER_TEMPLATE_NAME} soit encore pris en charge, il ne parcourt que le 1er niveau de l'arborescence des styles. Donc, il n'est pas approprié pour une utilisation lors d'héritages multiples.
Ce que cela fait, c'est de charger en premier lieu le fichier stylesheet.css de prosilver (et charger tous les composants déclarés via la méthode @import comme décrit précédemment dans ce guide). Ensuite, il va charger le stylesheet.css de votre style personnalisé. Vous pouvez utiliser les règles @import dans votre propre fichier stylesheet.css bien sûr (si vous souhaitez diviser votre code en plusieurs fichiers), ou vous pouvez simplement mettre toutes vos règles CSS dans le fichier stylesheet.css lui-même.
Note :
Il n'est pas conseillé d'utiliser les deux règles @import et règles CSS régulières dans le même fichier.
Cette même méthode peut être appliquée pour charger d'autres éléments CSS directement à partir du style parent (sans devoir les dupliquer), tel que responsive.css, print.css, bidi.css, etc. Si vous souhaitez utiliser les ressources linguistiques du style parent, Vous pouvez utiliser la portion de code suivante :
- Code: Tout sélectionner
<Link href="{ROOT_PATH}styles/prosilver/theme/{T_THEME_LANG_NAME}/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
Avantages :
- Pas de règles @import.
- Possibilité de tout dédupliquer.
- Pas de contrôle détaillé sur les parties du fichier stylesheets.css du style parent à inclure ou exclure.
Méthode 4. Remplacement avancé des éléments du thème dans <head>
Cette méthode fonctionne de la même manière que la méthode 3, mais au lieu d'inclure le fichier stylesheet.css du style parent (prosilver), vous chargez directement les différents éléments CSS (sans @import) à partir du fichier overall_header.html de votre style. Cela permet de mieux contrôler les fichiers à inclure ou exclure.
D'un point de vue technique, c'est la meilleure méthode à utiliser.
- Code: Tout sélectionner
<link href="{ROOT_PATH}styles/prosilver/theme/common.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet"> <link href="{ROOT_PATH}styles/prosilver/theme/links.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet"> <link href="{ROOT_PATH}styles/prosilver/theme/content.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet"> <link href="{ROOT_PATH}styles/prosilver/theme/buttons.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet"> <link href="{ROOT_PATH}styles/prosilver/theme/cp.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet"> <link href="{ROOT_PATH}styles/prosilver/theme/forms.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet"> <link href="{T_STYLESHEET_LINK}" rel="stylesheet"> <link href="{ROOT_PATH}styles/prosilver/theme/{T_THEME_LANG_NAME}/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
Notez que vous n'avez pas inclus colours.css, car vous voulez utiliser vos propres règles personnalisées (que vous allez spécifier dans votre stylesheet.css) au lieu de celui de prosilver.
Avantages :
- Contrôle complet des éléments du thème à charger (et dans quel ordre).
- Aucune utilisation de l'instruction @import dans la CSS (c'est préférable).
- Possibilité de tout dédupliquer.
- Le fichier overall_header.html est plus complexe.
Quelle méthode dois-je utiliser ?
Cela dépend de la quantité de changements que vous envisagez de faire. Du point de vue technique et de maintenance, nous suggérons la méthode 3 dans un cas de changements d'éléments relativement mineurs et la méthode 4 pour des modifications plus importantes.
Astuce :
Si vous souhaitez réduire la charge de transfert de données CSS, vous pouvez compresser et minifier les fichiers CSS que votre style utilise en un seul fichier. Mais ce n'est pas facile à faire et cela exige un traitement des tâches plus complexe (ce qui dépasse le cadre de cette documentation).
Styles et extensions
Ceci est totalement facultatif, mais si vous pensez que les utilisateurs de votre style souhaitent utiliser des extensions particulières (populaires), vous voudrez peut-être ces extensions puisse prendre en charge votre style.
Ceci est particulièrement utile si votre style a une disposition peu conventionnelle ou a des éléments CSS/images considérablement modifiés, ce qui peut rendre l'affichage d'extensions qui utilisent leur propre style, assez moche et hors de contexte.
De nombreuses extensions incluent leur propre feuille de style en utilisant <!-- INCLUDECSS my_extension.css --> ce qui ajoute le fichier référencé à {$STYLESHEETS} dans votre <head> (comme décrit dans la section Éléments obligatoires).
Comme, dans tout style correctement créé, la variable {$STYLESHEETS} est placée après <link href="{T_STYLESHEET_LINK}">, cela signifie que les règles CSS de l'extension annuleront les règles de votre style (comme prévu).
Vous remarquerez que cela vous pose un problème. Vous ne pouvez pas inclure de règles spécifiques pour ces extensions dans le fichier stylesheet.css de votre style, car elles seront annulées. Vous pouvez remédier à cela en utilisant des sélecteurs CSS plus forts ou en ajoutant !important aux déclarations CSS, mais ce n'est pas une solution très élégante.
Au lieu de cela, Vous pouvez simplement inverser l'ordre de chargement pour les règles de styles spécifiques à l'extension. La façon la plus simple de le faire consiste à déplacer toutes les règles de votre style dédiées aux extensions dans un nouveau fichier CSS (par exemple, /theme/extensions.css).
Maintenant, vous devons l'inclure dans la balise <head> de votre fichier overall_header.html, mais après {$STYLESHEETS}.
- Code: Tout sélectionner
{$STYLESHEETS} <link href="{T_THEME_PATH}/extensions.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
L'utilisation de cette méthode garantira que vos règles personnalisées seront chargées après les règles de l'extension, en les écrasant.
Astuce :
Si (et seulement si) vous avez un style très populaire, et qu'une extension utilise des templates qui ne fonctionnent pas bien avec votre style, vous pouvez contacter l'auteur de l'extension. S'il accepte, vous pouvez lui founir un template adapté qu'il incluera dans son extension (via GitHub ou une autre méthode).
Utilisation de Twig dans phpBB
Depuis la version 3.1, phpBB utilise Twig comme base pour son moteur de template. Vous pouvez utiliser la syntaxe Twig pour votre style, ce qui peut avoir de nombreux avantages.
Afin de garantir une rétrocompatibilité, l'ancienne syntaxe phpBB est toujours prise en charge (et largement utilisée), mais elles sont retranscrites en arrière plan dans la syntaxe Twig. Ainsi, <-- IF FOO -->{BAR}<-- ENDIF --> devient {% IF FOO %}{{ BAR }}{% endif %} en étant retranscrit dans la syntaxe native de Twig.
Sensiolabs fournit sur son site web une documentation complète (en anglais) pour le moteur de template Twig. Et plus particulièrement, la section Twig for Template Designers sera une ressource utile pour les auteurs de style, donc nous ne traiterons pas ce point ici. Au lieu de cela, nous aborderons certaines des spécificités liées à l'implémentation de Twig dans phpBB 3.2.x / 3.1.x.
Fonctionnalités disponibles
À ce jour, la dernière version de phpBB 3.2 (3.2.1) a été livrée avec Twig version 1.33.2 et la dernière version de phpBB 3.1 (3.1.11) a été livré avec Twig version 1.24.2. Toutes les fonctionnalités de Twig implémentées par la suite ne seront disponibles que lorsque Twig sera mis à jour dans une version future de phpBB.
Variables de langue
Depuis plusieurs années, phpBB prend en charge de multiples langues, elles sont traditionnellement retranscrites dans les templates en utilisant {L_FOO}. Si vous souhaitez utiliser la syntaxe native Twig, vous devez utiliser {{ lang('FOO') }} à la place.
Événements de template
Comme les variables de langue, les événements de template (events) peuvent également être utilisés dans la syntaxe native de Twig. L'événement suivant : <-- EVENT event_name --> équivaut à {% EVENT event_name %}.
Inclusion des templates dynamiques
De nombreux templates de phpBB incluent d'autres templates afin de conserver un code structuré. Ce n'est généralement pas un problème, à moins que le template à inclure ne soit attribué de manière dynamique (basé sur un paramètre de configuration phpBB ou un paramètre utilisateur).
Ces templates sont souvent inclus en utilisant la syntaxe suivante : <-- INCLUDE {FOO_TEMPLATE_FILE} -->. Twig utilise pratiquement la même construction (notez que vous pouvez inclure un template en utilisant la fonction ou la balise). En utilisant la syntaxe de balise, le code résultant serait {% include FOO_TEMPLATE_FILE %}.
Si vous souhaitez modifier le chemin d'accès du fichier inclus (peut-être en utilisant une extension .twig ou un chemin de fichier différent), vous pouvez modifier la règle d'inclusion sans devoir réécrire la variable de template. Cela peut se faire en construisant un tableau (array) et en le concaténant immédiatement.
Exemple : {% include ['includes/', FOO_TEMPLATE_FILE, '.twig']|join %}
Boucles
En raison de rétrocompatibilité, phpBB 3.1 implémente les boucles de template de façon peu conventionnelle. A cause de la manière dont les attributs de blocs sont attribués au template par la fonction assign_block_vars() (ils sont stockés dans des « boucles »), ils ne sont pas disponibles dans la « racine ». Prenez cet exemple simple d'une boucle de template :
- Code: Tout sélectionner
<-- BEGIN my_items --> {my_items.VALUE} <-- END my_items -->
En utilisant Twig, le code suivant devrait fonctionner.
- Code: Tout sélectionner
{% for item in loops.my_items %} {{ item.VALUE }} {% endfor %}
Note :
la mise en œuvre actuelle de boucles est provisoire, non documentée et soumise à changement. Mais vous pouvez l'utiliser si vous vous sentez à l'aise avec la syntaxe de Twig.
Conseils & Astuces
Utiliser les classes CSS de prosilver
La plupart des extensions sont développées principalement pour prosilver, elles utilisent naturellement les ressources de prosilver chaque fois que c'est possible. Cela peut réduire considérablement le nombre de règles CSS que les auteurs d'extensions doivent écrire.
Si un auteur d'extension souhaite ajouter un bloc de lignes avec du contenu, il peut écrire toutes les règles CSS lui-même, ou il peut simplement utiliser les règles déjà en place. Le résultat le plus probable est qu'il utilisera les règles CSS de prosilver, avec des sélecteurs comme, par exemple, ul.topiclist.
Si vous souhaitez augmenter les chances de compatibilité des extensions avec votre style, préférez l'utilisation des mêmes nom de classe CSS sur les mêmes éléments.
Utiliser la recompilation automatique du template (pendant le développement)
En apportant des modifications aux fichiers templates, il est pratique de pouvoir voir les modifications directement, sans avoir à purger systématiquement le cache de votre forum. Une petite astuce est de recompiler les templates automatiquement après chaque modification de fichier.
Allez dans : PCA > Général > Configuration du serveur > Paramètres de charge
Puis définissez à « Oui » le paramètre « Recompiler les différents éléments du style »
Utiliser des outils de comparaison de fichiers
Les utilisateurs oublient souvent les changements qu'ils ont apportés à certains styles. Ou ils ont des difficultés à voir les différences entre les différentes versions de fichiers.
C'est là que les outils de comparaison de fichiers sont utiles. Certains éditeurs de texte plus avancés disposent de fonctionnalités intégrées qui permettent de comparer des fichiers (ou des répertoires entiers). Alternativement, vous pouvez utiliser des applications autonomes. Deux des plus populaires et gratuites sont WinMerge et Meld.
Validation de code
L'écriture de code HTML et CSS valide augmentera considérablement vos chances pour que votre style fonctionne correctement avec différents navigateurs, sur différents systèmes d'exploitation et périphériques.
Un code HTML et CSS valide est également requis si vous souhaitez soumettre votre style dans notre base de données des styles, comme mentionné dans la Politique de soumission du style (en anglais).
Heureusement, il existe des outils automatisés qui vous aideront à identifier les problèmes. Nous vous suggérons d'utiliser Unicorn - W3C's Unified Validator.
Source : https://www.phpbb.com/styles/create/
Remerciements à skouat, Kewee, cabot, papicx et Jester pour les corrections.