Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 02

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, e contents/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() fa strpos($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 -l

Falso 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 stampaDove 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 scriptlo stesso codice nell'attributo (data-err-…="{_svc_…}"): il testo non deve contenere "
un messaggio di Auth o di un widget dell'accountAuth::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:

AppletRuolo
applets/headerlogo, navigazione, [LANGUAGE_SWITCHER]
applets/footerlink legali, copyright
applets/homepagehero + feature della home di default
applets/meta-custom-pagetitle/description/social per pagina, gestiti da backend
applets/servicesnon è 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

TabellaRuolo
layouti blocchi disponibili
layout_pathquale blocco su quale percorso, con visible come interruttore
layout_locationla 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() in library/gallery/system/set_js.php
  • CSS — system_set_css_level() in library/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 è:

CosaDove
controller di paginacontents/<nome>.php
template della paginathemes/<tema>/contents/<nome>/index.html
JS della paginathemes/<tema>/javascript/<nome>.js — caricato da solo
CSS della paginathemes/<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

TemaUso
themes/sitefrontend pubblico
themes/gallerybackend /restricted (Foundation)
themes/adminskin degli interventi sul backend (css/ff-skin.css)
themes/responsivewidget del forms framework (ff/)
themes/vgnextnuova area di gestione contenuti
themes/libraryvendor 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.