Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Motor de plantillas (.tpl)

9 min de lectura 12 apartados

En esta página

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 #

SintaxisQué 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).
@@ifImprime @if literal.
@verbatim … @endverbatimTodo lo de dentro sale tal cual, sin compilar.
html
<h1>{{ $title['title'] }}</h1>
<p class="sinopsis">{{ str_limit($title['overview'], 200) }}</p>
{!! img($title['poster'], 'poster', ['alt' => $title['title'], 'priority' => true]) !!}

Condiciones #

html
@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
DirectivaEquivale a
@if (expr) · @elseif (expr) · @else · @endifif de PHP
@unless (expr) · @endunlessif (!expr)
@isset($var) · @endissetif (isset($var))
@empty($var) · @endemptyif (empty($var))
@hasSection('nombre') · @endif¿Alguna plantilla definió esa sección?

Bucles #

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

PropiedadValor
$loop->iterationVuelta actual, empezando en 1.
$loop->indexVuelta actual, empezando en 0.
$loop->first / $loop->last¿Primera o última vuelta?
$loop->odd / $loop->even¿Vuelta impar o par?
$loop->countTotal de elementos (null si no se pueden contar, como un generador).
$loop->remainingCuántos quedan después de este.
$loop->depthNivel de anidamiento (1 = bucle exterior).
$loop->parentEl $loop del bucle exterior, en bucles anidados.

Un patrón habitual: dar prioridad de carga solo a las primeras imágenes.

html
@foreach ($titles as $t)
  {!! img($t['poster'], 'poster', ['alt' => $t['title'], 'priority' => $loop->iteration <= 2]) !!}
@endforeach

Layouts y secciones #

Una página extiende un layout y rellena sus secciones:

html
{{-- 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
html
{{-- 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>
DirectivaQué hace
@extends('layout')Esta plantilla se pinta dentro de layout.tpl. Lo que escribas fuera de las secciones se descarta.
@section('nombre') … @endsectionDefine 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') … @showEn el layout: define un contenido por defecto y lo imprime en ese mismo sitio.
@parentDentro de la sección de la página hija: inserta ahí el contenido que el layout definió con @section … @show.
html
{{-- layout --}}
@section('sidebar')
  <nav>{{ __('common.menu') }}</nav>
@show

{{-- página --}}
@section('sidebar')
  @parent
  <aside>Algo más</aside>
@endsection

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

html
@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]).
  • @include falla si el parcial no existe. @includeIf no imprime nada en ese caso: úsalo para parciales opcionales que un child theme puede añadir.

Hooks en las plantillas #

DirectivaEquivale aUso
@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.
html
<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 #

html
{{ __('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ónArchivosCómo se piden
Themelang/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 #

html
@php
  $ap = $site['appearance'] ?? [];
  $esSerie = ($title['type'] ?? '') === 'series';
@endphp

<script type="application/json" id="mi-datos">@json(['id' => $title['id'], 'url' => $title['url']])</script>
DirectivaQué hace
@php … @endphpBloque 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 #

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

NombreDónde se busca
title, partials/cardtemplates/ del theme activo → su padre → Cinema (core/themes/default/templates). Gana el primero que exista.
mi-plugin::cajaCarpetas registradas por el plugin con $plugin->views(__DIR__ . '/views').
admin::layoutVistas 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:

VariableContenido
$sitename, tagline, url, lang, langs, appearance (colores, logo, CSS personalizado…), footer_pages, social_links.
$seoObjeto PageSeo de la página. {!! $seo->render() !!} imprime <title>, metas, canonical, hreflang y JSON-LD.
$templateNombre 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 .tpl se compila a PHP en content/cache/views/ la primera vez y se vuelve a compilar cuando cambias el archivo. Con app.debug activo se compila siempre.
  • php bin/console.php cache:clear borra 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:check compila todas las plantillas del theme y pasa php -l al 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 @palabra que no es una directiva conocida se deja tal cual, así que un @media dentro de <style> no da problemas.

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?