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 seulement 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 lien, 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, s'il 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 manière de développement dans PHPBoost et sont gérés directement par le noyau du cms.
Sont concernés pour l'instant les modules :

• Articles
• Actualités
• Pages
• Sondages
  

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 :

• ModuleItemController.tpl

  : gère l'affichage de la page d'un item du module

• ModuleMessagesController.tpl

  : gère l'affichage d'une page de type messages (fonctionnalité à venir, non utilisée en version 6.0.0)

• ModuleSeveralItemsController.tpl

  : gère l'affichage d'une page avec plusieurs items du module (catégorie, tags, etc)
  

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 contre partie, 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 theme.
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

devient


De même que tout fichier CSS créé spécifiquement pour le thème devra être placé dans le dossier theme 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



devient

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.


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.

Les images

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

• no_avatar.webp

  : l'avatar commun lorsqu'un utilisateur choisi de ne pas de personnaliser le sien

• default_category.webp

  : la miniature par défaut des catégories

• default_item.webp

  : la miniature par défaut des items

• error.webp

  : l'image commune aux pages 403 et 404
  

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 parmis 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à, une variable de langue 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 avec un outil de recherche se trouve dans le module Bac à sable (sandbox).

Ajouter un fichier de langue dans le thème





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, et chaque variable commence par le nom du fichier qui la contient ce qui permet de savoir rapidement à quel fichier elle appartient.
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 majeur 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
PARENT_THEME	Le nom du thème parent du thème utilisé par le visiteur
LANG	Le langage 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)