Een leeg Comments-veld op een XFA-claimformulier heropent met een line feed erin. Sla je opnieuw op en heropent nog een keer, dan bevat het veld er twee. Een klantnaam met U+1F642, het licht glimlachende gezichtje, komt terug als U+F642, een codepunt uit het private use area dat de meeste fonts als een leeg rechthoekje tekenen. Alle drie de effecten zitten in de XML die een XFA-opslag in het datasets-pakket schrijft, en een opslagpad dat ze goed doet, moet lay-outwitruimte buiten veldwaarden houden, tekens uit het aanvullende vlak als complete surrogate pairs vervoeren, en een mislukte schrijfactie via de save-uitkomst melden in plaats van via een beschadigd bestand
Welke PDFium-runtime slaat XFA-waarden op?
Alleen pdfium.v8.dll slaat XFA-waarden op, want het is de enige PDFium Component-build die zowel de V8-JavaScript-engine als de XFA-formulioruntime meebrengt. Zodra een bewerking is vastgelegd (het veld verloor de focus, of ClearFormFieldFocus dwong de vastlegging af), exporteert die runtime bij het opslaan de live XFA-data naar het datasets-pakket, zonder dat je zelf pakketten bewerkt. Elke Windows-architectuur levert daarnaast pdfium.dll, gebouwd zonder V8 en XFA, die de opgeslagen pakketten exact terugschrijft zoals hij ze heeft gelezen. Wat er gebeurt met een waarde die wordt weggeschreven terwijl het veld nog focus heeft, staat in waarom XFA-veldbewerkingen bij opslag verdwijnen
De Delphi-wrapper probeert de juiste bibliotheek voor je te kiezen. Is EnableV8Engine nog False en is er nog geen PDFium-bibliotheek geladen, dan kijkt TPdf naar het bestand dat hij gaat openen, en vindt hij XFA-markeringen (een /XFA-entry in het AcroForm-dictionary, of /NeedsRendering true in de catalog), dan zet hij EnableV8Engine aan voor het laden. Die schakelaar werkt maar een keer per proces. Is er al een gewone pdfium.dll aanwezig omdat het eerste document van de sessie een gewone PDF was, dan blijft het proces daaraan verbonden, en gaat TPdf.OnXfaRuntimeMissing af zodra er later een XFA-document aankomt
De standaard zoekvolgorde is de andere helft van het probleem. Zonder map in LibraryName begint de loader bij een map DLLs\Win32 of DLLs\Win64 onder de applicatiemap of een van zijn voorouders, dus er kan eerst een oudere pdfium.v8.dll worden gevonden. Een LibraryName met een map erin pind exact dat bestand, en ontbreekt het, dan mislukt het laden
uses
System.SysUtils, PDFium;
procedure SelectXfaRuntime;
begin
// Een map in LibraryName pind exact dit bestand;
// een ontbrekend bestand laat LoadLibrary mislukken in plaats van elders te zoeken
{$IFDEF WIN64}
PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win64\pdfium.v8.dll';
{$ELSE}
PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win32\pdfium.v8.dll';
{$ENDIF}
PDFium.EnableV8Engine := True;
PDFium.LoadLibrary; // faal bij de opstart, niet bij de eerste XFA-opslag
end;
Als een document eenmaal open is, zegt TPdf.XFA dat het bestand XFA bevat, en TPdf.XfaRuntimeAvailable zegt dat de geladen bibliotheek de XFA-engine voor dit document echt kon starten. Statische en dynamische formulieren worden uit elkaar gehouden via TPdf.FormType, dat ftXfaFull geeft voor een dynamisch formulier en ftXfaForeground voor een statisch. Pakketniveau-probing op een machine zonder de V8-runtime is het onderwerp van XFA-formulieren detecteren en XFA-pakketten extraheren in Delphi
Waarom kunnen opgeslagen XFA-velden extra line feeds krijgen?
Opgeslagen XFA-velden krijgen line feeds wanneer de writer zijn XML pretty-print met een newline na elke starttag. Bij een XFA-opslag zijn twee writers betrokken, de generieke XML-elementwriter en de serializer van het formulierpakket, en beide formatteren hun uitvoer gewoontegetrouw zo. In de meeste XML-documenten is die witruimte cosmetisch. In XFA-data is het de waarde: wordt het datasets-pakket opnieuw geparsed, dan hoort elk teken tussen <Comments> en </Comments> bij het veld, de newline inbegrepen
Een leeg veld heropent dus met een LF. Elke volgende opslag formatteert rond de LF die er al staat, dus een veld dat niemand aanraakt groeit met een regel per beoordelingsronde
Waarden bij het laden afkappen lijkt een goedkope reparatie, en het zou echte data corrumperen. Mensen typen voorloopspaties, volgspaties en opzettelijke regeleinden in XFA-velden; een adresblok moet zijn regelstructuur houden, en een referentiecode met vaste breedte moet byte voor byte overleven. De XFA-writers in PDFium Component laten in plaats daarvan alleen de witruimte vallen die de serializer zelf rond tags synthetiseert. Gebruikerswaarden, tekstknooppunten die al in het bestand stonden en CDATA-secties gaan onveranderd door, dus " indented" blijft ingesprongen en een opzettelijk leeg veld blijft leeg
Emoji, surrogate pairs en een 16-bits wchar_t
Een emoji komt terug als een ander teken wanneer een decodeerpad een volledige Unicode-scalarwaarde in een enkele wchar_t opslaat, die op Windows 16 bits breed is. Twee plaatsen in een XFA-lading zijn eraan blootgesteld: de UTF-8-streamdecoder, en de parser voor numerieke tekenreferenties zoals 🙂. U+1F642 heeft 17 bits nodig. Proptest hem in 16, dan valt de bovenste bit weg en blijft U+F642 over in het private use area
Een formulierserializer kan ook de andere kant op falen. Filtert hij tekens per wchar_t, dan ziet hij twee surrogaatcode-eenheden, D83D en DE42, die elk op zichzelf ongeldig zijn, en gooit beide weg. De emoji verdwijnt uit het formulierpakket, zonder vervangend teken achter te laten
In PDFium Component consumeert de decoder elke scalarwaarde volledig en emitteert hij een correct surrogate pair, ook als de uitvoerbuffer nog maar ruimte voor een eenheid heeft en ook als een UTF-8-reeks van vier bytes over twee leesblokken is verdeeld. Naar buiten toe houdt de formulierexporteerder geldige surrogate pairs bij elkaar, en numerieke tekenreferenties decoderen ook naar correcte paren
Latin-1-testdata raakt geen van deze paden. Een round-trip-test voor een XFA-formulier heeft minstens een teken boven U+FFFF in een tekstveld nodig, en het controleren van de opgeslagen bytes op de UTF-8-reeks van vier bytes F0 9F 99 82 zegt meer dan naar het gerenderde veld kijken
Single-stream XFA en de save-uitkomst
Een single-stream XFA-document houdt zijn bewerkingen alleen vast als het opslagpad een XDP-stream ter plekke kan herschrijven, en elke input die hij niet kan herschrijven moet de opslag laten falen. ISO 32000-1 §12.7.8 staat in het interactive-form-dictionary voor de /XFA-entry zowel een array toe die pakketnamen en streams afwisselt als een enkele stream met het hele XDP-document. Een opslagpad dat alleen voor arrays is geschreven, wijst single streams af, en negeert de aanroeper die uitkomst, dan wordt de PDF weggeschreven met de formulierdata op de oude waarden
De V8-runtime in PDFium Component behandelt een gedefinieerde single-stream-subset in drie stappen. Hij exporteert beide live-pakketten, datasets en form, naar een staging-gebied en valideert ze. Pas daarna vervangt hij de overeenkomende pakketten binnen de originele XDP, waarbij hij de overige pakketten en de root-naamruimtedeclaraties vasthoudt. Mislukt de staging, dan wordt de persistente XFA-stream nooit aangeraakt en houdt het document zijn wijzigingsmarkering, zodat een latere opslag het opnieuw kan proberen
XML-comments en processing instructions vragen extra aandacht, want de parser die voor de herschrijving wordt gebruikt, laat ze vallen. Elk ervan wordt voor het parsen omgewisseld voor een unieke marker en daarna teruggezet, en de stream wordt alleen weggeschreven als elke marker exact een keer voorkomt, zodat comments buiten de live-pakketten hun tekst en volgorde houden
Sommige inputs worden ronduit geweigerd, en elke weigering bereikt je als mislukte opslag:
- Comments of processing instructions binnen de live
datasets- ofform-pakketten, want er is geen manier om hun oorspronkelijke posities in vers geëxporteerde inhoud te mappen - DTD-declaraties en XMLDSig-handtekeningen, want het herschrijven van de XDP kan een XML-handtekening niet geldig houden
- Ongeldige UTF-8 of UTF-16, onvolledige tags, ongeldige tekenreferenties, onbekende entities en misvormde processing instructions, die worden geweigerd in plaats van on-the-fly gerepareerd
Weigeren is hier de betere afweging. Een opslag die False geeft, kan opnieuw worden geprobeerd, gelogd of aan een mens worden overgelaten, terwijl een XDP die stilletjes genormaliseerd werd weken later een handtekening of een stroomafwaartse importer kan breken, ver weg van de code die het veranderde. Wat het single-stream-pad wel bewaart, is het XML-contentmodel, geschreven als UTF-8; de oorspronkelijke bytelay-out en de encoding-declaratie van de bronstream worden niet overgezet
Het laatste gebufferde blok
De laatste valkuil zit onder XFA, in de generieke PDF-writer. Een file writer die uitvoer bufferen in blokken van vaste grootte, moet aan het einde het laatste partiele blok naar buiten duwen. Gebeurt dat in opruimcode nadat de documentwriter al succes heeft gemeld, dan bereikt een volle schijf of een I/O-fout op het laatste blok nooit de aanroeper, en is het bestand op schijf te kort. In beide PDFium Component-runtimes hoort de laatste flush bij de save-uitkomst, en de XFA-wijzigingsmarkering wordt pas gewist als de schrijfactie echt is gelukt
De Delphi-kant voegt nog een laag toe. TPdf.SaveAs schrijft naar een tijdelijk bestand naast de target en verplaatst het er alleen overheen als de stream-opslag True geeft. Een False-resultaat laat het vorige bestand exact zoals het was, en het falen van de uiteindelijke vervanging geeft een OS-fout in plaats van stilletjes terug te komen
Waarom heropent een dynamisch XFA-formulier met minder pagina's?
Een dynamisch XFA-formulier heropent met minder pagina's wanneer zijn root-subform geen restoreState="auto" declareert, en die beslissing hoort bij de formulierauteur. In XFA 3.3 defaultt restoreState op de root-subform naar manual. Onder manual herstelt de XFA-processor alleen beperkte status uit het opgeslagen formulierpakket en laat de rest aan de eigen scripts van het formulier. Veldwaarden en de instantieaantallen van herhalende subforms komen terug; geometrische eigenschappen die tijdens de uitvoering zijn gezet, niet
Neem een formulier van drie pagina's waarvan het script een subform laat groeien naar h="450pt" terwijl de gebruiker hem invult. Het opgeslagen formulierpakket bevat de nieuwe hoogte, de veldwaarden en de instantieaantallen. Bij het heropenen wordt de lay-out opnieuw opgebouwd vanuit de template-hoogten, krimpt het subform terug en vloeit de inhoud over twee pagina's. Dat is het gedrag dat de XFA-specificatie vraagt wanneer de template nooit om automatische herstel heeft gevraagd. Het declareren op de root-subform verandert het heropenen:
<template xmlns="http://www.xfa.org/schema/xfa-template/3.3/">
<subform name="form1" layout="tb" restoreState="auto">
<pageSet>
<pageArea name="Page1">
<contentArea x="0.25in" y="0.25in" w="8in" h="10.5in"/>
<medium stock="letter"/>
</pageArea>
</pageSet>
<subform name="Details" layout="tb" w="7.5in">
<!-- velden; scripts kunnen h wijzigen of instances toevoegen tijdens run time -->
</subform>
</subform>
</template>
Ben jij niet de eigenaar van de template, laat hem dan met rust: een formulier gebouwd voor manual-modus verwacht dat zijn eigen initialisatiescripts de status herbouwen, en de modus onder hun voeten veranderen verandert waar die scripts omheen zijn geschreven. Live herpaginering terwijl de gebruiker typt is een ander mechanisme, beschreven in hoe PDFium Component dynamische XFA-paginaaantallen en verplaatste velden volgt
Een XFA-round trip controleren vanuit Delphi
Een XFA-opslag wordt geverifieerd door het opgeslagen bestand te heropenen in een verse TPdf-instantie en de opgeslagen data terug te lezen, want een True van SaveAs zegt alleen dat het bestand is weggeschreven. TPdf.GetXfaDatasets geeft het datasets-pakket zoals het in het document staat, niet het live datamodel, dus vóór de opslag lezen toont het de waarden van de laatste lading. Na een heropenen toont het precies wat is weggeschreven. Een single-stream-document heeft geen apart benoemde pakketten: PDFium meldt de hele XDP als een pakket met een lege naam, dus GetXfaPacketByName('datasets') en GetXfaDatasets geven allebei een lege array terug, en de code hieronder valt terug op de volledige stream uit GetXfaFormPackets
uses
System.SysUtils, PDFium, FPdfXfa;
function ReadSavedXfaData(const FileName: string): string;
var
Pdf: TPdf;
Packets: TXfaPacketList;
Bytes: TBytes;
begin
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FileName;
Pdf.Active := True;
Bytes := Pdf.GetXfaDatasets; // packet-array-layout
if Length(Bytes) = 0 then
begin
Packets := Pdf.GetXfaFormPackets; // single stream: één naamloos packet
if Length(Packets) = 1 then
begin
SetLength(Bytes, Length(Packets[0].Content));
if Length(Bytes) > 0 then
Move(Packets[0].Content[0], Bytes[0], Length(Bytes));
end;
end;
Result := TEncoding.UTF8.GetString(Bytes); // opgeslagen XDP-output is UTF-8
finally
Pdf.Free;
end;
end;
De opsroutine legt de wachtende bewerking vast, controleert het SaveAs-resultaat en vergelijkt de heropende waarde. TPdf.ClearFormFieldFocus haalt de formulierfocus weg, en dat is het moment waarop PDFium de bewerkingsbuffer van het gefocuste veld vastlegt. TPdf.SetFocusedFormFieldText kan het gefocuste veld vanuit code vullen, maar leunt op focus die via widget-annotaties wordt bijgehouden, wat een dynamische XFA-pagina meestal mist; daar geeft hij False terug, en tekst komt normaal via toetsenbardinvoer in TPdfView binnen
// XmlText is een hulpfunctie die je zelf toevoegt; hij hoort niet bij PDFium Component
function XmlText(const S: string): string;
begin
Result := StringReplace(S, '&', '&', [rfReplaceAll]);
Result := StringReplace(Result, '<', '<', [rfReplaceAll]);
end;
procedure SaveXfaAndVerify(Pdf: TPdf; const FileName, FieldTag,
Expected: string);
var
Saved: string;
begin
// Optionele scripted fill; False betekent dat geen bijgehouden veld focus heeft
if (Pdf.FocusedFormFieldIndex >= 0) and
not Pdf.SetFocusedFormFieldText(Expected) then
raise EPdfError.Create('Could not write the focused field');
Pdf.ClearFormFieldFocus; // leg de bewerkingsbuffer vast
if not Pdf.SaveAs(FileName) then // False: het vorige bestand blijft onaangetast
raise EPdfError.CreateFmt('Saving %s failed', [FileName]);
// Heropen in een verse TPdf en zoek naar de exacte elementtekst
Saved := ReadSavedXfaData(FileName);
if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
Saved) = 0 then
raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;
De substringtest is alleen een rooktest. Een leeg element mag worden geschreven als <Tag/>, data-elementen kunnen attributen hebben, en escaping voorbij & en < is aan de serializer, dus productiecontroles horen in een echte XML-parser. Draai de routine twee keer achter elkaar met dezelfde input, want newlinedrift laat pas zijn volle vorm zien in de tweede generatie
Hosttoepassingen die de XFA-runtime direct aansturen, hebben ook de callback-layout nodig die hij verwacht, en dat is het onderwerp van FPDF_FORMFILLINFO versie 2 en de XFA-ABI in Delphi. Beide Windows-runtimes voor Win32 en Win64, de Delphi- en C++Builder-wrapper en het TPdfView-viewerbesturingselement worden meegeleverd met PDFium Component for Delphi and C++Builder