Las páginas del sitio, el panel y las vistas de los plugins se escriben en archivos .tpl. La sintaxis se parece a la de Blade (Laravel): {{ }} para imprimir, directivas que empiezan por @ y herencia de layouts. Cada plantilla se compila una vez a PHP normal y se guarda en content/cache/views/, así que no cuesta nada en tiempo de ejecución.
Imprimir valores #
| Sintaxis | Qué hace |
|---|---|
{{ $title['title'] }} | Imprime escapado con e(). null no imprime nada. Úsalo siempre que el valor venga de la base de datos o del visitante. |
{!! $html !!} | Imprime sin escapar. Solo para HTML que tú controlas o que ya devuelve un helper (img(), player(), wordmark(), $seo->render()). |
{{-- comentario --}} | Comentario: no llega al HTML. |
@{{ algo }} | Imprime {{ algo }} literal (para JavaScript con plantillas propias). |
@@if | Imprime @if literal. |
@verbatim … @endverbatim | Todo lo de dentro sale tal cual, sin compilar. |
<h1>{{ $title['title'] }}</h1>
<p class="sinopsis">{{ str_limit($title['overview'], 200) }}</p>
{!! img($title['poster'], 'poster', ['alt' => $title['title'], 'priority' => true]) !!}Condiciones #
@if ($title['rating'] >= 8)
<span class="top">{{ __('common.top_rated') }}</span>
@elseif ($title['rating'] > 0)
{!! rating_badge($title['rating']) !!}
@else
<span>—</span>
@endif
@unless (empty($title['tagline']))
<p class="tagline">{{ $title['tagline'] }}</p>
@endunless
@isset($season)
<h2>{{ $season['name'] }}</h2>
@endisset
@empty($related)
<p>{{ __('common.nothing_here') }}</p>
@endempty| Directiva | Equivale a |
|---|---|
@if (expr) · @elseif (expr) · @else · @endif | if de PHP |
@unless (expr) · @endunless | if (!expr) |
@isset($var) · @endisset | if (isset($var)) |
@empty($var) · @endempty | if (empty($var)) |
@hasSection('nombre') · @endif | ¿Alguna plantilla definió esa sección? |
Bucles #
@foreach ($titles as $t)
<a class="cd{{ $loop->first ? ' first' : '' }}" href="{{ $t['url'] }}">
<span class="n">{{ $loop->iteration }}</span>
{{ $t['title'] }}
</a>
@endforeach
@forelse ($people as $p)
<li>{{ $p['name'] }}</li>
@empty
<li>{{ __('common.no_results') }}</li>
@endforelse
@for ($i = 1; $i <= 10; $i++) … @endfor
@while ($cond) … @endwhile@break y @continue cortan o saltan, y aceptan una condición: @break($loop->iteration > 5), @continue(empty($t['poster'])).
La variable $loop #
Dentro de @foreach y @forelse tienes $loop:
| Propiedad | Valor |
|---|---|
$loop->iteration | Vuelta actual, empezando en 1. |
$loop->index | Vuelta actual, empezando en 0. |
$loop->first / $loop->last | ¿Primera o última vuelta? |
$loop->odd / $loop->even | ¿Vuelta impar o par? |
$loop->count | Total de elementos (null si no se pueden contar, como un generador). |
$loop->remaining | Cuántos quedan después de este. |
$loop->depth | Nivel de anidamiento (1 = bucle exterior). |
$loop->parent | El $loop del bucle exterior, en bucles anidados. |
Un patrón habitual: dar prioridad de carga solo a las primeras imágenes.
@foreach ($titles as $t)
{!! img($t['poster'], 'poster', ['alt' => $t['title'], 'priority' => $loop->iteration <= 2]) !!}
@endforeachLayouts y secciones #
Una página extiende un layout y rellena sus secciones:
{{-- templates/estrenos.tpl --}}
@extends('layout')
@section('content')
<main id="main" class="wrap">
<h1>{{ $heading }}</h1>
@include('partials/grid', ['titles' => $titles, 'lcp' => 8])
{!! pagination($pagination, '/estrenos') !!}
</main>
@endsection{{-- templates/layout.tpl (simplificado) --}}
<!DOCTYPE html>
<html lang="{{ $site['lang'] }}">
<head>
{!! $seo->render() !!}
<style>{!! inline_css('critical.css') !!}</style>
@hook('head')
</head>
<body>
@hook('body_open')
@hook('before_content')
@yield('content')
@hook('after_content')
@hook('footer')
@hook('body_close')
</body>
</html>| Directiva | Qué hace |
|---|---|
@extends('layout') | Esta plantilla se pinta dentro de layout.tpl. Lo que escribas fuera de las secciones se descarta. |
@section('nombre') … @endsection | Define el contenido de una sección. |
@section('nombre', $valor) | Sección corta en una línea. El valor se escapa. |
@yield('nombre', 'por defecto') | Imprime una sección (o el valor por defecto si nadie la definió). |
@section('nombre') … @show | En el layout: define un contenido por defecto y lo imprime en ese mismo sitio. |
@parent | Dentro de la sección de la página hija: inserta ahí el contenido que el layout definió con @section … @show. |
{{-- layout --}}
@section('sidebar')
<nav>{{ __('common.menu') }}</nav>
@show
{{-- página --}}
@section('sidebar')
@parent
<aside>Algo más</aside>
@endsectionLos layouts se pueden encadenar: una plantilla extiende title, que a su vez extiende layout. Así es season.tpl en Cinema: solo @extends('title').
Incluir parciales #
@include('partials/card', ['t' => $title, 'priority' => true])
@includeIf('partials/promo')- El parcial recibe todas las variables de la plantilla que lo incluye, más las que le pases (estas ganan). La excepción es
$loop, que no pasa al parcial: si lo necesitas, pásalo tú (['n' => $loop->iteration]). @includefalla si el parcial no existe.@includeIfno imprime nada en ese caso: úsalo para parciales opcionales que un child theme puede añadir.
Hooks en las plantillas #
| Directiva | Equivale a | Uso |
|---|---|---|
@hook('nombre', $arg1, …) | do_action('nombre', $arg1, …) | Un punto donde los plugins imprimen HTML. |
@filter('nombre', $valor, …) | echo apply_filters('nombre', $valor, …) | Un valor que los plugins pueden cambiar. Se imprime sin escapar: el valor de partida debe ser HTML seguro. |
<div class="acciones">
@hook('title_actions', $title)
</div>
<p class="aviso">@filter('mi_theme_aviso', e(__('mi_theme.aviso')), $title)</p>Si añades hooks propios a un theme, ponles un prefijo (mi_theme_…) y documéntalos. Los hooks que todo theme debe disparar (head, body_open, nav_items, before_content, after_content, footer, body_close, player_before, player_after) están en crear themes.
Traducciones #
{{ __('theme.watch_now') }}
{{ __('mi_theme.bienvenida', ['name' => $site['name']]) }}
{{ _n('common.seasons_count', count($seasons)) }}
@lang('mi_theme.bienvenida', ['name' => $site['name']])
{{ __('mi-plugin::boton') }}@lang(...) es lo mismo que {{ __(...) }}: imprime escapado. Si una clave no existe en el idioma de la página, se busca en el idioma por defecto del sitio, después en inglés y, si tampoco está, se imprime la clave.
Las traducciones se organizan distinto en themes y plugins:
| Extensión | Archivos | Cómo se piden |
|---|---|---|
| Theme | lang/es.php, lang/en.php… devuelven un array que se fusiona con las cadenas del núcleo. | Con punto: 'mi_theme' => ['bienvenida' => 'Hola'] → __('mi_theme.bienvenida'). Usa un grupo propio para no chocar con nadie. |
| Plugin (spec 1) | lang/es.php… registrados con $plugin->lang() en su propio dominio. | Con el dominio: __('mi-plugin::boton'). |
Como un theme se fusiona con el núcleo, también puede reescribir textos del núcleo: un lang/es.php con 'theme' => ['watch_now' => 'Reproducir'] cambia ese botón en todo el sitio. Los archivos del theme hijo se cargan después de los del padre, así que ganan.
PHP, JSON y formularios #
@php
$ap = $site['appearance'] ?? [];
$esSerie = ($title['type'] ?? '') === 'series';
@endphp
<script type="application/json" id="mi-datos">@json(['id' => $title['id'], 'url' => $title['url']])</script>| Directiva | Qué hace |
|---|---|
@php … @endphp | Bloque de PHP. Úsalo para preparar variables, no para lógica pesada: las consultas van en el controlador o en un filtro template_data. |
@json($valor) | JSON seguro para meter en HTML (escapa <, >, &, comillas). |
@csrf | <input type="hidden" name="_token"> del panel. En el sitio público no sirve (la página está en caché): ver formularios públicos. |
@method('PUT') | Campo oculto _method para enviar PUT o DELETE desde un formulario. |
Caché de fragmentos #
@cache('mi-theme:footer-generos:' . current_lang(), 3600)
<ul>
@foreach (app(\MovieMaster\Content\Repositories\TermRepository::class)->all('genre', null, 'name', 20, true) as $g)
<li><a href="{{ $g['url'] }}">{{ $g['name'] }}</a></li>
@endforeach
</ul>
@endcache@cache('clave', segundos) guarda el HTML del bloque en la caché de objetos (cache()) y lo reutiliza hasta que caduca. Sirve para trozos caros que se repiten en muchas páginas. La clave debe incluir todo lo que cambia el resultado (el idioma, como mínimo). Esta caché no se purga cuando cambia el contenido: elige tiempos cortos o usa claves que cambien solas.
Cómo se encuentran las plantillas #
Los nombres no llevan extensión y usan / para las carpetas:
| Nombre | Dónde se busca |
|---|---|
title, partials/card | templates/ del theme activo → su padre → Cinema (core/themes/default/templates). Gana el primero que exista. |
mi-plugin::caja | Carpetas registradas por el plugin con $plugin->views(__DIR__ . '/views'). |
admin::layout | Vistas del panel. |
Por eso un child theme solo necesita las plantillas que cambia: el resto llega del padre o de Cinema. Solo hay un nivel de padre; un theme hijo de un hijo no hereda del abuelo (pero siempre cae en Cinema).
Desde PHP se pinta con view('mi-plugin::caja', ['titles' => $items]), que devuelve el HTML como texto.
Variables disponibles #
Todas las plantillas públicas reciben:
| Variable | Contenido |
|---|---|
$site | name, tagline, url, lang, langs, appearance (colores, logo, CSS personalizado…), footer_pages, social_links. |
$seo | Objeto PageSeo de la página. {!! $seo->render() !!} imprime <title>, metas, canonical, hreflang y JSON-LD. |
$template | Nombre de la plantilla (home, title, episode…). Útil en el layout para marcar el menú activo. |
Las variables propias de cada página ($title, $titles, $pagination…) están en crear themes. Un plugin puede añadir o cambiar variables antes de pintar con el filtro template_data.
Compilación y depuración #
- Cada
.tplse compila a PHP encontent/cache/views/la primera vez y se vuelve a compilar cuando cambias el archivo. Conapp.debugactivo se compila siempre. php bin/console.php cache:clearborra las plantillas compiladas, la caché de objetos (incluidos los fragmentos de@cache) y la caché de páginas. Las compiladas y la caché de páginas también se borran al activar, desactivar o actualizar una extensión.- Un error en una plantilla queda en
content/logs/app.log.theme:checkcompila todas las plantillas del theme y pasaphp -lal resultado, así que los errores de sintaxis salen antes de publicar. - Escribe los bloques de PHP siempre como
@php … @endphp. No uses la forma corta@php(...): si después aparece un bloque@endphp, el compilador los junta y la plantilla se rompe. - Las directivas reconocen paréntesis anidados (
@if (in_array($x, ['a', 'b']))). Una@palabraque no es una directiva conocida se deja tal cual, así que un@mediadentro de<style>no da problemas.