Themecontracten en assets

Presentatie heeft een eigen grens

Een Theme bepaalt de vormgeving van de winkel en kan ook de Adminpresentatie leveren. Het bepaalt geen prijzen, kent geen rechten toe, reserveert geen voorraad en markeert geen betalingen als betaald. Die handelingen blijven in Coreservices en Module- of Extensioncontracten. Templates tonen de gegevens en acties die applicatieschermen aanleveren.

ThemeManager ontdekt mappen onder themes/. De instelling appearance.active_theme kiest het actieve Theme. Als het ingestelde ID niet bestaat, volgt Default of een ander geïnstalleerd Theme. Activeren wijzigt een instelling en gebruikt geen migratielevenscyclus zoals een Module.

Begin bij het echte ontwikkelskelet

php artisan agovena:make-theme studio

De generator schrijft alleen themes/studio/theme.json. Hij kopieert geen Default-views, CSS, instellingenschema of Vite-invoer. Alleen een gegenereerd manifest vormt dus nog geen bruikbaar winkeltheme.

Een illustratief aangevuld manifest:

{
  "id": "studio",
  "name": "Studio",
  "version": "0.1.0",
  "description": "Een eigen winkelpresentatie.",
  "css": "themes/studio/resources/css/theme.css",
  "preview": "preview.png",
  "capabilities": ["storefront"]
}

De runtimevelden zijn id, name, version, description, css, optioneel admin_css, optioneel preview en capabilities. Ontbrekende of lege CSS wordt themes/<id>/resources/css/theme.css. Met css: null schakel je CSS dus niet uit. Previewpaden zijn relatief aan de Thememap. capabilities geeft presentatiemogelijkheden aan en staat los van productcapabilities.

Voor Admin-ondersteuning voeg je admin toe aan capabilities, lever je de benodigde Admin-views en stel je admin_css in op de eigen Admin-entry. Het werkelijke Default-manifest bevat zowel storefront als admin, plus de ondersteunde presentatiefuncties.

Bronnen: ThemeManifest en Default-manifest.

Contract voor Blade-views

$theme->view('catalog.index') retourneert theme::catalog.index. De serviceprovider koppelt theme:: aan de views/-map van het actieve Theme. Lever de views die de ingeschakelde applicatieschermen opvragen. Deze registratie biedt geen algemene overervingsketen waarin ontbrekende bestanden automatisch uit Default worden gehaald.

Een bruikbare implementatie-inventaris is:

themes/studio/
  theme.json
  settings.schema.php
  resources/css/theme.css
  views/layouts/storefront.blade.php
  views/layouts/checkout.blade.php
  views/catalog/...
  views/checkout/...
  views/account/...
  views/pages/...
  views/partials/...
  views/errors/...

Lees de render()-methode van ieder scherm voor de exacte viewnaam en variabelen. CategoriesIndex gebruikt bijvoorbeeld catalog.categories met categories, theme en themeConfig, gevolgd door layouts.storefront. CheckoutPage gebruikt checkout.index en layouts.checkout; de component levert regels, totalen, vereisten en interactietoestand.

Behoud de relevante Livewire-bindings en acties wanneer je markup vervangt. De referentielayouts bevatten ook CSRF-metadata, taal, branding, toestemming, navigatie en assetintegratie. Die onderdelen verwijderen om een visueel eenvoudiger template te maken kan echt gedrag breken. Bekijk de Default-winkellayout.

Optionele Modules kunnen eveneens accountviews uit het Theme opvragen. Test de capabilitycombinaties die je ondersteunt, niet alleen de homepage. Een capabilitystring in theme.json levert niet vanzelf een ontbrekende view.

Terugval voor Admin

ThemeManager::themeFor(ThemeSurface::Admin) kiest het actieve Theme als het Admin aanbiedt. Anders wordt Default gekozen als dat Admin ondersteunt. AgovenaServiceProvider plaatst de viewmap daarvan vóór de overige Adminlocaties. Daardoor blijft de standaard-Admin beschikbaar voor een Theme dat alleen de storefront verzorgt.

Een Adminpresentatie moet de bestaande beheercontracten behouden: navigatie, bevoegdheidsgebonden acties, fouten, tabellen, formulieren en laadstatussen. Verborgen knoppen vervangen geen serverautorisatie. Importeer geen providerlogica in een Theme alleen om een label of status te tonen.

Vormgevingsinstellingen

settings.schema.php mag een ThemeSettingsSchema of een array met ThemeSettingField-instanties retourneren. Een veld beschrijft key, label, type, default, group, optioneel help, optioneel options en sort.

Dit veldpatroon wordt ook door Default gebruikt:

<?php

use App\Agovena\Theme\ThemeSettingField;
use App\Agovena\Theme\ThemeSettingsSchema;

return new ThemeSettingsSchema([
    new ThemeSettingField(
        key: 'appearance.default_color_mode',
        label: 'admin.appearance.theme_fields.appearance.default_color_mode',
        type: 'select',
        default: 'system',
        group: 'appearance',
        options: ['system', 'light', 'dark'],
        sort: 10,
    ),
]);

ThemeConfig leest eerst opgeslagen waarden uit theme.<id>, daarna schemastandaarden en ten slotte de terugvalwaarde van de aanroeper. Met bool() en string() lees je getypeerde waarden. Dit is presentatieconfiguratie, geen versleutelde opslag voor providercredentials.

De normalisatie van homepaginasecties kent een expliciete lijst: hero, featured_products, featured_categories, trust_strip, promo_split en rich_text. Tekst wordt van tags ontdaan en begrensd, links worden gefilterd en mediapaden beperkt. Een nieuw sectietype vereist implementatie en validatie, niet alleen een nieuwe JSON-waarde.

Bronnen: Default-instellingenschema, ThemeSettingsSchema en ThemeConfig.

Assetcontract

vite.config.js bevat expliciete invoerbestanden. Een nieuw Thememanifest voegt niet automatisch een buildentry toe. Voeg bij je implementatie de eigen CSS en eventuele JavaScript-entry toe aan de buildconfiguratie. Verwijs er vervolgens in de layout naar via Laravel Vite.

@vite([$theme->cssEntry, 'resources/js/storefront.js'])

Laat een productiestylesheettag niet rechtstreeks naar een ongebouwd bronpad wijzen. Manifestpad, Vite-entry en layoutverwijzing moeten overeenkomen, inclusief hoofdletters. Controleer de productiebuild, niet alleen de Vite-ontwikkelserver.

De Default-CSS-entry importeert tokens, reset, een gedeelde kaartcomponent, winkel- en checkoutcomponenten, toestemming, foutpagina's en toegankelijkheidsutilities. Volg de native CSS- en ITCSS-indeling. Behoud bestaande component- en statusklassen wanneer je hun gedrag hergebruikt. Themevariabelen gebruiken --theme-*; gedeelde Adminonderdelen hebben daarnaast een eigen contract. Vervang de bestaande stijlstructuur niet door een utilityframework alleen omdat je dat gewend bent.

Foutpagina's en veerkracht

Een Theme kan views/errors/<status>.blade.php leveren. De selectie probeert eerst het actieve Theme en daarna Default voor precies die status. De renderer accepteert foutstatussen van 400 tot 599, levert status, theme en een mogelijk null themeConfig, en behoudt de oorspronkelijke HTTP-status.

ThemeErrorRenderer behandelt JSON-, authenticatie- en validatie-exceptions niet via dit HTML-pad. Fouttemplates moeten zonder instellingen kunnen werken en statische CSS-terugvalwaarden gebruiken. Roep niet opnieuw de falende applicatieservice aan alleen om een storingspagina aan te kleden.

Verificatie

php artisan test tests/Feature/ThemePlatformTest.php
php artisan test tests/Feature/ThemeAdminSurfaceTest.php
php artisan test tests/Feature/ThemeErrorPagesTest.php
npm run build

Controleer daarnaast in de browser mobiele en desktopbreedtes, beide kleurmodi, toetsenbordbediening, veldfouten, uitgeschakelde knoppen, winkelwagenupdates, checkout, klantpagina's en ondersteunde Moduleviews. PHP-tests gebruiken withoutVite() in de basistestklasse. Alleen geslaagde PHP-tests bewijzen daarom niet dat productieassets werken. Zie bijdragen voor browsertests.