Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 02

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

Falso 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 imprimeDó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 scriptel mismo código en el atributo (data-err-…="{_svc_…}"): el texto no debe contener "
un mensaje de Auth o de un widget de la cuentaAuth::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:

AppletFunción
applets/headerlogo, navegación, [LANGUAGE_SWITCHER]
applets/footerenlaces legales, copyright
applets/homepagehero + características de la home por defecto
applets/meta-custom-pagetitle/description/social por página, gestionados desde el backend
applets/servicesno 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

TablaFunción
layoutlos bloques disponibles
layout_pathqué bloque en qué ruta, con visible como interruptor
layout_locationla 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() en library/gallery/system/set_js.php
  • CSS — system_set_css_level() en library/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áginacontents/<nombre>.php
plantilla de la páginathemes/<tema>/contents/<nombre>/index.html
JS de la páginathemes/<tema>/javascript/<nombre>.js — se carga solo
CSS de la páginathemes/<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

TemaUso
themes/sitefront-end público
themes/gallerybackend /restricted (Foundation)
themes/adminskin de las intervenciones en el backend (css/ff-skin.css)
themes/responsivewidgets del forms framework (ff/)
themes/vgnextnueva área de gestión de contenidos
themes/libraryvendors 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.