Templatesyntax

Templates gebruiken shortcodes tussen [# en #].

Templates zijn bewust zonder logica. Een template is schone, eenvoudige markup: hij toont waarden, herhaalt een template voor een lijst en kiest hooguit welke template volgt ([#if … tpl=…#]). Beslissingen, berekeningen en datavoorbereiding staan in libraries, waar je ze op één plek kunt lezen en testen. Er zijn geen logicablokken, lussen met voorwaarden of expressies in templates, zoals engines als Twig of Blade die toestaan; logica in markup mengen is precies wat Nimbly vermijdt.

[#shortcode#]
[#shortcode param#]
[#shortcode key=value key2=value2#]

Shortcodes kunnen genest worden: elke parameterwaarde of shortcodenaam kan zelf een shortcode bevatten:

[#get data.users.[#get selected-id#]#]

Dat werkt ook in tpl=-parameters en shortcodenamen, waarmee je templatenamen dynamisch samenstelt:

[#if current_image=(not-empty) tpl=card-image[#if current_image=(empty) echo=-placeholder#]#]

Dit wordt tpl=card-image als er een afbeelding is, en tpl=card-image-placeholder als die er niet is.

Een bijzonder krachtige toepassing is kiezen op contenttype: zet een typeveld direct in de naam van de shortcode om zonder vertakkingen naar een template voor dat type te gaan:

[#card-[#get item.type#]#]

Dit wordt [#card-news#], [#card-event#], [#card-download#] enzovoort, afhankelijk van het type van het item. Dit patroon maakt ketens van [#if item.type=X tpl=Y#] overbodig en groeit netjes mee als er types bijkomen.

Gebruik default= om een geldige shortcodenaam te garanderen als de waarde kan ontbreken of onbekend kan zijn; een shortcode die niet gevonden wordt, verschijnt als letterlijke tekst in de uitvoer:

[#card-[#get item.type default=unknown#]#]

Maak [#card-unknown#] als algemene terugvaloptie (of laat hem leeg om niets te tonen).

Templates zijn gewone bestanden in het beoogde uitvoerformaat (HTML, JSON, CSS, enzovoort). Ze hebben de extensie .tpl.

Routetemplates

Elke URL hoort bij een bestand in ext/uri/:

ext/uri/index.tpl              → /
ext/uri/about/index.tpl        → /about/
ext/uri/blog/(slug)/index.tpl  → /blog/<anything>/

Een routetemplate maakt de pagina:

[#html#]

De main.tpl in dezelfde map bevat de body van de pagina, getoond binnen de HTML-shell. Die hoort altijd bij die route; zelfs ext/uri/main.tpl is alleen de body van de homepage (/), geen algemene layout.

Herbruikbare templates

Staan in ext/tpl/<name>/index.tpl. Je roept ze aan met hun naam als shortcode:

[#hero-section#]

Templates krijgen geen parameters rechtstreeks mee. Om data aan een template te geven, gebruik je [#set ... overwrite#] vóór de aanroep:

[#set back_url=/agenda overwrite#]
[#back-button#]

Lees de variabele in de template met [#get back_url default=/#]. Library-shortcodes (ext/lib/<name>/) werken anders: die krijgen $params en kun je met parameters aanroepen.

Naamgeving van templates

Geef elke herbruikbare template een naam met eerst het type, gevolgd door de route of het onderwerp waar hij bij hoort:

{type}-{route-or-subject}

Types en voorbeelden:

Subtemplates in een paginamap volgen dezelfde regel, eerst het type:

ext/tpl/page-projects/
  section-project-list.tpl
  card-project.tpl
  card-project-image.tpl

Zet het type nooit aan het eind (project-card, about-page). Met het type vooraan staan alle kaarten, alle secties en alle paginatemplates bij elkaar in het bestandssysteem.

Templates binnen een route

Templates kunnen ook los in een URI-map staan (niet in een submap). Dat zijn geen routes, maar deeltemplates die vanuit de index.tpl of main.tpl van die route worden gebruikt.

ext/uri/new/page-settings-fields.tpl   ← partial, not a route
ext/uri/new/index.tpl                  ← route
ext/uri/new/main.tpl                   ← route body

Belangrijk: een submap in ext/uri/ maakt altijd een nieuwe route. Een los .tpl-bestand in een URI-map is een deeltemplate voor die route.

route.inc

route.inc wordt alleen gebruikt voor dynamische routes: routes met (param)-segmenten in de URL die gematcht, gevalideerd en geaccepteerd of geweigerd moeten worden. Statische routes (gewone URL-paden zonder parameters) gebruiken geen route.inc; hun index.tpl wordt direct geladen.

Dynamische routes worden niet vanzelf gevonden. Elke route met een (param)-segment heeft ook een record in de resource .routes nodig, anders bereikt het request de route.inc nooit en volgt een 404. Zo heeft ext/uri/en/blog/(slug)/route.inc een .routes-record nodig met route: "en/blog/(slug)" en een passende order, meestal 200. Draai php core/cli/nimbly.php routes:sync om de bestanden ext/uri/**/route.inc te doorzoeken en ontbrekende .routes-records aan te maken.

Een route.inc staat naast index.tpl en bepaalt of het request bij deze route hoort:

<?php
$parts = router_match(__FILE__);
if ($parts === false) return;

$slug = $parts[0];
load_library('data');
load_library('util');

$records = data_read_index('articles', 'title_slug', md5_uuid($slug));
if (empty($records)) return;

set_variable_dot('record', reset($records));
router_accept();

Routerfuncties

Het standaardpatroon: roep router_match() aan, valideer het resultaat, laad en valideer de data, en roep alleen router_accept() aan als alles klopt. Mislukt er iets, doe dan gewoon return; het request valt door naar de volgende route of een 404.

Valideer alle invoer van de route aan de grens

Vertrouw geen enkele waarde die via een URL binnenkomt. Dat geldt voor dynamische padsegmenten, GET- en queryparameters, headers die de route gebruikt, en elke waarde uit het request die via het variabelensysteem van de templates binnenkomt. Geautomatiseerde scanners sturen standaard SQL-fragmenten, shellsyntax, padtraversals, te grote getallen en andere fuzzing naar elke publieke parameter, ook al gebruikt Nimbly geen SQL.

Valideer en normaliseer deze waarden in de route voordat je ze aan een library geeft of ze gebruikt in berekeningen, bij het opzoeken van resources, in bestandspaden, cachesleutels, redirects of commando's:

• Gebruik bij voorkeur een allowlist voor de exacte syntax die je accepteert; probeer niet bekende slechte fragmenten weg te halen.
• Controleer type, lengte, bereik en toegestane waarden waar dat van toepassing is.
• Zet gevalideerde getallen om naar int of float voordat je ermee rekent.
• Houd ruwe tekst uit het request buiten bestands- en cachepaden, tenzij de volledige syntax met een allowlist is gecontroleerd en bewust deel uitmaakt van de cachesleutel.
• Weiger ongeldige invoer meteen met het normale foutantwoord van de route. Routes voor assets die op een API lijken, mogen een lege HTTP 400 geven als foute invoer zichtbaar moet zijn voor rate limiting of botdetectie.
• Valideer zelf in PHP, ook als Apache, een proxy of een CDN dezelfde parameter al filtert; filtering aan de rand is een optimalisatie, niet de vertrouwensgrens.

Een queryparameter ratio voor een thumbnail moet bijvoorbeeld als begrensd positief decimaal getal worden gevalideerd en naar float worden omgezet voordat er met de afbeelding wordt gerekend. Een tekst als ratio=1' OR 1=1 mag nooit bij de berekening van een thumbnail of het aanmaken van een cachebestand komen.

Houd route.inc beperkt tot routinglogica: matchen, valideren, een variabele of twee zetten, accepteren of weigeren. Bedrijfslogica hoort in een library die vanuit index.tpl via een shortcode wordt geladen.

Voeg nooit een route.inc toe aan een statische route. Een statische route (zoals login/, about/) heeft geen (param)-segmenten en wordt altijd geaccepteerd; een route.inc zonder router_accept() geeft een 404. Moet er logica draaien op een statische pagina, zet die dan in een shortcode die vanuit index.tpl wordt aangeroepen, niet in route.inc.

route is een gereserveerde shortcodenaam. Er is geen shortcode [#route#] en die kan ook niet worden gemaakt. De bestandsnaam route.inc hoort alleen bij het routingsysteem.

---