Technisch artikel

PDFium Component XFA Save: newlines, emoji en restoreState

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

PDFium Component-diagram van de XFA-opslagcyclus waarin de writer een newline na starttags toevoegt, de heropende parser de LF tussen de Comments-tags als veldwaarde leest en elke verdere opslag nog een line feed toevoegt tenzij de writer alleen de witruimte verwijdert die hij zelf heeft gesynthetiseerd
Eén opslag-heropen-cyclus plant de eerste line feed en elke volgende ronde voegt er nog één toe, waardoor de drift zijn volle vorm pas in de tweede generatie laat zien

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 &#x1F642;. 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

PDFium Component-diagram van surrogaatafhandeling waarin U+1F642 aankomt als het UTF-16-paar D83D DE42 en twee naïeve paden hem kunnen corrupteren: 16-bit wchar_t-decoders kappen de scalar af tot U+F642 in de private use area, terwijl een serializer die eenzame surrogaten filtert de emoji helemaal laat verdwijnen
Windows wchar_t is 16 bits breed, dus een scalar die een surrogaatpaar nodig heeft verliest zijn hoge helft of verdwijnt uit het pakket, tenzij beide paden paren bij elkaar houden

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

PDFium Component single-stream XFA-opslagpijplijn waarbij live datasets- en formulierpakketten naar staging worden geëxporteerd, gevalideerd en vervolgens binnen de originele XDP worden vervangen, met comments bewaard via markers, terwijl staging-falen en inputs als DTDs of XMLDSig de opslag expliciet weigeren
De export in staging wordt gevalideerd voordat er iets wordt vervangen, dus een mislukte opslag laat de persistente XFA-stream onaangetast en het document houdt zijn wijzigingsmarkering

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- of form-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, '&', '&amp;', [rfReplaceAll]);
  Result := StringReplace(Result, '<', '&lt;', [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