Pagine, template e applet
Come si costruisce l'HTML: dove va un controller di pagina, come funziona il template engine, cos'è un applet e come si aggancia CSS e JS.
1. Una pagina è un file
Creare contents/<nome>.php è sufficiente perché /<nome> esista. Nessuna registrazione, nessuna riga di database, nessuna voce di routing: ci pensa la regola BOTTOM di cm/conf/routing_table.xml ((.*) → /contents$0).
Anatomia canonica:
<?php
use_cache(false); // pagina dinamica: mai dalla cache di pagina
$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");
// ... query, set_var, parse dei blocchi ...
$cm->oPage->addContent($tpl->rpparse("main", false));
$cm->oPage->addContent()inserisce l'HTML nel layout (header, footer e blocchi arrivano dal layout configurato lato CMS, non dal file di pagina);- una pagina che deve uscire fuori dal layout (pagina legale self-contained, anteprima, export) stampa direttamente e fa
exit; - le sottocartelle funzionano:
contents/area/sezione.php→/area/sezione, econtents/area/index.php→/area. Il residuo di percorso arriva in$cm->real_path_info(vedi 01 §4).
Esempi nel repo: contents/md/index.php (versione Markdown dei contenuti), contents/i18n.php (mappa degli slug per lingua), contents/restricted/, contents/emailpreviewer/.
2. ffTemplate: il motore dei template
Due costrutti, e nient'altro.
2.1 I placeholder {nome}
$tpl->set_var("titolo", "Ciao"); // {titolo} nel file HTML
Un placeholder non valorizzato resta crudo nella pagina: {titolo} visibile a video è il sintomo tipico di un blocco non parsato o di un file caricato con il nome sbagliato.
2.2 I blocchi <!--BeginNome--> … <!--EndNome-->
<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 = append (ciclo); false = sostituisci
}
⚠️ I marker NON sono commenti HTML
<!--BeginRiga-->sembra un commento ma è una direttiva del template engine.ffTemplate::getBlock()fastrpos($sTemplate, "<!--Begin" . $sName . "-->"): un confronto su stringa letterale, senza alcuna tolleranza per gli spazi.Quindi, in qualunque riformattazione o pulizia di massa:
- non rimuoverli;
- non aggiungere spazi:
<!-- BeginRiga -->è rotto;- non riformattare i commenti che li circondano in modo da inglobarli;
- non riordinarli né spostarli: Begin/End delimitano un blocco e devono restare appaiati e annidati come prima.
Se il marker salta,
getBlock()torna stringa vuota,replaceBlock()lascia il template intatto e i{placeholder}restano crudi. Se il marker sta in un guscio (guscio.html,guscio-pubblico.html), saltano CSS, JS e menu di tutte le pagine. Non è un errore che si vede in lint: il PHP compila, l'HTML è valido, si scopre solo dal browser.Verifica dopo una modifica di massa ai template (deve stampare
0):grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \ --include='*.html' --include='*.php' . | grep -v '/docs/' | wc -lFalso positivo noto:
themes/library/plugins/jquery.dynatree/doc/, dove sono commenti veri.
2.3 Traduzioni: {_word_code}
Un placeholder che inizia con _ è risolto da ffTranslator contro la tabella ff_international (join su ff_languages, fallback a ITA). È il motore del multilingua: un template, N lingue.
<h1>{_home_title}</h1>
Il dizionario si gestisce da backend in /restricted/international. Vedi 08 — Auth, utenti e permessi per l'accesso e la sezione multilingua di PANORAMICA_JOECMS.md per la strategia complessiva (dizionario per l'interfaccia, file per lingua per le pagine legali, dove la prosa lunga con dati interpolati renderebbe il dizionario fragile).
Un testo che vede il visitatore non si scrive in una lingua sola. Dove va, secondo chi lo stampa:
| Chi lo stampa | Dove sta il testo |
|---|---|
un template (.html passato da ffTemplate, email comprese) | codice {_svc_…} del dizionario, nelle quattro lingue dell'installer |
| un attributo del template letto da uno script | lo stesso codice nell'attributo (data-err-…="{_svc_…}"): il testo non deve contenere " |
un messaggio di Auth o di un widget dell'account | Auth::text() (vendor/wolfgan/auth/Auth.php), vedi 08 §1 |
| uno script che scrive da sé (popup, etichette) | una tabella per lingua nello script, scelta da <html lang> (themes/site/javascript/root.js) |
| una pagina che gira senza database (errore, manutenzione) | le tabelle di cm/errori.php, vedi 13 §1bis |
Un codice nuovo va in database.sql e in una migrazione, che riempie i segnaposto invece di inserire con ID fissi (migrations/README.md). Il controllo che il codice esista in tutte e quattro le lingue si fa sul dump: un codice mancante esce in pagina così com'è (FF_TRANSLATOR_HIDE_CODE), e con una lingua predefinita diversa dall'italiano non c'è nemmeno il ripiego sull'italiano.
2.4 Il doppione della classe
⚠️ L'autoloader risolve ffTemplate su vendor/phpformsframework/ffTemplate.php, non su ff/classes/ffTemplate.php: esistono due copie della stessa classe. La copia caricata emette un Warning: Undefined variable $res a ogni parse(). Nel flusso web display_errors = 0 lo nasconde, ma finisce nei log — e da riga di comando si vede. È un difetto preesistente del framework, non un sintomo di un problema del progetto.
3. Applet: blocchi riutilizzabili
Un applet è una cartella applets/<nome>/ con index.php (logica) e template.html (vista). Il contratto è uno solo: l'output va messo in $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, "/")); // il contesto della pagina è disponibile
$out_buffer = $tpl->rpparse("main", false);
Applet presenti nel repo:
| Applet | Ruolo |
|---|---|
applets/header | logo, navigazione, [LANGUAGE_SWITCHER] |
applets/footer | link legali, copyright |
applets/homepage | hero + feature della home di default |
applets/meta-custom-page | title/description/social per pagina, gestiti da backend |
applets/services | non è un applet di layout: è la cartella degli endpoint HTTP, vedi 03 |
Gli applet sono cablati nel seed e accesi/spenti dal wizard o da layout_path.visible (header = ID 2, footer = ID 3).
4. Layout: come i blocchi finiscono nella pagina
| Tabella | Ruolo |
|---|---|
layout | i blocchi disponibili |
layout_path | quale blocco su quale percorso, con visible come interruttore |
layout_location | la posizione nel guscio (header, colonna, footer…) |
Il layout si gestisce da /restricted/block e /restricted/themes. Un progetto che non vuole il layout del CMS su una certa pagina stampa direttamente e fa exit (§1).
5. CSS e JS: cosa è automatico e cosa no
Due funzioni di sistema decidono gli asset:
- JS —
system_set_js_level()inlibrary/gallery/system/set_js.php - CSS —
system_set_css_level()inlibrary/gallery/system/set_css.php
Il meccanismo è per convenzione di nome: un file che corrisponde al percorso della pagina viene caricato da solo. Nei progetti dell'ecosistema la convenzione adottata è:
| Cosa | Dove |
|---|---|
| controller di pagina | contents/<nome>.php |
| template della pagina | themes/<tema>/contents/<nome>/index.html |
| JS della pagina | themes/<tema>/javascript/<nome>.js — caricato da solo |
| CSS della pagina | themes/<tema>/css/<nome>.css — caricato da solo |
Per aggiungere un asset a mano si usa $cm->oPage->addJs(...) / addCss(...) dal controller.
⚠️ Negli endpoint JSON (/srv) il bus di sistema azzera $cm->oPage->page_js e page_css e logga quelli trovati in request_error_js / request_error_css: se ce ne sono, qualcosa ha provato a decorare una risposta che non è una pagina.
Frontend JoeCMS: SCSS modulare
Il CSS del tema site è scritto come SCSS modulare in themes/site/css/root/ (_color, _sizes, _font, _typography, _base, _components) e compilato in root.css; i token di marca stanno in themes/site/css/joecms-brand.css. Un progetto nuovo cambia palette e tipografia toccando due partial, non un CSS monolitico.
6. Temi presenti
| Tema | Uso |
|---|---|
themes/site | frontend pubblico |
themes/gallery | backend /restricted (Foundation) |
themes/admin | skin degli interventi sul backend (css/ff-skin.css) |
themes/responsive | widget del forms framework (ff/) |
themes/vgnext | nuova area di gestione contenuti |
themes/library | vendor JS/CSS |
Config d'ambiente del tema: themes/site/conf/config.local.php (sviluppo) e config.remote.php (produzione, scritto dall'installer con chmod 0640). È HTTP_HOST a decidere quale dei due viene caricato — dettaglio che conta parecchio da riga di comando, vedi 13 — Osservabilità e CLI.