2 - Création d'un thème PHPBoost 6

Introduction


Après avoir mis en place les fichiers de base de la structure d'un thème, on peut s'étonner de l'absence de fichier HTML ou de fichier css. En réalité ils sont présents dans un dossier commun pour une utilisation "automatique" et ne seront nécessaires dans un thème que s'ils sont amenés à être modifiés.

Dans le principe, on copie le ou les fichiers du dossier commun que l'on veut modifier puis on les colle dans le thème en respectant l’arborescence de ce dossier commun :



Ce principe de copié/collé/modification est appelé : surcharge

Héritage des fichiers


Structure HTML


Les fichiers tpl de la structure HTML du thème seront surchargés à la racine du thème avant d'être modifiés :




frame.tpl contient les limites de la structure HTML : le <head/>, l'appel du fichier @import.css, des fichiers javascript et l'appel de la structure html principale.
js_top.tpl contient la liste des fichiers javascript appelés en début de page.
js_bottom contient la liste des fichiers javascript appelés en fin de page.

body.tpl contient la structure HTML principale

maintain.tpl contient la structure HTML principale lorsque le site est placé en maintenance

L'administration


Il est possible de modifier l'aspect de l'administration en surchargeant les fichiers du dossier commun.
Comme précédemment, on fera attention à bien respecter l'arborescence des dossiers/fichiers.




Par exemple si on veut modifier la structure HTML principale des pages de l'administration on surchargera comme suit:




le framework


Certains contenus sont générés via le script php dans des fichiers tpl contenus dans le dossier :




Si l'on veut par exemple modifier l'aspect des menus de liens, on va surcharger le fichier



dans le thème




Les fichiers des modules


les modules "classiques"


Par défaut, les fichiers de templates des modules sont appelés dans le dossier 
templates
de leur répertoire respectif . Pour les personnaliser, il suffit de les surcharger dans le thème, dans un dossier au nom du module, lui-même placé dans un dossier 
modules
que l'on aura créé à la racine du thème.

Nous avons, dans la mesure du possible, harmonisé les noms de fichiers tpl des modules. Ainsi les fichiers 
{NomDuModule}SeveralItemsController.tpl
représentent les pages qui affichent plusieurs items (catégories, tag, items d'un membre, items en attente), alors que les fichiers 
{NomDuModule}ItemController.tpl
représentent les pages d'un item du module.

Par exemple pour modifier la page d'un item du module Téléchargement
On surcharge le fichier



dans le thème




Il en va de même pour le/les fichiers images, css et js du module.

Ainsi en suivant l'exemple, si on veut modifier la totalité des fichiers du module Téléchargement, le thème contiendra donc




Si le module contient des fichiers images et/ou js et qu'ils sont surchargés dans le thème, on n'oubliera pas de changer leur adresse dans les fichiers tpl(js) ou css.

Les modules "noyau"


Les modules noyau utilisent une nouvelle méthode de développement dans PHPBoost et sont gérés directement par le noyau du cms.
Sont concernés pour l'instant les modules :

Cette nouvelle structure des modules permet de centraliser l'affichage de tous les modules convertis en module noyau vers un seul fichier placé dans le dossier




où l'on retrouve 3 fichiers :


Personnalisation de tous les modules noyau


On souhaite modifier l'ensemble des modules noyau, auquel cas on surcharge ces fichiers dans le thème en respectant l'arborescence du dossier __default__




Personnalisation de chaque module noyau


On souhaite modifier chaque module noyau indépendamment, auquel cas on surcharge ces fichiers dans le thème en les plaçant dans chaque module et en les renommant au nom du module
Par exemple pour les modules Articles et Actualités, le fichier ModuleSeveralItemsController.tpl est surchargé 2 fois et chaque version est renommée avant d'être modifiée




Les fichiers CSS


Le framework CSS utilise un système d'import : tous les fichiers css nécessaires sont listés dans un fichier 
@import.css
. Les plus aguerris et les curieux trouveront nombre de sites qui déconseillent cette pratique notamment pour des problèmes de performances de cache.

Mais PHPBoost se démarque en n'utilisant pas "directement" le fichier.
En effet, lorsque le cache est activé, @import.css ne sert que de listing qui indique au script php où se trouvent les fichiers css utilisés afin de les compresser en un seul. Ainsi, la mise en cache est directe et assurée par php, et le framework ne nécessite pas de fichier css compressé.

En contrepartie, lors du développement d'un thème avec le cache désactivé, l'actualisation d'une modification devra se faire par un ctrl+F5 au lieu d'un simple F5.

Comme pour les fichiers tpl, l'ensemble des fichiers CSS nécessaires au framework sont regroupés dans un dossier commun :




Pour une modification en profondeur, on surchargera les fichiers CSS voulus dans le thème.
Par exemple, pour modifier l'agencement des cellules



en n'oubliant pas de modifier l'appel des fichiers dans le @import.css du thème
Code CSS : 
...
@import url('../../__default__/theme/cell.css') screen;
@import url('../../__default__/theme/cell_layout.css') screen;
...

devient
Code CSS : 
...
@import url('../../Nom_Du_Theme/theme/cell.css') screen;
@import url('../../Nom_Du_Theme/theme/cell_layout.css') screen;
...


De même, tout fichier CSS créé spécifiquement pour le thème devra être placé dans le dossier thème et être déclaré dans le fichier @import.css
@import url('../../Nom_Du_Theme/theme/fichier.css') screen;


Respecter l'écriture 
@import url('../../Nom_Du_Theme/theme/fichier.css') screen;
alors que 
@import url('fichier.css') screen;
peut fonctionner puisque le fichier.css est au même niveau que @import.css, permet de rendre éligible votre thème à la parentalité (cf l'article Modifier un thème).


L'administration


Le fichier @import.css et les fichiers css spécifiques à l'administration sont contenus dans le dossier




Avant de surcharger les fichiers css de l'administration, il faut d'abord surcharger le frame.tpl de l'administration et y modifier l'adresse d'appel du fichier @import.css



frame.tpl : 
        <!-- Theme CSS -->
    # IF C_CSS_CACHE_ENABLED #
        <link rel="stylesheet" href="${CSSCacheManager::get_css_path('/templates/__default__/dashboard/@import.css')}" type="text/css" media="screen, print" />
    # ELSE #
        <link rel="stylesheet" href="{PATH_TO_ROOT}/templates/__default__/dashboard/@import.css" type="text/css" media="screen, print" />
    # ENDIF #


devient
frame.tpl : 
<!-- Theme CSS -->
    # IF C_CSS_CACHE_ENABLED #
        <link rel="stylesheet" href="${CSSCacheManager::get_css_path('/templates/Nom_Du_Theme/dashboard/@import.css')}" type="text/css" media="screen, print" />
    # ELSE #
        <link rel="stylesheet" href="{PATH_TO_ROOT}/templates/Nom_Du_Theme/dashboard/@import.css" type="text/css" media="screen, print" />
    # ENDIF #


Les fichiers javascript


La notion de parentalité (cf l'article Modifier un thème) impose de déclarer l'adresse des fichiers js avec le nom du dossier du thème contrairement aux versions précédentes où le thème était défini par la variable de template {THEME}. Cette variable fonctionne toujours, mais le fichier ne serait pas pris en compte dans un thème enfant.
Code HTML : 
// PHPBoost version < 6
<script src="{PATH_TO_ROOT}/templates/{THEME}/chemin/vers/fichier.js"></script>
//PHPBoost version > 6
<script src="{PATH_TO_ROOT}/templates/Nom_Du_Theme/chemin/vers/fichier# IF C_CSS_CACHE_ENABLED #.min# ENDIF #.js"></script>


Pour améliorer les performances, la variable C_CSS_CACHE_ENABLED a été portée dans tout le framework, ce qui permet d'utiliser la version non compressée du fichier js pendant le développement du script et la version compressée en production.
Code HTML : 
# IF C_CSS_CACHE_ENABLED #
    <script src="{PATH_TO_ROOT}/templates/Nom_Du_Theme/chemin/vers/fichier.min.js"></script>
# ELSE #
    <script src="{PATH_TO_ROOT}/templates/Nom_Du_Theme/chemin/vers/fichier.js"></script>
# ENDIF #
que l'on peut aussi déclarer 
<script src="{PATH_TO_ROOT}/templates/Nom_Du_Theme/chemin/vers/fichier# IF C_CSS_CACHE_ENABLED #.min# ENDIF #.js"></script>


Les images


Certaines images ont été définies par défaut :


Elles sont déclarées dans le dossier




il suffit donc de les surcharger dans le thème en conservant le même nom




À noter que pour pousser plus loin la personnalisation, il est possible de déclarer les images 
default_category.webp
et 
default_item.webp
indépendamment pour chaque module :




Tous les modules qui utilisent les miniatures sont personnalisables, indépendamment de leur structure "classique" ou "noyau".

L'extension webp est utilisée pour la quasi-totalité des images déclarées dans le cms, pour la légèreté des fichiers et la gestion de la transparence. Seules ces 4 images "défaut" devront être déclarées avec cette extension. Si votre éditeur d'image ne la gère pas ou si vous n'en utilisez pas, il existe des convertisseurs gratuits en ligne qui vous permettront de convertir vos images.
Un parmi tant d'autre : Convertio

Les langues


Il est possible, en version 6, d'ajouter des variables de langue dans un thème ce qui permet de rajouter du texte dans un fichier tpl tout en conservant la fonctionnalité multi langage.

Tous les fichiers de langage du dossier /lang sont portés dans le framework, ainsi que ceux d'un module.
Une variable de langue du dossier /lang est utilisable dans tout fichier tpl, alors qu'une variable de langue d'un module ne sera utilisable que dans les fichiers tpl du module. Ainsi, on n'est plus obligé de déclarer le dossier et le fichier dans lesquels se trouve la variable.

Donc si une variable existe déjà, elle peut être ajoutée dans un tpl du thème : 
{@nom.de.la.variable}
ou si elle contient du html 
{@H|nom.de.la.variable}.


Si une variable n'existe pas, il est possible de créer un fichier de langue dans le dossier /lang ou dans le thème pour pouvoir l'utiliser. Le fichier et la variable seront automatiquement pris en compte.

La liste des variables existantes se trouve dans le module Bac à sable (sandbox) doté d'un outil de recherche.

Ajouter un fichier de langue dans le thème





file.php : 
<?php
$lang['first.var'] = 'Un premier texte';
$lang['other.var'] = 'Un autre texte';
$lang['var.with.quote'] = 'Attention à l\'apostrophe';
?>


Si le nom du fichier et le nom des variables importent peu, le langage php est très strict. On fera donc attention à bien finir une déclaration de variable par un 
;
ainsi qu'au backslash 
\
avant une apostrophe.

Pour des raisons pratiques, les mots des variables sont séparés par des points (à quelques exceptions près) ce qui permet une recherche rapide dans un éditeur. Chaque variable commence par le nom du fichier qui la contient ce qui permet de savoir rapidement dans quel fichier la retrouver.
ex: {@download.add.item} est une variable issue du fichier common.php du module Téléchargement.

Les variables de template


Dans les fichiers tpl, les variables de template {VARIABLE} ou # IF C_VARIABLE_EXISTS # ... # ENDIF # sont la transcription html du script php, ce qui permet de récupérer le contenu dynamique (le titre d'un item, son contenu, sa miniature, etc).
Elles sont en majeure partie issues des modules qui les contiennent.

Il existe des variables communes utilisables dans tout fichier tpl

Les variables de condition


Elles définissent un état et peuvent être utilisées comme suit:
# IF C_VARIABLE_EXISTS #// code HTML# ENDIF #

# IF C_VARIABLE_EXISTS #// code HTML # ELSE #// autre code HTML# ENDIF #


on peut aussi imbriquer 2 conditions ou plus
# IF C_VARIABLE_EXISTS #// code HTML # ELSE ## IF C_VARIABLE_EXISTS #// autre code HTML# ENDIF ## ENDIF #

On fera attention à bien mettre un espace après un 
#
de début et avant un 
#
de fin

Les variables communes
Variable Fonction
C_CSS_CACHE_ENABLED Vérifie si le cache css est activé
IS_USER_CONNECTED Vérifie si l'utilisateur est connecté
IS_MODERATOR Vérifie si l'utilisateur est un modérateur
IS_ADMIN Vérifie si l'utilisateur est un administrateur
IS_MOBILE_DEVICE Vérifie si l'utilisateur utilise un appareil mobile
Emplacements des menus
C_HAS_TOP_HEADER_MENUS Vérifie si l'emplacement "sur-entête" est activé
C_HAS_HEADER_MENUS Vérifie si l'emplacement "Tête de page" est activé
C_HAS_SUB_HEADER_MENUS Vérifie si l'emplacement "sous-entête" est activé
C_HAS_SOME_HEADER_MENUS Vérifie si au moins un des emplacements d'entête est activé
C_HAS_ALL_HEADER_MENUS Vérifie si tous les emplacements d'entête sont activés
C_HAS_LEFT_MENUS Vérifie si l'emplacement "Menu gauche" est activé
C_HAS_RIGHT_HEADER_MENUS Vérifie si l'emplacement "Menu droite" est activé
C_HAS_SOME_VERTICAL_MENUS Vérifie si au moins un des emplacements verticaux est activé
C_HAS_ALL_VERTICAL_MENUS Vérifie si tous les emplacements verticaux sont activés
C_HAS_TOP_CENTRAL_MENUS Vérifie si l'emplacement "Menu central haut" est activé
C_HAS_BOTTOM_CENTRAL_HEADER_MENUS Vérifie si l'emplacement "Menu central bas" est activé
C_HAS_SOME_CENTRAL_MENUS Vérifie si au moins un des emplacements centraux est activé
C_HAS_ALL_CENTRAL_MENUS Vérifie si tous les emplacements centraux sont activés
C_HAS_TOP_FOOTER_MENUS Vérifie si l'emplacement "Sur-peid de page" est activé
C_HAS_FOOTER_MENUS Vérifie si l'emplacement "Pied de page" est activé


Les variables de contenu


Une variable de template représente du contenu généré par le script php et s'utilise avec des 
{}

<h1>{TITRE}</h1>

<div>{CONTENT}</div>

<a href="{PATH_TO_ROOT}/chemin/vers/un/fichier">Nom du fichier</a>


Les variables communes
Variable Utilisation
THEME Le nom du thème utilisé
PARENT_THEME Le nom du thème parent du thème utilisé par le visiteur
LANG Le langage utilisé par le visiteur
TOKEN Le cookie de session de l'utilisateur
REWRITED_SCRIPT L'adresse complète de la page en cours
U_SITE Url du site (ex: https://monsite.fr)
PATH_TO_ROOT Le chemin complet de la racine du site après l'adresse du site, avec le dossier du module
ex: https://monsite.ext
/sous/dossier/phpboost/Nom_du_module
TPL_PATH_TO_ROOT Le chemin complet de la racine du site après l'adresse du site, sans le dossier du module
ex: https://monsite.ext
/sous/dossier/phpboost/


les variables de date


Le formatage des dates peut être modifié en changeant la variable déclarée par cette variable suivie d'un suffixe. ex: {DATE} peut être modifié en {DATE_SHORT_TEXT}
La plupart des dates sont déclarées sous la forme {DATE}, mais on peut les trouver sous un autre nom : {UPDATE_DATE} ou préfixées lorsque la variable est dans une boucle : {boucle.DATE} ou encore déjà affublées d'un suffixe : {DATE_SHORT}.
On prendra soin de ne modifier que le suffixe.

suffixe affichage
aucun 11/04/2022
_TIMESTAMP 1649688660
(= Nombre de secondes entre la date et le 1er janvier 1970)
_SHORT 11/04/2022
_SHORT_TEXT Lundi 11 Avril 2022
_SHORT_MONTH_TEXT 11 Avril 2022
_FULL 11/04/2022 à 16h51
_DAY 11
_DAY_TEXT Lun
_DAY_FULLTEXT Lundi
_DAY_MONTH 11/04
_DAY_MONTH_TEXT 11 Avr
_WEEK 15 (= N° de la semaine dans l'année civile)
_MONTH 04
_MONTH_TEXT Avr
_MONTH_FULLTEXT Avril
_YEAR 2022
_HOUR 16
_MINUTE 51
_SECONDS 00
_ISO8601 2022-04-11T16:51:00+02:00
_AGO Il y a 3 minutes / Il y a 3 jours / Il y a 3 mois / Il y a 3 ans
(= temps qui sépare la lecture de la publication)
_SINCE Depuis 3 minutes / Depuis 3 jours / Depuis 3 mois / Depuis 3 ans
(= temps qui sépare la lecture de la publication)
_DELAY 11 Avr
_RELATIVE 3 minutes / 3 jours / 3 mois / 3 ans
(= temps qui sépare la lecture de la publication)