Files
slp-modular-cms/docs/hero-module.md
T

6.2 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 (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.

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: <!--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), 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__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/<omgeving>/shared/media && chmod 700 ~/apps/slpsoftware/<omgeving>/shared/media (voor ASF-test hetzelfde in zijn eigen map).
  2. In shared/env: Media__Directory=%h/apps/slpsoftware/<omgeving>/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)

./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 slaat een CMS over dat al een hero heeft (-Force vervangt), vraagt het wachtwoord interactief en gebruikt voor productie niets zonder Bryans go.

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.