Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 02

Pages, templates et applets

Comment se construit le HTML : où va un contrôleur de page, comment fonctionne le moteur de templates, ce qu'est un applet et comment on accroche CSS et JS.

1. Une page est un fichier

Créer contents/<nom>.php suffit pour que /<nom> existe. Aucun enregistrement, aucune ligne en base, aucune entrée de routage : la règle BOTTOM de cm/conf/routing_table.xml ((.*) → /contents$0) s'en charge.

Anatomie canonique :

<?php
use_cache(false);                      // page dynamique : jamais depuis le cache de page
$db = ffDB_Sql::factory();

$filename = FF_DISK_PATH . "/themes/site/contents/elenco/index.html";
$tpl = ffTemplate::factory(ffCommon_dirname($filename));
$tpl->load_file(basename($filename), "main");

// ... requêtes, set_var, parse des blocs ...

$cm->oPage->addContent($tpl->rpparse("main", false));
  • $cm->oPage->addContent() insère le HTML dans le layout (header, footer et blocs viennent du layout configuré côté CMS, pas du fichier de page) ;
  • une page qui doit sortir hors du layout (page légale autonome, aperçu, export) imprime directement et fait exit ;
  • les sous-dossiers fonctionnent : contents/area/section.php → /area/section, et contents/area/index.php → /area. Le reste de chemin arrive dans $cm->real_path_info (voir 01 §4).

Exemples dans le dépôt : contents/md/index.php (version Markdown des contenus), contents/i18n.php (table des slugs par langue), contents/restricted/, contents/emailpreviewer/.

2. ffTemplate : le moteur de templates

Deux constructions, et rien d'autre.

2.1 Les placeholders {nom}

$tpl->set_var("titolo", "Bonjour");     // {titolo} dans le fichier HTML

Un placeholder sans valeur reste brut sur la page : {titolo} visible à l'écran est le symptôme typique d'un bloc non parsé ou d'un fichier chargé sous un mauvais nom.

2.2 Les blocs <!--BeginNom--> … <!--EndNom-->

<ul>
<!--BeginRiga-->
    <li><a href="{url}">{etichetta}</a></li>
<!--EndRiga-->
</ul>
while ($db->nextRecord()) {
    $tpl->set_var("url", ...);
    $tpl->set_var("etichetta", ...);
    $tpl->parse("SectRiga", true);     // true = ajoute (boucle) ; false = remplace
}

⚠️ Les marqueurs NE sont PAS des commentaires HTML

<!--BeginRiga--> ressemble à un commentaire mais c'est une directive du moteur de templates. ffTemplate::getBlock() fait strpos($sTemplate, "<!--Begin" . $sName . "-->") : une comparaison de chaîne littérale, sans aucune tolérance aux espaces.

Donc, dans tout reformatage ou nettoyage de masse :

  • ne les supprimez pas ;
  • n'ajoutez pas d'espaces : <!-- BeginRiga --> est cassé ;
  • ne reformatez pas les commentaires qui les entourent de façon à les englober ;
  • ne les réordonnez pas et ne les déplacez pas : Begin/End délimitent un bloc et doivent rester appariés et imbriqués comme avant.

Si un marqueur saute, getBlock() renvoie une chaîne vide, replaceBlock() laisse le template intact et les {placeholders} restent bruts. Si le marqueur est dans une coque (guscio.html, guscio-pubblico.html), CSS, JS et menus de toutes les pages sautent. Ce n'est pas une erreur que le lint voit : le PHP compile, le HTML est valide, on ne le découvre que dans le navigateur.

Vérification après une modification de masse des templates (doit afficher 0) :

grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \
     --include='*.html' --include='*.php' . | grep -v '/docs/' | wc -l

Faux positif connu : themes/library/plugins/jquery.dynatree/doc/, où ce sont de vrais commentaires.

2.3 Traductions : {_word_code}

Un placeholder qui commence par _ est résolu par ffTranslator contre la table ff_international (jointure sur ff_languages, repli sur ITA). C'est le moteur du multilingue : un template, N langues.

<h1>{_home_title}</h1>

Le dictionnaire se gère depuis le backend dans /restricted/international. Voir 08 — Auth, utilisateurs et permissions pour l'accès et la section multilingue de PANORAMICA_JOECMS.md pour la stratégie d'ensemble (dictionnaire pour l'interface, un fichier par langue pour les pages légales, où la prose longue avec des données interpolées rendrait le dictionnaire fragile).

Un texte que voit le visiteur ne s'écrit jamais dans une seule langue. Où il va, selon ce qui l'affiche :

Ce qui l'afficheOù se trouve le texte
un template (.html passé par ffTemplate, emails compris)un code {_svc_…} du dictionnaire, dans les quatre langues de l'installeur
un attribut du template lu par un scriptle même code dans l'attribut (data-err-…="{_svc_…}") : le texte ne doit pas contenir "
un message de Auth ou d'un widget du compteAuth::text() (vendor/wolfgan/auth/Auth.php), voir 08 §1
un script qui écrit lui-même (fenêtres, libellés)une table par langue dans le script, choisie d'après <html lang> (themes/site/javascript/root.js)
une page qui tourne sans base de données (erreur, maintenance)les tables de cm/errori.php, voir 13 §1bis

Un nouveau code va dans database.sql et dans une migration, qui remplit les entrées de substitution au lieu d'insérer avec des ID fixes (migrations/README.md). Que le code existe dans les quatre langues se vérifie sur le dump : un code manquant sort dans la page tel quel (FF_TRANSLATOR_HIDE_CODE), et avec une langue par défaut autre que l'italien il n'y a même pas le repli sur l'italien.

2.4 La classe en double

⚠️ L'autoloader résout ffTemplate sur vendor/phpformsframework/ffTemplate.php, pas sur ff/classes/ffTemplate.php : il existe deux copies de la même classe. La copie chargée émet un Warning: Undefined variable $res à chaque parse(). Dans le flux web display_errors = 0 le cache, mais il finit dans les logs — et en ligne de commande on le voit. C'est un défaut préexistant du framework, pas le symptôme d'un problème du projet.

3. Applets : blocs réutilisables

Un applet est un dossier applets/<nom>/ avec index.php (logique) et template.html (vue). Le contrat est unique : la sortie va dans $out_buffer.

<?php
// applets/header/index.php
$filename = FF_DISK_PATH . "/applets/header/template.html";
$tpl = ffTemplate::factory(ffCommon_dirname($filename));
$tpl->load_file(basename($filename), "main");

$arrPath = explode("/", trim($cm->path_info, "/"));   // le contexte de la page est disponible

$out_buffer = $tpl->rpparse("main", false);

Applets présents dans le dépôt :

AppletRôle
applets/headerlogo, navigation, [LANGUAGE_SWITCHER]
applets/footerliens légaux, copyright
applets/homepagehero + fonctionnalités de l'accueil par défaut
applets/meta-custom-pagetitle/description/social par page, gérés depuis le backend
applets/servicesce n'est pas un applet de layout : c'est le dossier des endpoints HTTP, voir 03

Les applets sont câblés dans le seed et activés/désactivés par l'assistant ou par layout_path.visible (header = ID 2, footer = ID 3).

4. Layout : comment les blocs arrivent sur la page

TableRôle
layoutles blocs disponibles
layout_pathquel bloc sur quel chemin, avec visible comme interrupteur
layout_locationla position dans la coque (header, colonne, footer…)

Le layout se gère depuis /restricted/block et /restricted/themes. Un projet qui ne veut pas du layout du CMS sur une page donnée imprime directement et fait exit (§1).

5. CSS et JS : ce qui est automatique et ce qui ne l'est pas

Deux fonctions système décident des ressources :

  • JS — system_set_js_level() dans library/gallery/system/set_js.php
  • CSS — system_set_css_level() dans library/gallery/system/set_css.php

Le mécanisme fonctionne par convention de nommage : un fichier qui correspond au chemin de la page est chargé tout seul. Dans les projets de l'écosystème la convention adoptée est :

QuoiOù
contrôleur de pagecontents/<nom>.php
template de la pagethemes/<thème>/contents/<nom>/index.html
JS de la pagethemes/<thème>/javascript/<nom>.js — chargé tout seul
CSS de la pagethemes/<thème>/css/<nom>.css — chargé tout seul

Pour ajouter une ressource à la main on utilise $cm->oPage->addJs(...) / addCss(...) depuis le contrôleur.

⚠️ Dans les endpoints JSON (/srv) le bus système vide $cm->oPage->page_js et page_css et journalise ceux trouvés dans request_error_js / request_error_css : s'il y en a, quelque chose a essayé de décorer une réponse qui n'est pas une page.

Front-end JoeCMS : SCSS modulaire

Le CSS du thème site est écrit en SCSS modulaire dans themes/site/css/root/ (_color, _sizes, _font, _typography, _base, _components) et compilé dans root.css ; les tokens de marque sont dans themes/site/css/joecms-brand.css. Un nouveau projet change palette et typographie en touchant deux partials, pas un CSS monolithique.

6. Thèmes présents

ThèmeUsage
themes/sitefront-end public
themes/gallerybackend /restricted (Foundation)
themes/adminskin des interventions sur le backend (css/ff-skin.css)
themes/responsivewidgets du forms framework (ff/)
themes/vgnextnouvel espace de gestion des contenus
themes/libraryvendors JS/CSS

Config d'environnement du thème : themes/site/conf/config.local.php (développement) et config.remote.php (production, écrit par l'installeur avec chmod 0640). C'est HTTP_HOST qui décide lequel des deux est chargé — un détail qui compte beaucoup en ligne de commande, voir 13 — Observabilité et CLI.