Importar un tema

Un tema es una carpeta de páginas Blade que el equipo copia a su sitio en un solo paso. Esta guía cubre las páginas que recibe un equipo nuevo, la pantalla de importación y el formato de la carpeta de un tema, para cuando incluyas los tuyos.

Con qué empieza un equipo nuevo

Cuando se crea un equipo, un trabajo en cola copia en él el tema por defecto: un layout, una página de inicio, una página de contacto con un formulario que funciona y una página de categoría. Las páginas quedan ligadas al layout y activas, así que el dominio del equipo muestra un sitio antes de que alguien escriba una línea. No es un sitio terminado: la página de categoría usa el tipo de plantilla de ejemplo SomethingCategory, que lee registros que ningún equipo tiene, así que abrirla responde con un error. Reemplázala, o cambia su tipo de plantilla, antes de publicar (consulta Tipos de plantilla y categorías).

Ese tema por defecto viene con el producto, y quien lo instala puede cambiarlo (consulta Para desarrolladores abajo). Los equipos que ya existen conservan las páginas que tienen.

Importar un tema

El equipo abre Importar tema en la pantalla de páginas. Cada tema se muestra con su nombre, su descripción, su autor, su versión, hasta tres de las funciones que enlista su metadata y sus colores. El tema por defecto aparece primero, marcado como Predeterminado.

1. Haz clic en el tema para seleccionarlo.
2. Haz clic en Importar tema y confirma.

El layout se importa primero y todas las demás páginas del tema se ligan a él; solo se importa el primer archivo marcado como layout. Cada archivo se busca entre las páginas del equipo por su slug: una página cuyo slug ya existe en el equipo se sobrescribe con la versión del tema, y una que había sido borrada se restaura primero. Un archivo del tema sin slug no coincide con ninguna página, así que cada importación crea una página nueva para él, con una dirección hecha a partir de su título. Las páginas del equipo que el tema no tiene se quedan como están. El tema queda guardado como el tema actual del equipo.

La confirmación indica que las páginas con el mismo slug que una página del tema se reemplazan por la versión del tema y que las demás páginas del equipo se conservan.

El layout del tema por defecto tiene el slug layout, así que volver a importar el tema por defecto actualiza la página layout del equipo en vez de crear otra. Los layouts de más que crearon importaciones anteriores (layout-1, layout-2, …) se quedan como están: bórralos desde la pantalla de páginas si el equipo no los usa.

Crea un respaldo de cualquier página que hayas editado a mano antes de importar: la sobrescritura no guarda uno por ti. Consulta Páginas y layouts.

Para desarrolladores

Cambiar el tema por defecto

El tema por defecto vive en resources/views/stubs/themes/default/. Cambia esos archivos y cada equipo creado después empieza con tu versión; los equipos que ya existen conservan las páginas que tienen. La pantalla de importación está en /team/import-theme.

Agregar un tema propio

Cada carpeta dentro de resources/views/stubs/themes/ es un tema, y aparece en la pantalla de importación sin registrarla. La carpeta de un tema contiene:

resources/views/stubs/themes/restaurant/
├── metadata.json
├── layout.blade.php
├── home.blade.php
├── menu.blade.php
└── components/
    └── dish-card.blade.php

metadata.json describe el tema en la pantalla de importación:

{
    "name": "Restaurant",
    "description": "A menu, a home page and a booking form.",
    "author": "Your company",
    "version": "1.0.0",
    "is_default": false,
    "features": ["Menu by category", "Booking form", "Opening hours"],
    "color_scheme": {
        "primary": "#4F46E5",
        "secondary": "#059669"
    }
}

Sin ese archivo se usa el nombre de la carpeta como nombre del tema. is_default: true pone el tema primero en la lista, y color_scheme solo muestra los dos colores en la tarjeta: no cambia las páginas.

Cada archivo Blade empieza con un comentario que contiene los datos de su página en JSON. Un archivo sin él, o sin title, se omite:

{{--
{
  "title": "Menu",
  "slug": "menu",
  "seo_title": "Our menu",
  "seo_description": "Everything we cook, by category."
}
--}}
<section class="max-w-4xl mx-auto py-16">
    <h1 class="text-4xl font-bold">{{ $page->title }}</h1>
</section>

Los archivos dentro de una subcarpeta components/ también se importan como páginas, con el mismo encabezado. Solo el tema por defecto se copia en los equipos nuevos; los demás solo se alcanzan desde la pantalla de importación.

Revisar un tema antes de importarlo

Corre php artisan theme:validate {theme} desde la raíz del proyecto, con el nombre de la carpeta del tema, cada vez que agregues o cambies un tema y antes de que un equipo lo importe:

php artisan theme:validate restaurant

Lee el metadata.json de la carpeta y cada archivo Blade de la carpeta y de su subcarpeta components/, muestra lo que encontró y enlista errores y advertencias. No cambia nada.

Reporta un error cuando la carpeta no existe; cuando metadata.json falta, no es JSON válido o no tiene name, description o author; cuando la carpeta no tiene archivos Blade; cuando el comentario de datos de un archivo no es JSON válido o no tiene title o slug; cuando más de un archivo tiene "is_layout": true, o ninguno lo tiene; y cuando ningún archivo tiene comentario de datos. Advierte cuando metadata.json no tiene version, cuando dos archivos comparten slug y cuando un archivo no tiene comentario de datos.

Cualquier archivo sin slug es un error, el layout incluido. El tema por defecto pasa: php artisan theme:validate default no reporta errores.

Es más estricto que la pantalla de importación, que importa un tema sin metadata.json, sin layout o con archivos sin slug. El comando termina con código de salida 0 cuando no hay errores y 1 cuando los hay.