- Een decode voor de hele set, per breedte eenmaal geschaald voor WebP en AVIF (6000x4000: 21,1 s -> 6,4 s per set) - Eigen limiet per set (Media:RenderSetTimeoutSeconds 600), harde limiet rond een foto, de renderer stopt nooit door een uitzondering, een mislukte foto wacht tot de volgende ronde en houdt de rij niet op - Logging per foto (start, per variant, einde, fout); voortgang per variant in de admin; nieuwe uitsnede na focuswijziging zichtbaar (oude afbeelding blijft, shimmer); knop Opnieuw proberen - Thema-script als /theme-init.js (CSP script-src 'self'), test en smoke-controle op inline scripts Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
9.1 KiB
Hero-module
Levend document (2026-11-16). De hero van een website (titel, tagline, lead, knoppen, afbeeldingen) staat in het CMS. Het CMS levert alleen inhoud; elke site houdt zijn eigen opmaak. Ontwerp en besluiten: aidlc-docs/features/hero-module/. Contract met de websites: aidlc-docs/features/hero-module/inception/requirements/site-contract-agreed-with-asf.md.
Wat beheer je
Admin > Hero (Owner en Administrator, module Hero):
- Titel (een nieuwe regel is een regelafbreking, maximaal 5 regels), tagline, lead, weergave (
singleofslideshow). - Maximaal twee knoppen met tekst en doel. Een doel is een
#anker, een/padof eenhttps://-adres; andere waarden worden geweigerd. - Planning (aan of uit, van en tot). Buiten de planning, of uitgezet, toont de website zijn eigen ingebakken hero.
- Slides: een afbeelding met verplichte beschrijving (alt-tekst) of de markering decoratief, volgorde, aan of uit per slide. Er is geen grens op het aantal slides; technisch publiceert de host er hoogstens
Hero:MaxPublishedSlides(50). - Focus: per afbeelding een algemeen punt en zoom, en optioneel een eigen punt voor de liggende (
wide, 3:2) en de staande (tall, 4:5) weergave. De host snijdt de varianten daaromheen uit. Een wijziging van het focuspunt geldt pas als je de hero opslaat (Bryan, 2026-11-16): het focus-venster houdt de wijziging lokaal in de admin (knop Toepassen, een markering bij de slide); bij Opslaan gaat ze mee in dezelfde aanvraag (imageFocus); de host bewaart hero en focus direct (onder een seconde) en snijdt de varianten daarna op de achtergrond in nieuwe bestanden. De afbeelding schakelt over naar de nieuwe set zodra die compleet is; tot die tijd blijft de oude set in beeld. Verlaat je de pagina zonder op te slaan, dan vervalt de wijziging en is er niets aan de server veranderd. Mislukt een opslag nadat nieuwe bestanden zijn geschreven, dan verwijst niets ernaar en ruimt de opschoning ze na 7 dagen op; de oude bestanden blijven ook 7 dagen staan voor sites die nog oude data hebben.
De admin toont alleen een badge Live of Niet live.
Wat de website krijgt
GET /api/v1/hero: anoniem,Cache-Control: public, max-age=60,204als er niets te tonen is (dan blijft de ingebakken hero staan). Dezelfde JSON staat onderheroin het datablok#cms-data.- Markers in de pagina:
<!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML-->(titel, tagline, knoppen, eerste slide als<picture>) en<!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD-->in de head (een of twee preload-links). Alleen WebP komt in de eerste afbeelding en de preload. Zonder bruikbare hero, bij een fout of als de bestanden van de eerste slide ontbreken blijft de pagina zoals gebouwd. - Afbeeldingen:
/media/hero/<set>/<ratio>-<breedte>.<webp|avif>, onder het eigen adres van de site (de CSP verandert niet),immutablegecachet; een andere focus geeft een nieuw adres. - De golden files van ASF (commit 13f78c4) leggen de HTML byte voor byte vast:
src/SlpModularCms.Modules.Hero.Tests/Golden.
Instellen op een host
| Instelling | Betekenis |
|---|---|
Media__Directory |
De map voor de afbeeldingen, buiten de release en buiten de webroot. Zonder deze instelling (of als de map niet beschrijfbaar is) staan uploads uit; bestaande bestanden en de publieke hero blijven werken. Niet in een committed appsettings-bestand. |
Media__MaxUploadBytes (10 MB), Media__MaxPixels (64 miljoen), Media__MaxParallelJobs (2), Media__DecodeTimeoutSeconds (20), Media__MaxTotalBytes (2 GB), Media__RetentionDays (7) |
Grenzen en bewaartijd; standaardwaarden zijn bedoeld om te blijven. |
Hero__TextOnlyRegion |
true voor een site waarvan de hero geen afbeeldingen heeft (SLP Software; staat in de committed instellingen van die site): een hero zonder slides wordt dan als tekst (titelregels, lead, knoppen) in de eerste HTML geschreven. Uit (standaard, ook voor ASF): een hero zonder slides laat de pagina ongemoeid. |
Hero__TitlePrefix |
Merktekst die in de tekst-only-regio als eerste, visueel te verbergen deel van de h1 wordt geschreven (<span class="cms-hero-title-prefix">), zodat crawlers en schermlezers de volledige titel lezen. SLP Software: "SLP Software: " (committed instelling); leeg (standaard, ook ASF) schrijft niets. De site verbergt de klasse zelf visueel. |
Media__RenderSetTimeoutSeconds (600), Media__StripTimeoutSeconds (60) |
De tijd die het knippen van alle varianten van één foto in de achtergrond mag duren, en het verwijderen van metadata bij een upload. Ruim gekozen: een grote foto op een Raspberry Pi kost minuten. |
Hero__MaxPublishedSlides |
Technische bovengrens op het aantal gepubliceerde slides (standaard 50). |
RateLimiting__HeroPublic, __MediaPublic, __HeroUpload |
Snelheidsbeleid (standaard 120 per 60 s, 600 per 60 s, 100 uploads per uur per gebruiker: een reeks van 8-10 foto's mag de limiet niet opmaken). |
Pi (test en later productie van SLP)
- Eenmalig, als het service-account:
mkdir -p ~/apps/slpsoftware/<omgeving>/shared/media && chmod 700 ~/apps/slpsoftware/<omgeving>/shared/media(voor ASF-test hetzelfde in zijn eigen map). - In
shared/env:Media__Directory=%h/apps/slpsoftware/<omgeving>/shared/media(let op: systemd verwacht een volledig pad; vervang%hdoor het thuispad als de EnvironmentFile dat niet uitbreidt). - De map hoort bij de back-up van de site (het back-upscript van de database neemt hem niet mee).
- Na de eerste deploy: kijk in het log naar
Image library Magick.NET self-test passed(met de lijst formaten). Staat daar een fout, dan zijn uploads uitgezet en is de bibliotheek op deze machine niet bruikbaar (linux-arm64 is niet vooraf getest). - Het deployartefact is ongeveer 35 MB groter door de beeldbibliotheek; meet de grootte bij de eerste deploy tegen de uploadlimiet van de proxy.
IIS (ASF-productie, later)
Een gegevensmap naast de site, buiten de webroot, waarin het account van de application pool mag schrijven. Of dat op MijnHostingPartner kan, is nog niet getest (Bryan test het met ASF). Faalt het, dan komt er een opslag in de database achter dezelfde koppeling (IMediaStore). De self-contained win-x64-publish bevat alleen Magick.Native-Q8-x64.dll.
Startinhoud (alleen test)
./scripts/Seed-Hero.ps1 -BaseUrl https://test.andreaslop.nl -ImagesDirectory <web/src/assets van de ASF-repository>
./scripts/Seed-Hero.ps1 -BaseUrl https://test.slpsoftware.nl -SeedFile ./scripts/hero-sls.json
hero-asf.json bevat de 8 huidige foto's met alt-teksten en een eerste schatting van de focuspunten (door de ASF-sessie); Bryan past ze aan in de admin. hero-sls.json is de huidige SLP-hero (alleen tekst, twee knoppen). Het script uploadt eerst alle foto's (de varianten worden daarna op de achtergrond gemaakt; het script wacht tot alles klaar is) (dezelfde foto is dezelfde afbeelding, dus een tweede run dupliceert niets) en slaat dan de hero in een keer op, met de focuspunten in dezelfde aanvraag (imageFocus): een focuspunt geldt pas bij het opslaan van de hero. Het slaat een CMS over dat al een hero heeft (-Force vervangt), vraagt het wachtwoord interactief (alleen voor een lokale host of testrun leest het SEED_HERO_PASSWORD) en gebruikt voor productie niets zonder Bryans go. Getest op PowerShell 7 en Windows PowerShell 5.1 tegen een lokale host, met de ASF-seed en hero-sls.json.
Wat er achter de schermen gebeurt
- Verwerking op de achtergrond: een upload bewaart het origineel en geeft direct antwoord (
processing: true, nog geen varianten, de afbeelding wordt niet gepubliceerd);HeroRenderServiceknipt de varianten, een afbeelding per keer (op een Raspberry Pi 4 ongeveer 25-30 s per foto), en pikt bij het opstarten en elke minuut werk op dat nog openstaat. Daardoor kapt de proxy-time-out (60 s) nooit een upload of een opslag af, en laat een afgebroken verzoek niets half bewaard achter (bestanden eerst, rij als laatste; een herhaling doet het gewoon opnieuw). De admin ververst zelf zolang er afbeeldingen worden verwerkt. - Upload: echt bestandstype aan de inhoud (geen SVG), grenzen op bytes, pixels, tijd en gelijktijdigheid; metadata (GPS) uit het opgeslagen origineel en alle varianten; varianten per verhouding rond het focuspunt, nooit groter dan de bron, in WebP (en AVIF waar het platform dat kan). Dezelfde foto nog een keer is hetzelfde plaatje (en herstelt verloren bestanden).
- Oude bestanden (nieuwe focus, vervangen of ongebruikte foto) blijven 7 dagen en worden dan opgeschoond; een bestand dat nog gebruikt wordt, verdwijnt nooit.
- Ondersteunde invoer: JPEG, PNG, WebP, GIF, BMP, TIFF en AVIF; HEIC alleen als aangegeven mogelijkheid van de bibliotheek (nog niet met een echt bestand getest).
Controleren na een deploy
scripts/smoke-site.sh(in de CI na elke test-deploy): moduleHerogeladen,GET /api/v1/herois 200 of 204, het beheer is beschermd, een niet-bestaand mediaadres is een gewone 404.- LCP: Lighthouse (mobiel profiel) op de testsite vóór en na het plaatsen van de markers in de website; de LCP van de gerenderde pagina mag niet slechter zijn dan die van de ingebakken pagina en de hero veroorzaakt geen layoutverschuiving (
widthenheightstaan op de afbeelding). Zierelease-checklist-productie.md.