Páginas, plantillas y applets
Cómo se construye el HTML: dónde va un controlador de página, cómo funciona el motor de plantillas, qué es un applet y cómo se enganchan CSS y JS.
1. Una página es un archivo
Crear contents/<nombre>.php basta para que /<nombre> exista. Ningún registro, ninguna fila de base de datos, ninguna entrada de enrutamiento: de eso se encarga la regla BOTTOM de cm/conf/routing_table.xml ((.*) → /contents$0).
Anatomía canónica:
<?php
use_cache(false); // página dinámica: nunca desde la caché de página
$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");
// ... queries, set_var, parse de los bloques ...
$cm->oPage->addContent($tpl->rpparse("main", false));
$cm->oPage->addContent()inserta el HTML en el layout (header, footer y bloques llegan del layout configurado en el CMS, no del archivo de página);- una página que debe salir fuera del layout (página legal autónoma, vista previa, exportación) imprime directamente y hace
exit; - las subcarpetas funcionan:
contents/area/seccion.php→/area/seccion, ycontents/area/index.php→/area. El residuo de ruta llega en$cm->real_path_info(ver 01 §4).
Ejemplos en el repo: contents/md/index.php (versión Markdown de los contenidos), contents/i18n.php (mapa de los slugs por idioma), contents/restricted/, contents/emailpreviewer/.
2. ffTemplate: el motor de plantillas
Dos construcciones, y nada más.
2.1 Los placeholders {nombre}
$tpl->set_var("titolo", "Hola"); // {titolo} en el archivo HTML
Un placeholder sin valor queda crudo en la página: {titolo} visible en pantalla es el síntoma típico de un bloque no parseado o de un archivo cargado con el nombre equivocado.
2.2 Los bloques <!--BeginNombre--> … <!--EndNombre-->
<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 = añade (bucle); false = sustituye
}
⚠️ Los marcadores NO son comentarios HTML
<!--BeginRiga-->parece un comentario pero es una directiva del motor de plantillas.ffTemplate::getBlock()hacestrpos($sTemplate, "<!--Begin" . $sName . "-->"): una comparación de cadena literal, sin ninguna tolerancia a los espacios.Por tanto, en cualquier reformateo o limpieza masiva:
- no los elimines;
- no añadas espacios:
<!-- BeginRiga -->está roto;- no reformatees los comentarios que los rodean de forma que los engloben;
- no los reordenes ni los muevas: Begin/End delimitan un bloque y deben seguir emparejados y anidados como antes.
Si el marcador se rompe,
getBlock()devuelve una cadena vacía,replaceBlock()deja la plantilla intacta y los{placeholders}quedan crudos. Si el marcador está en una estructura (guscio.html,guscio-pubblico.html), se rompen CSS, JS y menús de todas las páginas. No es un error que se vea en el lint: el PHP compila, el HTML es válido, solo se descubre desde el navegador.Verificación tras una modificación masiva de las plantillas (debe imprimir
0):grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \ --include='*.html' --include='*.php' . | grep -v '/docs/' | wc -lFalso positivo conocido:
themes/library/plugins/jquery.dynatree/doc/, donde son comentarios de verdad.
2.3 Traducciones: {_word_code}
Un placeholder que empieza por _ lo resuelve ffTranslator contra la tabla ff_international (join con ff_languages, fallback a ITA). Es el motor del multilingüe: una plantilla, N idiomas.
<h1>{_home_title}</h1>
El diccionario se gestiona desde el backend en /restricted/international. Ver 08 — Auth, usuarios y permisos para el acceso y la sección multilingüe de PANORAMICA_JOECMS.md para la estrategia global (diccionario para la interfaz, archivo por idioma para las páginas legales, donde la prosa larga con datos interpolados haría frágil el diccionario).
Un texto que ve el visitante nunca se escribe en un solo idioma. Dónde va, según qué lo imprime:
| Qué lo imprime | Dónde está el texto |
|---|---|
una plantilla (.html pasado por ffTemplate, emails incluidos) | un código {_svc_…} del diccionario, en los cuatro idiomas del instalador |
| un atributo de la plantilla leído por un script | el mismo código en el atributo (data-err-…="{_svc_…}"): el texto no debe contener " |
un mensaje de Auth o de un widget de la cuenta | Auth::text() (vendor/wolfgan/auth/Auth.php), ver 08 §1 |
| un script que escribe por su cuenta (ventanas emergentes, etiquetas) | una tabla por idioma en el script, elegida según <html lang> (themes/site/javascript/root.js) |
| una página que funciona sin base de datos (error, mantenimiento) | las tablas de cm/errori.php, ver 13 §1bis |
Un código nuevo va en database.sql y en una migración, que rellena los marcadores de posición en lugar de insertar con ID fijos (migrations/README.md). Que el código exista en los cuatro idiomas se comprueba sobre el dump: un código que falta sale en la página tal cual (FF_TRANSLATOR_HIDE_CODE), y con un idioma predeterminado distinto del italiano ni siquiera queda el respaldo en italiano.
2.4 La clase duplicada
⚠️ El autoloader resuelve ffTemplate en vendor/phpformsframework/ffTemplate.php, no en ff/classes/ffTemplate.php: existen dos copias de la misma clase. La copia cargada emite un Warning: Undefined variable $res en cada parse(). En el flujo web display_errors = 0 lo oculta, pero acaba en los logs — y desde línea de comandos se ve. Es un defecto preexistente del framework, no el síntoma de un problema del proyecto.
3. Applets: bloques reutilizables
Un applet es una carpeta applets/<nombre>/ con index.php (lógica) y template.html (vista). El contrato es uno solo: la salida va en $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, "/")); // el contexto de la página está disponible
$out_buffer = $tpl->rpparse("main", false);
Applets presentes en el repo:
| Applet | Función |
|---|---|
applets/header | logo, navegación, [LANGUAGE_SWITCHER] |
applets/footer | enlaces legales, copyright |
applets/homepage | hero + características de la home por defecto |
applets/meta-custom-page | title/description/social por página, gestionados desde el backend |
applets/services | no es un applet de layout: es la carpeta de los endpoints HTTP, ver 03 |
Los applets están cableados en el seed y se encienden/apagan desde el asistente o desde layout_path.visible (header = ID 2, footer = ID 3).
4. Layout: cómo acaban los bloques en la página
| Tabla | Función |
|---|---|
layout | los bloques disponibles |
layout_path | qué bloque en qué ruta, con visible como interruptor |
layout_location | la posición en la estructura (header, columna, footer…) |
El layout se gestiona desde /restricted/block y /restricted/themes. Un proyecto que no quiere el layout del CMS en una página concreta imprime directamente y hace exit (§1).
5. CSS y JS: qué es automático y qué no
Dos funciones de sistema deciden los recursos:
- JS —
system_set_js_level()enlibrary/gallery/system/set_js.php - CSS —
system_set_css_level()enlibrary/gallery/system/set_css.php
El mecanismo funciona por convención de nombre: un archivo que corresponde a la ruta de la página se carga solo. En los proyectos del ecosistema la convención adoptada es:
| Qué | Dónde |
|---|---|
| controlador de página | contents/<nombre>.php |
| plantilla de la página | themes/<tema>/contents/<nombre>/index.html |
| JS de la página | themes/<tema>/javascript/<nombre>.js — se carga solo |
| CSS de la página | themes/<tema>/css/<nombre>.css — se carga solo |
Para añadir un recurso a mano se usa $cm->oPage->addJs(...) / addCss(...) desde el controlador.
⚠️ En los endpoints JSON (/srv) el bus de sistema vacía $cm->oPage->page_js y page_css y registra los encontrados en request_error_js / request_error_css: si hay alguno, algo ha intentado decorar una respuesta que no es una página.
Front-end JoeCMS: SCSS modular
El CSS del tema site está escrito como SCSS modular en themes/site/css/root/ (_color, _sizes, _font, _typography, _base, _components) y compilado en root.css; los tokens de marca están en themes/site/css/joecms-brand.css. Un proyecto nuevo cambia paleta y tipografía tocando dos partials, no un CSS monolítico.
6. Temas presentes
| Tema | Uso |
|---|---|
themes/site | front-end público |
themes/gallery | backend /restricted (Foundation) |
themes/admin | skin de las intervenciones en el backend (css/ff-skin.css) |
themes/responsive | widgets del forms framework (ff/) |
themes/vgnext | nueva área de gestión de contenidos |
themes/library | vendors JS/CSS |
Config de entorno del tema: themes/site/conf/config.local.php (desarrollo) y config.remote.php (producción, escrito por el instalador con chmod 0640). Es HTTP_HOST quien decide cuál de los dos se carga — detalle que importa bastante desde línea de comandos, ver 13 — Observabilidad y CLI.