Cómo construir un theme para MovieMaster: la estructura de carpetas, los themes hijos, theme.json, functions.php, las plantillas y sus variables, los helpers, los hooks obligatorios, el CSS y el JavaScript con sus presupuestos, y los contratos que esperan los plugins. La sintaxis de las plantillas .tpl está en su propia guía: plantillas.
Theme completo o theme hijo #
Hay dos formas de hacer un theme:
| Tipo | Qué es | Cuándo elegirlo |
|---|---|---|
| Theme hijo | Declara "parent": "default" (u otro theme) y solo trae lo que cambia: unas plantillas, un poco de CSS, textos. Todo lo demás lo hereda. | Casi siempre. Recibe gratis las mejoras del padre en cada actualización. |
| Theme completo | Sin parent. Trae su propio layout.tpl, su CSS crítico y su JavaScript. | Cuando el diseño no se parece en nada a ninguno de los themes que vienen con el CMS. |
Los themes incluidos son Cinema (default, el theme base), Nébula (nebula) y Lumen (lumen). Nébula y Lumen son hijos de Cinema: sobrescriben layout.tpl, home.tpl, title.tpl, episode.tpl y algunos parciales, y traen su propio critical.css. Son el mejor ejemplo de un theme hijo grande.
Estructura de un theme #
content/themes/<slug>/
theme.json manifest spec 1
screenshot.png 880×660, menos de 300 KB
functions.php opcional: hooks del theme
lang/ opcional: es.php, en.php…
templates/
layout.tpl esqueleto de todas las páginas
home.tpl portada
titles.tpl listados de películas, series y años
title.tpl ficha de película o serie
season.tpl temporada
episode.tpl episodio
genres.tpl tags.tpl índices de géneros y etiquetas
term.tpl un género o una etiqueta
people.tpl person.tpl
search.tpl page.tpl mylist.tpl offline.tpl
errors/error.tpl errores (o errors/404.tpl, errors/500.tpl…)
pages/<plantilla>.tpl opcional: plantillas elegibles para páginas
partials/ card, row, grid, more, person, episodes, sort
assets/
critical.css CSS que se incrusta en cada página
main.js módulo principal
player.js lists.js search.js sw.js
brand/
critical.extra.css solo themes hijos
child.js solo themes hijosEn un theme hijo todo es opcional menos theme.json y screenshot.png. Cada archivo que pongas sustituye al del padre con el mismo nombre; lo que no pongas se sigue usando del padre.
El nombre de la carpeta es el slug y tiene que coincidir con el de theme.json. Un theme se activa en Admin → Apariencia → Themes. Si el mismo slug existe en core/themes/ y en content/themes/, se usa la carpeta con la versión más nueva.
Crear un theme con make:theme #
php bin/console.php make:theme mi-theme --name="Mi Theme" --parent=defaultGenera un theme hijo en content/themes/mi-theme/ con:
theme.jsonconspec: 1, versión0.1.0, el padre,requires.corefijado a la versión menor actual y el canal de actualizaciónstable.- Un
screenshot.pngprovisional (necesita la extensión GD de PHP; cámbialo antes de publicar). functions.phpvacío y comentado.templates/vacío: hasta que copies una plantilla, todo sale del padre.assets/critical.extra.csspara tu CSS adicional.
Otras opciones: --description=, --author=, --license= y --force (sobrescribe los archivos generados si el theme ya existe). No crea child.js: cada byte cuenta en el presupuesto de JavaScript, así que añádelo solo si lo necesitas.
Para un theme completo, copia core/themes/default a content/themes/<tu-slug>, cambia slug y name en theme.json y quita parent.
El flujo normal de un theme hijo es copiar del padre solo la plantilla que quieres cambiar (core/themes/default/templates/title.tpl → content/themes/mi-theme/templates/title.tpl), editarla y comprobar con theme:check.
theme.json #
{
"$schema": "https://moviemaster.dev/schema/theme-v1.json",
"spec": 1,
"name": "Mi Theme",
"slug": "mi-theme",
"version": "1.0.0",
"parent": "default",
"author": { "name": "Tu estudio", "url": "https://tu-estudio.com" },
"license": "proprietary",
"description": "Portada con carrusel y fichas en dos columnas.",
"descriptions": { "es": "Portada con carrusel y fichas en dos columnas." },
"requires": { "core": "^0.9", "php": ">=8.2" },
"screenshot": "screenshot.png",
"supports": ["custom-colors", "custom-logo", "pwa", "series", "mylist"],
"contracts": ["player@1", "mylist@1", "install@1", "i18n@1"],
"settings": [
{ "key": "hero_autoplay", "type": "checkbox", "label": "Carrusel automático", "default": true }
],
"budget": { "inline_css": 20480, "js_initial": 5120 }
}Los campos son los mismos que en un plugin, con tres propios de los themes: parent, screenshot y budget. La explicación de cada uno está en la referencia del manifest.
Ajustes del theme #
Cada entrada de settings aparece en Admin → Ajustes, en el grupo «Opciones del theme · Mi Theme», solo mientras el theme está activo. Los tipos son los mismos que en los plugins (text, textarea, number, checkbox, select, color, url, list, media, secret, info).
El valor se guarda como theme.<slug>.<key>, así que se lee con setting():
@if(setting('theme.mi-theme.hero_autoplay', true))
<div class="hero" data-autoplay>…</div>
@endiffunctions.php #
Es el punto de entrada PHP del theme. Se carga en cada petición, después de los plugins activos (así puedes usar sus funciones y sus hooks), primero el del padre y luego el del hijo. Se ejecuta dentro de una función aislada: no recibe variables, pero tiene a mano todas las funciones globales y los hooks.
<?php
// content/themes/mi-theme/functions.php
// Una clase en <body> según la plantilla
add_filter('body_class', function (string $classes): string {
return $classes . ' mi-theme';
});
// Cinco títulos relacionados en vez de los que traiga el padre
add_filter('related_limit', fn () => 5);
// Datos extra para una plantilla concreta
add_filter('template_data', function (array $data, string $template): array {
if ($template === 'home') {
$data['destacado'] = setting('theme.mi-theme.destacado', '');
}
return $data;
}, 10, 2);
// Algo en el <head> de todas las páginas
add_action('head', function (): void {
echo '<meta name="color-scheme" content="dark">';
});Si functions.php lanza una excepción, el error se registra en el log y el sitio sigue funcionando con el theme sin esas modificaciones. No lo uses para crear tablas ni guardar datos: eso es trabajo de un plugin.
Traducciones #
Los archivos lang/es.php, lang/en.php… de un theme devuelven un array que se fusiona con las cadenas del núcleo (no tienen dominio propio). Agrupa tus textos bajo una clave con el nombre del theme:
<?php
// lang/es.php
return [
'mi_theme' => [
'ver_trailer' => 'Ver tráiler',
'temporadas' => ':n temporadas',
],
// Reescribir un texto del núcleo en todo el sitio:
'theme' => [
'watch_now' => 'Reproducir',
],
];{{ __('mi_theme.ver_trailer') }}
{{ __('mi_theme.temporadas', ['n' => count($seasons)]) }}Los archivos del padre se cargan antes que los del hijo, así que el hijo gana. Si falta una clave en el idioma de la página se usa el idioma por defecto del sitio y después el inglés. Más detalles en plantillas.
Plantillas del theme #
Cada página pública se dibuja con una plantilla de nombre fijo. Todas extienden layout con @extends('layout') y rellenan la sección content.
| Plantilla | Ruta | Qué muestra |
|---|---|---|
home | /, /page/2… | Portada: hero, filas y últimos episodios. |
titles | /movies, /series, /year/2024 | Listado paginado con orden y filtro por año. |
title | /movie/<slug>, /series/<slug> | Ficha con reproductor, temporadas y relacionados. |
season | /series/<slug>/season/<n> | Una temporada con sus episodios. |
episode | /series/<slug>/season/<n>/episode/<m> | Episodio con reproductor y navegación. |
genres, tags | /genres, /tags | Índices de géneros y etiquetas. |
term | /genre/<slug>, /tag/<slug> | Títulos de un género o una etiqueta. |
people, person | /people, /person/<slug> | Reparto y ficha de una persona. |
search | /search?q= | Resultados de búsqueda. |
page | /p/<slug> | Página estática. Si la página elige una plantilla x y existe pages/x.tpl, se usa esa. |
mylist | /my-list | «Mi lista» y «Seguir viendo» (se pintan en el navegador). |
offline | /offline | La página que la PWA enseña sin conexión. |
errors/<código> | — | Errores. Se busca errors/404, después errors/error. |
Un plugin puede sustituir cualquier plantilla con el filtro template_path o añadir datos con template_data; por eso conviene que tus plantillas no supongan variables que el núcleo no garantiza.
Variables por plantilla #
Todas las plantillas reciben $site, $seo y $template (el nombre de la plantilla). layout.tpl ve además todas las variables de la plantilla hija.
$site (la configuración del sitio):
| Clave | Contenido |
|---|---|
name, tagline, description | Nombre, eslogan y descripción del sitio. |
footer_text, social_links | Texto del pie y lista de enlaces sociales. |
footer_pages | Páginas marcadas para el pie (cada una con title y url). |
url | URL base sin / final. |
lang, langs, locale | Idioma actual, idiomas activos y locale (es_ES). |
appearance | Ajustes de Apariencia: primary, secondary, logo_media_id, favicon_media_id, custom_css… |
$seo es un objeto PageSeo: {!! $seo->render() !!} imprime el <title>, las metas, los hreflang y el JSON-LD. Va una vez, dentro del <head>.
| Plantilla | Variables |
|---|---|
home | $hero (títulos destacados), $rails (filas: cada una con su título y sus títulos), $latest_episodes, $series_by_id (la serie de cada episodio, por id), $genres, $titles, $pagination, $page |
titles | $heading, $type (movie, series o null en años), $titles, $pagination, $page, $sort, $sorts, $base (ruta para paginar), $years |
title | $title, $sources (fuentes agrupadas para player()), $seasons, $episodes, $current_season, $related, $first_episode (series: el primer episodio de la primera temporada; películas: null), $upcoming (true si aún no hay fuentes y el título está marcado como «próximamente») |
season | Lo mismo que title, más $season |
episode | $title, $season, $episode, $episodes, $seasons, $sources, $nav (prev y next) |
genres, tags | $terms |
term | $term, $titles, $pagination, $page, $sort, $sorts, $base, $siblings (otros términos populares) |
people | $people, $pagination, $page |
person | $person, $titles, $credits, $collaborators, $pagination, $page |
search | $q, $titles, $people, $pagination, $page |
page y pages/* | $page (la página: title, content, template…) |
mylist, offline | Solo las comunes |
errors/* | $status, $message |
Los campos de cada título, episodio, término y persona son los que devuelven los repositorios; están listados en la API PHP. Lo más usado en una tarjeta: $t['title'], $t['url'], $t['type'], $t['year'], $t['rating'], $t['poster'], $t['backdrop'], $t['runtime_label'] y $t['seasons_count'].
Para inspeccionar lo que llega, activa app.debug y escribe temporalmente en la plantilla:
<pre>@json(array_keys(get_defined_vars()))</pre>Helpers para plantillas #
Funciones pensadas para usarse dentro de los .tpl. Las que devuelven HTML se imprimen con {!! !!}.
| Helper | Devuelve |
|---|---|
img(?array $media, $size = 'thumb', array $opts = []) | <picture> con AVIF/WebP, srcset, ancho y alto. $size es el tipo de imagen (poster, backdrop, still, profile, logo…) o un ancho. Opciones: alt, priority, lazy, sizes, class, max (ancho máximo del srcset). Sin imagen devuelve un hueco .ph con la proporción correcta. |
art_img(?array $wide, ?array $tall, $alt = '', $priority = false, $class = 'bg') | Imagen con dirección de arte: el póster en móvil y el backdrop desde 768 px. Para billboards. |
player(array $grouped, ?array $backdrop, string $label, string $beacon = '', bool $priority = false, string $actions = '', bool $upcoming = false) | El reproductor completo: facade con la imagen, barra de idiomas y servidores, y el iframe o <video> al pulsar. $beacon es la URL que cuenta la visita (url('/api/view/' . $t['id'])). |
trailer_facade(array $title) | El tráiler de YouTube como facade (no carga YouTube hasta el clic). '' si no hay tráiler. |
rating_badge($rating) | La nota con su estilo. |
rank_svg(int $n) | El número grande y perfilado del Top 10 (1–10), como SVG. |
wordmark(string $text, $alto = 24, array $opts = []) | El nombre del sitio dibujado en SVG, en mayúsculas y a dos tonos, sin fuentes web. Opciones: accent, split, id, use, class, tracking. Devuelve '' si el texto tiene caracteres que no sabe dibujar: prevé un texto de reserva. |
pagination(array $p, string $base, string $pattern = '%s/page/%d') | La paginación accesible a partir de $pagination y $base. |
lang_switcher(array $alternates = [], ?string $current = null) | Selector de idioma. |
theme_asset(string $file) | URL de un archivo de assets/ con ?v= (la fecha del archivo más reciente). Busca en el hijo y luego en el padre. |
inline_css(string $file) | El contenido minificado de un CSS de assets/, para meterlo en <style>. |
child_theme_asset('css'|'js') | El CSS extra o la URL de child.js del theme hijo; '' si no hay o si se pasa del presupuesto. |
theme_vars(array $appearance) | :root{--primary;--secondary;--on-primary} con los colores de Apariencia. |
theme_setting(string $key, $default = null) | Un ajuste de Apariencia (appearance.<key>). |
brand_asset(string $file) | Un archivo de marca de MovieMaster (assets/brand/). |
compact_number(int $n) | 1500 → 1.5K, 2000000 → 2M. |
media() | El repositorio de medios: media()->find($id), media()->url($media, 480, 'jpg'). |
url(), lang_url(), current_lang(), setting(), plugin_active(), __(), _n(), e() | Las funciones globales de siempre. |
Y un parcial que conviene reutilizar:
@include('partials/grid', ['titles' => $titles, 'lcp' => 2])lcp es cuántas tarjetas cargan con prioridad (true equivale a 2). Pon solo las que se ven sin desplazarse en un móvil.
Imágenes #
Usa siempre img() o art_img(). Generan los formatos modernos, los tamaños y las dimensiones que evitan saltos de diseño.
- Una sola imagen
prioritypor vista: la del LCP (el hero, el póster de la ficha). El resto,lazy(es lo que haceimg()por defecto). - Ajusta
sizesal ancho real en pantalla y limita conmaxlas tarjetas pequeñas: menos bytes en móvil. - El arte de las diapositivas que no son la primera va dentro de
<template class="bb-art">.main.jslo convierte en imagen al llegar a esa diapositiva.
<a class="card" href="{{ $t['url'] }}">
{!! img($t['poster'], 'poster', ['alt' => $t['title'], 'sizes' => '(max-width: 767px) 42vw, 200px', 'max' => 500]) !!}
<p class="card-title">{{ $t['title'] }}</p>
</a>Hooks que todo theme debe disparar #
Los plugins se enganchan a estos puntos. Si tu layout.tpl no los dispara, los plugins que dependan de ellos no aparecen (cuentas, comentarios, publicidad, analítica…).
| Hook | Dónde |
|---|---|
@hook('head') | Al final del <head>, después del CSS. |
@hook('body_open') | Justo después de <body>. |
@hook('nav_items') | Dentro del menú principal. Aquí llega el enlace «Entrar» del plugin de cuentas. |
@hook('before_content') | Antes del contenido principal. |
@hook('after_content') | Después del contenido principal. Aquí llega la caja de comentarios. |
@hook('footer') | Dentro del pie. |
@hook('body_close') | Justo antes de </body>, después de los scripts del theme. Aquí imprime el núcleo el «Código antes de </body>» de los scripts de publicidad; si no lo disparas, ese código sale en footer. |
@hook('player_before'), @hook('player_after') | Antes y después de player() en title.tpl y episode.tpl. |
Además se aplica el filtro body_class a la clase del <body>. El esqueleto mínimo de un layout.tpl:
@php $ap = $site['appearance'] ?? []; @endphp<!DOCTYPE html>
<html lang="{{ $site['lang'] }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
{!! $seo->render() !!}
<style>{!! inline_css('critical.css') !!}{!! child_theme_asset('css') !!}{{ theme_vars($ap) }}{!! str_replace('</style', '', (string) ($ap['custom_css'] ?? '')) !!}</style>
@hook('head')
</head>
<body class="{{ apply_filters('body_class', 'tpl-' . $template) }}">
@hook('body_open')
<header class="top">
<a class="brand" href="{{ url('/') }}">{{ $site['name'] }}</a>
<nav aria-label="{{ __('theme.main_nav') }}">
<a href="{{ url('/movies') }}">{{ __('common.movies') }}</a>
<a href="{{ url('/series') }}">{{ __('common.series') }}</a>
@hook('nav_items')
</nav>
</header>
@hook('before_content')
<main id="main">
@yield('content')
</main>
@hook('after_content')
<footer>
@hook('footer')
</footer>
<script type="module" src="{{ theme_asset('main.js') }}"></script>
@hook('body_close')
</body>
</html>La lista completa de acciones y filtros, con sus argumentos, está en la referencia de hooks.
CSS crítico y presupuestos #
MovieMaster apunta a 100 en Lighthouse, y el theme es lo que más pesa en eso. Las reglas:
- Todo el CSS va incrustado en un
<style>del<head>coninline_css('critical.css'). No hay hojas externas que bloqueen el render. - Sin fuentes web. Usa la pila del sistema (
system-ui, -apple-system, "Segoe UI", Roboto, sans-serif). Para el logo de texto,wordmark(). - Presupuesto: 20 KB de CSS incrustado (minificado) y 5 KB de JavaScript inicial (
main.js).
Los presupuestos se declaran en theme.json:
"budget": { "inline_css": 20480, "js_initial": 5120 }Un theme completo puede subir inline_css hasta 32768 bytes si lo necesita. En un theme hijo el límite efectivo es el menor entre el del núcleo, el del hijo y el del padre, y cuenta la suma de la base (el critical.css del hijo o, si no tiene, el del padre) más el extra.
CSS y JavaScript de un theme hijo #
Un hijo tiene dos formas de añadir estilos:
assets/critical.extra.css: se añade detrás del CSS del padre. Es lo normal para retoques.- Su propio
assets/critical.css: sustituye por completo al del padre. Es lo que hacen Nébula y Lumen, que lo compilan desdesrc/theme.css.
Para JavaScript, assets/child.js se carga como módulo detrás del main.js del padre. layout.tpl de Cinema ya lo incluye:
@php $childJs = child_theme_asset('js'); @endphp
@if($childJs !== '')<script type="module" src="{{ $childJs }}"></script>
@endifVariables CSS #
Define tus colores como variables en :root. theme_vars() añade después --primary, --secondary y --on-primary con los colores que el administrador elija en Apariencia, así que tu CSS debe usar var(--primary) en vez del color escrito.
Los plugins de cuentas y comentarios se pintan con estas variables y clases del theme; si faltan, caen en valores neutros:
- Variables:
--bg --bg-2 --bg-3 --fg --fg-2 --fg-3 --line --link --primary --on-primary --pad --r. - Clases:
.wrap,.sec,.h1,.h2,.btn,.btn-primary,.btn-soft.
La tarjeta que se comparte en redes también lee --bg, --primary y --link del primer :root de tu CSS, escritos en hexadecimal (#0b1020, no rgb() ni otra variable).
JavaScript del theme #
main.jses un módulo (<script type="module">) y el único script inicial. Carga el resto bajo demanda conimport().- Importa los demás módulos con el mismo
?v=que traemain.js(import('./player.js?v=' + v)); si no, el navegador puede mezclar versiones viejas y nuevas tras una actualización. - Para textos traducidos en JavaScript, imprímelos en un JSON dentro de la página y léelos desde el script:
<script type="application/json" id="mm-i18n">@json(['all_results' => __('theme.suggest_all')])</script>const t = JSON.parse(document.getElementById('mm-i18n')?.textContent || '{}');- Service worker (
assets/sw.js, servido en/sw): regístralo después del eventoloady nunca intercepes/admin,/install,/apini peticiones que no sean GET. Cinema lo registra desdemain.jscuando el<script>llevadata-sw="{{ url('/sw') }}"(solo si la PWA está activa:setting('pwa.enabled', true)).
Contratos con los plugins #
Un contrato es una promesa de marcado: el theme deja un hueco con una forma concreta y los plugins (o los scripts del núcleo) cuentan con él. Declara en theme.json los que cumples:
"contracts": ["player@1", "mylist@1", "install@1", "i18n@1", "account@1", "comments@1"]| Contrato | Qué tiene que haber en el theme |
|---|---|
player@1 | El reproductor de player() dentro de #watch en episode.tpl (con #ep-page como contenedor de la página), y los hooks player_before/player_after. |
mylist@1 | #mm-this en las fichas, [data-mylist] para guardar, y #row-recent/#row-list donde se pintan las listas. Detalles abajo. |
install@1 | Un [data-install] con un <button> dentro, que empieza con hidden. |
i18n@1 | <script type="application/json" id="mm-i18n"> con los textos que usan los scripts. |
account@1 | Un enlace <a href="{{ url('/account/login') }}" rel="nofollow" data-account data-account-url="{{ url('/account') }}" data-in="Mi cuenta">Entrar</a> donde quieras. El script del plugin lo cambia a «Mi cuenta» cuando hay sesión. Envuélvelo en @if(plugin_active('members')). |
comments@1 | @hook('comments') en title.tpl y episode.tpl, donde quieras la caja de comentarios. |
Sin account@1 ni comments@1, los plugins se colocan solos: el enlace «Entrar» por nav_items y la caja de comentarios por after_content. Los contratos sirven para que tú decidas el sitio exacto.
Reproductor, Mi lista y Seguir viendo #
Si heredas de Cinema y conservas su marcado, todo esto funciona sin tocar nada. Si escribes un theme completo o cambias esas piezas, este es el marcado que esperan player.js y lists.js.
Mi lista y Seguir viendo #
Se guardan en el navegador del visitante (localStorage), sin cuentas.
{{-- En title.tpl y episode.tpl: los datos de lo que se está viendo --}}
<div id="mm-this" hidden
data-u="{{ $title['url'] }}"
data-t="{{ $title['title'] }}"
data-i="{{ $title['backdrop'] ? media()->url($title['backdrop'], 480, 'jpg') : '' }}"
data-m="{{ $title['year'] }}"></div>
{{-- Botón de guardar --}}
<button type="button" data-mylist aria-pressed="false"
data-on="✓ {{ __('theme.in_list') }}" data-off="+ {{ __('theme.my_list') }}">+ {{ __('theme.my_list') }}</button>
{{-- Series: «Reproducir» pasa a «Continuar S01E02» si hay un episodio visto --}}
@if($title['type'] === 'series' && $first_episode)
<a class="btn" href="{{ url('/series/' . $title['slug'] . '/season/' . $first_episode['season_number'] . '/episode/' . $first_episode['episode_number']) }}"
data-resume="{{ __('theme.resume') }}"><span>{{ __('theme.play') }}</span></a>
@endif- En
home.tplymylist.tpl,#row-recenty#row-listreciben las tarjetas. Condata-gridse pintan como rejilla en vez de fila.#mm-emptyse oculta si hay algo que mostrar. - Los enlaces a episodios
a.epreciben la claseseencuando el visitante ya los vio.
Reproductor #
player() genera todo el marcado. Lo que el theme debe respetar:
- El contenedor:
.facadedentro de.player. Enepisode.tpl,#ep-page > #watch > .player; así el cambio de episodio en caliente sustituye solo esa parte. - Siguiente episodio: un
a[data-next]condata-nameydata-img..playerllevadata-credits(segundos antes del final) ydata-wait(cuenta atrás) desde Ajustes → Reproductor. - Saltar intro: con los segmentos activos,
.facadellevadata-segyplayer.jsañade unbutton.btn.skmientras dura la intro. Los textos salen de#mm-i18n(skip_intro,skip_recap). - Pantalla completa en iPhone: el reproductor recibe
.is-fs. Las reglas que limitan su tamaño van bajo.player:not(.is-fs). - Clases que añade el script y puedes estilar:
.dd-m,.dd-o(desplegables),.nx(tarjeta de siguiente) y.sk(saltar).
Un reproductor de terceros en iframe puede hablar con MovieMaster con parent.postMessage: 'mm:credits' (mostrar ya la tarjeta de siguiente), 'mm:next' (pasar de episodio), 'mm:ended' (terminó) y, opcionalmente, su progreso {currentTime, duration}.
Portada y filas #
main.js de Cinema espera [data-nav-toggle] (botón del menú móvil), [data-rail] (filas con desplazamiento) y [data-hero] (carrusel). La fila del Top 10 es .rail.top y cada tarjeta es .t10, con el número de rank_svg() (se colorea con .t10 svg path).
SEO y accesibilidad #
El núcleo genera el SEO; el theme solo tiene que no estropearlo:
{!! $seo->render() !!}una sola vez en el<head>y<html lang="{{ $site['lang'] }}">.- Un único
<h1>por página. Los títulos de las tarjetas van en<p>o<span>, no en<h2>/<h3>, para no inflar la estructura de encabezados. - Textos alternativos en las imágenes con contenido (
altenimg());alt=""en las decorativas. - Contraste suficiente y foco visible en todo lo que se puede pulsar. Los iconos sin texto llevan
aria-label. - La marca del pie es la del sitio (su logo o su nombre), nunca la «M» de MovieMaster.
Comprobar y publicar #
php bin/console.php theme:check mi-theme
php bin/console.php cache:cleartheme:check compila y revisa la sintaxis de todas las plantillas, valida theme.json, comprueba el padre y los presupuestos, y busca archivos que no deben ir en una extensión (.env, llaves, bases de datos, .git…). Errores típicos:
| Mensaje | Solución |
|---|---|
screenshot.png missing (required in spec 1) | Añade la captura (880×660, menos de 300 KB). |
parent theme 'x' not found | Instala el padre o corrige parent. |
inline CSS over budget: … > 20480 | Reduce el CSS o, en un theme completo, sube budget.inline_css (máx. 32768). |
… is only loaded for child themes | critical.extra.css/child.js en un theme sin padre: mueve su contenido a tus archivos principales. |
templates/x.tpl: … | Error de sintaxis en una plantilla: la línea indicada es la del PHP compilado. |
Antes de publicar, repasa esta lista:
- [ ]
theme:checksin errores ycache:clearhecho. - [ ] Lighthouse 100 en móvil en portada, ficha y episodio.
- [ ] Todos los hooks del layout y, si cambias el marcado, los contratos que declaras.
- [ ] Una sola imagen
prioritypor vista. - [ ] Probado con nombres largos, títulos sin imagen y sin traducción, y con los dos idiomas.
- [ ] Captura propia, sin arte de terceros (pósters de películas reales, logos de marcas).
El empaquetado (ext:pack) y la publicación en la tienda se explican en empaquetar y publicar.
Trampas conocidas #
- Espacios antes de
:y la minificación.minify_cssquita los espacios alrededor de:, así quepadre :is(hijo)(opadre :hover,padre :first-child) se convierte enpadre:is(hijo), que significa otra cosa. Escribepadre *:is(hijo). content-visibility: autoaísla los contadores CSS. Si numeras concounter(), cada bloque vuelve a empezar. Los números del Top 10 salen de la plantilla (rank_svg($loop->iteration)).- Textos solo para lectores de pantalla dentro de una fila con scroll horizontal. Un
.srconposition:absolutenecesita un antepasado posicionado; si no, ensancha la página. - Más imágenes prioritarias no es mejor. Cada
priorityde más compite con la del LCP y lo empeora. - Contenido fuera de
@sectionen una plantilla hija se descarta sin aviso. Ver plantillas. - Cambios que no se ven. Las plantillas compiladas se renuevan solas cuando cambia el
.tpl, pero la caché de páginas no. Tras tocar el theme en producción,cache:clear(activar o actualizar el theme ya la vacía). - Capturas a página completa con herramientas automáticas no cargan las imágenes
lazy: no es un fallo del theme.