Technisch artikel

Flexbox, CSS Grid en voetnoten in PDF vanuit Delphi

Stel dat een hoofdstuk in twee kolommen op de een-na-laatste regel van de linkerkolom een voetnootverwijzing zet. Een notitie van één regel heeft ongeveer 14 punten nodig onderin die kolom, en er zijn er nog maar 9 over. Beide voor de hand liggende uitkomsten zijn fout: de notitie toch tekenen en hij drukt over de lopende tekst heen, of alleen de notitie doorschuiven en hij belandt onder de rechterkolom, naast tekst waar hij niets mee te maken heeft. Een browser hoeft die afweging nooit te maken, want een webpagina heeft geen onderrand. Flexbox en CSS Grid zijn ontworpen onder dezelfde aanname, dus zodra rapport-HTML op pagina's van vaste grootte moet landen, heeft elk van beide een regel nodig voor wat er gebeurt als de box zonder hoogte komt te zitten

Een flex-dashboardrij in een box met vaste breedte

PDF Library for Delphi behandelt elk element met display: flex of display: inline-flex als een echte flexcontainer, dus een rij kaarten blijft een rij in plaats van in gestapelde blokken in te storten. Je tekent hem met DrawHTMLTextBox(Left, Top, Width, Height, HTMLText), dat een WideString teruggeeft: leeg wanneer alles paste, anders het deel dat nog ergens anders getekend moet worden

In de rijrichting krijgt elk item een basis, de basiswaarden en de gaten tussen items worden opgeteld, en wat er op de regel overblijft wordt uitgedeeld. Positieve ruimte gaat via flex-grow. Negatieve ruimte wordt teruggepakt door flex-shrink vermenigvuldigd met de basis van het item, wat de CSS-regel is en over een ogenblik een prettig neveneffect laat zien. Met flex-wrap gezet schuiven items naar een nieuwe regel zodra de volgende basis niet meer past, en elke regel verdeelt zijn eigen vrije ruimte. justify-content, align-items, align-content, gap en de -reverse-richtingen verplaatsen daarna alleen boxen die al gemeten zijn

Diagram van PDF Library for Delphi met flex-rijdimensionering: gemeten bases en grow-gewichten, gewogen verdeling van overgebleven ruimte per regel, en een alleen-verplaats-uitlijningspas die een dashboardrij van twee-één-één oplevert
Flex-sizing is één begrensde meetronde gevolgd door gewogen verdeling van de overgebleven ruimte; uitlijning verplaatst de gemeten boxen en triggert nooit opnieuw meten
uses
  SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  Html, Remainder: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetOrigin(1);          // oorsprong linksboven: Top groeit de pagina af
    Lib.SetPageSize('A4');

    // Percentagebases houden de 2:1:1-verhouding exact, gap inbegrepen
    Html :=
      '<div style="display:flex; gap:12px;">' +
      '<div style="flex:0 1 50%; background:#f4f6f8; padding:8px;">' +
        '<b>Revenue</b><br/>EUR 4,182,300</div>' +
      '<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
        '<b>Margin</b><br/>18.4%</div>' +
      '<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
        '<b>Backlog</b><br/>92 days</div>' +
      '</div>';

    Remainder := Lib.DrawHTMLTextBox(40, 40, 515, 120, Html);
    if Remainder <> '' then
      raise Exception.Create('Dashboard row needs more than 120 pt');

    Lib.SaveToFile('dashboard.pdf');
  finally
    Lib.Free;
  end;
end;

Reken het door voor de box van 515 punten. De gap van 12px wordt 9 punten, dus twee gaten kosten 18. De bases tellen op tot de volledige 515, wat met precies die 18 punten overschiet. Shrink wordt gewogen naar basis, dus de kaart van 50% geeft 9 punten terug en elke kaart van 25% geeft 4.5 terug, wat 248.5, 124.25 en 124.25 oplevert. De verhouding is nog steeds exact 2:1:1, en de code hoefde de gaten nooit met de hand af te trekken

Waarom komen gelijke flex: 1-items ongelijk uit de bus?

Omdat hun basis de breedte van hun content is. De renderer neemt een basis uit flex-basis, uit een lengte binnen de flex-shorthand (een waarde met pt, px, em of %), of uit width. Als geen daarvan een positieve lengte oplevert wordt de gemeten contentbreedte van het item zijn basis. Een kale flex: 1 en het browseridiom flex: 1 1 0 belanden allebei daar, want eenheidsloze 0 wordt niet als lengte gelezen. Gelijke groeifactoren tellen daarna gelijke hoeveelheden vrije ruimte op boven ongelijke startbreedtes

Schrijf hetzelfde dashboard met flex: 1 op elke kaart, dan begint de Revenue-kaart, wier zevencijferig bedrag zijn content de breedste van de drie maakt, breder dan de Margin-kaart en blijft hij na groei precies dat verschil breder, want elke kaart krijgt hetzelfde eenderde deel van wat er aan vrije ruimte overblijft. Voor werkbalken, taglijsten en knoppenrijen is dat vaak toch al de look die je wilt. Voor een dashboard niet. Alles dat moet aansluiten op een tabel erboven of eronder verdient expliciete percentage- of puntenbases met grow op 0, wat onze aanbeveling is en precies wat het voorbeeld doet: de drie kaarten landen dan op 248.5, 124.25 en 124.25 punten op elke pagina, wat de cijfers erin ook zeggen

De kolomrichting volgt dezelfde logica op de verticale as. De basis komt uit flex-basis of height, anders uit de gemeten contenthoogte, en vrije ruimte bestaat alleen wanneer de container een height opgeeft. Zonder die is de container precies zo hoog als zijn items en heeft justify-content niets te verdelen

Grid-tracks, plaatsing en spans

Voor display: grid leest PDF Library for Delphi grid-template-columns en grid-template-rows als vaste lengtes, percentages, fr-eenheden, repeat(n, track) en minmax(a, b). Vaste tracks en gaten worden van de beschikbare breedte afgetrokken, en de rest wordt gesplitst naar fr-gewicht. Een minmax()-track wordt gedimensioneerd naar zijn tweede argument, dus minmax(120px, 1fr) gedraagt zich als 1fr, en auto-, min-content- en max-content-tracks nemen elk één deel van de vrije ruimte

Diagram van PDF Library for Delphi met geaccepteerde grid-trackwaarden, deterministische bezettingsplaatsing waarbij opzettelijke overlapping is toegestaan, en een rij-overspannend item dat zijn hoogte gemiddeld over de gedekte rijen teruggeeft
Grid tracks accepteren lengtes, percentages, fr-eenheden, repeat en minmax, terwijl automatische plaatsing de bezettingsmatrix deterministisch doorloopt

Plaatsing is deterministisch. Autoplaatste items lopen het grid rij voor rij door (of kolom voor kolom met grid-auto-flow: column) en slaan cellen die al bezet zijn over. Een item met alleen een rij zoekt die rij af naar een vrije kolom; een item met alleen een kolom zoekt die kolom af naar beneden. Items met beide coördinaten gaan exact waar ze het zeggen, ook bovenop een ander item, en zo komt een badge over een kaart te liggen

Spans vragen één gewoonte. De renderer leest een span uit het deel na de schuine streep, als in grid-row: 1 / span 2, of uit grid-row-end: span 2 en grid-column-end: span 2. De kale grid-row: span 2 die browsers als hele waarde accepteren is geen van die spellingsvormen, dus houd de startrij en de schuine streep aan

// Inspectieblad: vaste labelkolom, twee flexibele kolommen
Html :=
  '<div style="display:grid; ' +
  'grid-template-columns:120pt repeat(2, 1fr); gap:6pt;">' +
  '<div style="grid-row:1 / span 2; background:#eef2ff;">' +
    'Site plan</div>' +
  '<div>Inspector</div>' +
  '<div>Date</div>' +
  '<div style="grid-column:2 / span 2;">Findings summary</div>' +
  '</div>';

Remainder := Lib.DrawHTMLTextBox(40, 180, 515, 260, Html);

In die box van 515 punten is de labelkolom 120 punten, de twee gaten kosten 12, en elke 1fr-kolom krijgt 191.5. De Site plan-cel heeft een rij maar geen kolom, dus hij landt in kolom 1 en beslaat rij 1 en 2. Inspector en Date vullen de rest van rij 1. De samenvatting heeft een kolom maar geen rij, dus de plaatsing zoekt kolom 2 af naar beneden, vindt rij 1 bezet en belandt in rij 2 over beide flexibele kolommen

Rijhoogtes komen uit de content. Omdat een overspannend item zijn gemeten hoogte gelijkmatig over de rijen verdeelt die hij dekt, en elke rij dan het grootste deel neemt dat een item erom vraagt, wordt de extra hoogte van een hoge cel over elke rij die hij raakt uitgesmeerd in plaats van op de eerste gedumpt. Een hoge Site plan-cel licht dus beide rijen een stukje in plaats van alleen de eerste uit te rekken en Findings summary in een gat te laten zweven

Containers verhuizen ongedeeld tussen boxen

Een flex- of gridcontainer wordt nooit over twee boxen gesplitst. Nooit. Als de hele container niet past in de ruimte die over is, gaan de container en alles erachter naar de teruggegeven rest, en omdat die rest precies is wat je aan de volgende box of de volgende pagina doorgeeft, opent de kaartenrij simpelweg het volgende frame met zijn gemeten geometrie intact. De helft van een KPI-tegel onderaan pagina 3 en de andere helft op pagina 4 is erger dan een gat, en dat is de ruil die deze regel maakt. Een container die hoger is dan een hele lege box is de uitzondering: hij wordt desondanks bovenaan die box getekend en loopt voorbij zijn onderrand, want geen latere box wordt groter

De praktische consequentie is dat je de hoogte van een container moet kennen voordat je hem aan een pagina toewijst. GetHTMLTextHeight(Width, HTMLText) meet zonder te tekenen, flex en grid inbegrepen

// GridHtml, Y en PageBottom horen bij je rapportcode
Needed := Lib.GetHTMLTextHeight(515, GridHtml);
if Y + Needed > PageBottom then
begin
  Lib.NewPage;
  Lib.SetPageSize('A4');
  Y := 40;
end;
Lib.DrawHTMLTextBox(40, Y, 515, Needed, GridHtml);
Y := Y + Needed + 12;

De meting is met opzet begrensd, wat telt wanneer klanten sjablonen bewerken. Een flex- of gridcontainer neemt zijn eerste 256 directe kinderen, gridplaatsing werkt binnen 64 rijen, en een tracklijst bevat hooguit 64 tracks, met repeat()-aantallen begrensd om dat te matchen. Een flexcontainer met honderden kinderen is bijna altijd een datatabel in vermomming, en het tabelpad, met zijn eigen kolommeting en rowspan-ondersteuning, zet hem toch beter neer

Hoe blijven voetnoten bij hun verwijzing?

PDF Library for Delphi meet elke notitie op het moment dat hij de verwijzing tegenkomt en trekt die hoogte af van het bodybudget van de huidige box. Een notitie wordt geschreven als <aside style="float:footnote">, <aside role="doc-footnote"> of een <footnote>-element. De verwijzing wordt een superscriptnummer op twee derde van de omliggende fontgrootte, en de notitietekst wordt gezet op 8 punten met 10-punts leading, voorafgegaan door hetzelfde nummer

Past de body tot nu toe plus de nieuwe notitie niet meer, dan verhuizen de markering en alles erna samen naar de rest. Notitie en verwijzing reizen als paar. Dat is het antwoord op het openscenario: de regel met de verwijzing en zijn notitie openen de volgende kolom, en noch de overprint noch de verweesde notitie kan gebeuren. In een begrensde box is het notitiegebied vastgepind aan de onderkant onder een dunne grijze lijn van een kwart van de boxbreedte. In onbegrende meting, zoals GetHTMLTextHeight, is er geen onderkant om aan vast te pinnen, dus de notities volgen de body direct

Diagram van PDF Library for Delphi met voetnootpaginering: het notitiegebied is gereserveerd onder een lijn onderaan zijn box, een notitie die niet past reist samen met zijn markering door naar de vervolgstring, en de nummering blijft doorlopend over pagina's
Voetnootruimte wordt uit het body-budget gesneden voordat er meer tekst stroomt, en de nummering overleeft kolommen en pagina's

De nummering begint bij 1 voor elke verse HTML-string. Het volgende nummer wordt binnen de remainder-string zelf bewaard, dus DrawHTMLTextBox-ketens en DrawHTMLStory houden één doorlopende reeks aan over kolommen en pagina's, mits de remainder exact wordt teruggegeven zoals hij werd geleverd. De vervolgstring opnieuw opbouwen vanuit je eigen brontekst herstart de telling

Chapter :=
  '<p>The bearing stayed within tolerance for the full six hours' +
  '<aside style="float:footnote">Ambient temperature held at ' +
  '21 &deg;C throughout the run.</aside> of the load test.</p>' +
  MoreChapterHtml;                 // de rest van je hoofdstuk

// 2 kolommen, 16 pt gutter, hooguit 20 pagina's; het verhaal voegt zelf pagina's toe
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode;          // een keer lezen: lezen reset hem

if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
  // verkeerde geometrie: Columns 1..64, MaxPages 1..10000, gutters smaller dan Width
else if Err = PDFLIB_ERROR_HTML_STORY then
  // twee frames achter elkaar zonder vooruitgang
else if Rest <> '' then
  // 20 pagina's gebruikt en er blijft tekst over: later verder met Rest
  ;

DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText) begint op de huidige pagina, vult de kolommen van links naar rechts, en voegt pagina's met dezelfde afmetingen toe tot de tekst op is of MaxPages is bereikt. Die drie uitkomsten uit elkaar houden is de reden om LastErrorCode te lezen vóór je de teruggegeven string test. Ongeldige argumenten geven de invoer ongewijzigd terug, wat er anders precies uitziet als een verhaal dat zonder pagina's kwam te zitten

De layout voeden vanuit echte content

Voor kolomtekst over meerdere kolommen bepaalt het kolom- en afbreekgedrag uit afbreken en gebalanceerde tekstkolommen hoe de stroom binnen elke kolom eruitziet. Komt de markup uit data in plaats van uit handgeschreven sjablonen, dan is de dataset-report-engine de route die hem genereert voordat flex en grid hem op de pagina arrangeren. Content die later weer uit de PDF moet, gaat via PDF exporteren naar Markdown en DOCX

HTML-layout met flex, grid en voetnoten, rapportgeneratie en semantische export worden geleverd in één library voor Delphi, C++Builder en Free Pascal. De productpagina van PDF Library for Delphi zet de rest van de HTML-renderer en de teken-API op een rij