# 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 (`single` of `slideshow`). - Maximaal twee knoppen met tekst en doel. Een doel is een `#anker`, een `/pad` of een `https://`-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 snijdt dan de varianten opnieuw in nieuwe bestanden en bewaart hero en afbeeldingen in één keer. 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`, `204` als er niets te tonen is (dan blijft de ingebakken hero staan). Dezelfde JSON staat onder `hero` in het datablok `#cms-data`. - Markers in de pagina: `…` (titel, tagline, knoppen, eerste slide als ``) en `…` 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//-.`, onder het eigen adres van de site (de CSP verandert niet), `immutable` gecachet; 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__MaxPublishedSlides` | Technische bovengrens op het aantal gepubliceerde slides (standaard 50). | | `RateLimiting__HeroPublic`, `__MediaPublic`, `__HeroUpload` | Snelheidsbeleid (standaard 120 per 60 s, 600 per 60 s, 20 per uur per gebruiker). | ### Pi (test en later productie van SLP) 1. Eenmalig, als het service-account: `mkdir -p ~/apps/slpsoftware//shared/media && chmod 700 ~/apps/slpsoftware//shared/media` (voor ASF-test hetzelfde in zijn eigen map). 2. In `shared/env`: `Media__Directory=%h/apps/slpsoftware//shared/media` (let op: systemd verwacht een volledig pad; vervang `%h` door het thuispad als de EnvironmentFile dat niet uitbreidt). 3. De map hoort bij de back-up van de site (het back-upscript van de database neemt hem niet mee). 4. 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). 5. 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) ```powershell ./scripts/Seed-Hero.ps1 -BaseUrl https://test.andreaslop.nl -ImagesDirectory ./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 (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 - 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): module `Hero` geladen, `GET /api/v1/hero` is 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 (`width` en `height` staan op de afbeelding). Zie `release-checklist-productie.md`.