Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Crear themes

5 min de lectura 17 apartados

En esta página

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:

TipoQué esCuándo elegirlo
Theme hijoDeclara "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 completoSin 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 #

text
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 hijos

En 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 #

bash
php bin/console.php make:theme mi-theme --name="Mi Theme" --parent=default

Genera un theme hijo en content/themes/mi-theme/ con:

  • theme.json con spec: 1, versión 0.1.0, el padre, requires.core fijado a la versión menor actual y el canal de actualización stable.
  • Un screenshot.png provisional (necesita la extensión GD de PHP; cámbialo antes de publicar).
  • functions.php vacío y comentado.
  • templates/ vacío: hasta que copies una plantilla, todo sale del padre.
  • assets/critical.extra.css para 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 #

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():

html
@if(setting('theme.mi-theme.hero_autoplay', true))
  <div class="hero" data-autoplay>…</div>
@endif

functions.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
<?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
<?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',
    ],
];
html
{{ __('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.

PlantillaRutaQué muestra
home/, /page/2…Portada: hero, filas y últimos episodios.
titles/movies, /series, /year/2024Listado 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/offlineLa 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):

ClaveContenido
name, tagline, descriptionNombre, eslogan y descripción del sitio.
footer_text, social_linksTexto del pie y lista de enlaces sociales.
footer_pagesPáginas marcadas para el pie (cada una con title y url).
urlURL base sin / final.
lang, langs, localeIdioma actual, idiomas activos y locale (es_ES).
appearanceAjustes 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>.

PlantillaVariables
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»)
seasonLo 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, offlineSolo 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:

html
<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 {!! !!}.

HelperDevuelve
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:

html
@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 priority por vista: la del LCP (el hero, el póster de la ficha). El resto, lazy (es lo que hace img() por defecto).
  • Ajusta sizes al ancho real en pantalla y limita con max las 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.js lo convierte en imagen al llegar a esa diapositiva.
html
<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…).

HookDó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 &lt;/body&gt;» 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:

html
@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> con inline_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:

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:

  1. assets/critical.extra.css: se añade detrás del CSS del padre. Es lo normal para retoques.
  2. Su propio assets/critical.css: sustituye por completo al del padre. Es lo que hacen Nébula y Lumen, que lo compilan desde src/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:

html
@php $childJs = child_theme_asset('js'); @endphp
@if($childJs !== '')<script type="module" src="{{ $childJs }}"></script>
@endif

Variables 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.js es un módulo (<script type="module">) y el único script inicial. Carga el resto bajo demanda con import().
  • Importa los demás módulos con el mismo ?v= que trae main.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:
html
<script type="application/json" id="mm-i18n">@json(['all_results' => __('theme.suggest_all')])</script>
js
const t = JSON.parse(document.getElementById('mm-i18n')?.textContent || '{}');
  • Service worker (assets/sw.js, servido en /sw): regístralo después del evento load y nunca intercepes /admin, /install, /api ni peticiones que no sean GET. Cinema lo registra desde main.js cuando el <script> lleva data-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:

json
"contracts": ["player@1", "mylist@1", "install@1", "i18n@1", "account@1", "comments@1"]
ContratoQué tiene que haber en el theme
player@1El 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@1Un [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@1Un 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.

html
{{-- 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.tpl y mylist.tpl, #row-recent y #row-list reciben las tarjetas. Con data-grid se pintan como rejilla en vez de fila. #mm-empty se oculta si hay algo que mostrar.
  • Los enlaces a episodios a.ep reciben la clase seen cuando el visitante ya los vio.

Reproductor #

player() genera todo el marcado. Lo que el theme debe respetar:

  • El contenedor: .facade dentro de .player. En episode.tpl, #ep-page > #watch > .player; así el cambio de episodio en caliente sustituye solo esa parte.
  • Siguiente episodio: un a[data-next] con data-name y data-img. .player lleva data-credits (segundos antes del final) y data-wait (cuenta atrás) desde Ajustes → Reproductor.
  • Saltar intro: con los segmentos activos, .facade lleva data-seg y player.js añade un button.btn.sk mientras 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 (alt en img()); 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 #

bash
php bin/console.php theme:check mi-theme
php bin/console.php cache:clear

theme: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:

MensajeSolución
screenshot.png missing (required in spec 1)Añade la captura (880×660, menos de 300 KB).
parent theme 'x' not foundInstala el padre o corrige parent.
inline CSS over budget: … > 20480Reduce el CSS o, en un theme completo, sube budget.inline_css (máx. 32768).
… is only loaded for child themescritical.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:check sin errores y cache:clear hecho.
  • [ ] 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 priority por 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_css quita los espacios alrededor de :, así que padre :is(hijo) (o padre :hover, padre :first-child) se convierte en padre:is(hijo), que significa otra cosa. Escribe padre *:is(hijo).
  • content-visibility: auto aísla los contadores CSS. Si numeras con counter(), 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 .sr con position:absolute necesita un antepasado posicionado; si no, ensancha la página.
  • Más imágenes prioritarias no es mejor. Cada priority de más compite con la del LCP y lo empeora.
  • Contenido fuera de @section en 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.

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?