Technisch artikel

PDF-formulieren samenvoegen: dubbele velden in Delphi

Typ een naam in het vak Applicant op pagina 1 van een vers samengevoegd aanvraagpakket, tab naar het volgende veld, en in veel viewers vult het vak Applicant op pagina 6 zich met dezelfde tekst. Niemand heeft die twee besturingselementen aan elkaar gekoppeld. Deel 1 en deel 3 van het pakket zijn door verschillende mensen geschreven, beide noemden een veld op toplevel Applicant, en een PDF-formulier identificeert een veld bij zijn volledig gekwalificeerde naam. Twee velden met één naam zijn, wat het bestandsformaat betreft, één veld dat twee keer wordt getekend

De oplossing is om vóór de merge te beslissen wat een gedeelde naam moet betekenen: weigeren, met opzet delen, of de nieuwkomer hernoemen. Achteraf beslissen is veel moeilijker dan het klinkt

Wat ISO 32000 onder een veldnaam verstaat

Een veldnaam is identiteit, en de specificatie zegt dat expliciet. ISO 32000-1 §12.7.3.2 bouwt de volledig gekwalificeerde naam uit de partiele naam (de T-entry) van een veld en van elk van zijn voorouders, samengevoegd met punten. Dezelfde sectie staat toe dat verschillende veldwoordenboeken een volledig gekwalificeerde naam delen en beschrijft ze als verschillende representaties van hetzelfde onderliggende veld, die alleen in uiterlijk zouden mogen verschillen. De Fields-arrays van twee onafhankelijk geschreven formulieren aan elkaar plakken levert precies die opzet per ongeluk op

De schade hangt af van wat de botsende velden bevatten. Een Date die op het ene formulier geboortedatum betekende en op het andere datum van ondertekening, heeft nu één waardeplek, en welke waarde een viewer ook kiest, hij belandt op beide plekken. Een Total op een onkostenstaat en een Total op een stortingsoverzicht spreken elkaar tegen zodra een van beide wordt berekend. Handtekeningvelden zijn het slechtste geval: twee signature-widgets op verschillende pagina's, één naam, en geen net antwoord op welke widget de ondertekenaar nu eigenlijk heeft goedgekeurd

Ook hoofdletters tellen. Partiele namen zijn tekstreeksen en niets in de specificatie vouwt ze, dus Total en total zijn twee verschillende velden. Een botsingscontrole die namen eerst naar kleine letters brengt voordat hij vergelijkt, rapporteert conflicten die niet bestaan, en onder een hernoembeleid hernoemt hij velden die niemand hoefde aan te raken

Namen controleren voordat er iets beweegt

PDF Library for Delphi pakt de botsing aan in MergeDocumentEx(DocumentID, DuplicateFieldStrategy), dat het document dat bij DocumentID hoort samenvoegt in het momenteel geselecteerde document en elke naamconflict beslecht voordat er ook maar één object wordt hernummerd. De strategie is een waarde TPDFlibDuplicateFieldStrategy: dfsReject, dfsMerge of dfsAutoNumber. De gewone MergeDocument plakt nog steeds de twee wortelveldarrays ongewijzigd aan elkaar, wat de juiste keuze is wanneer u beide formulieren bezit en weet dat hun namen uiteenlopen

Volgorde is het hele ontwerp. Een merge moet de objectnummers van het binnenkomende document verschuiven zodat ze niet botsen met die van het doel, zijn pagina's in de paginaboom van het doel inpassen en zijn velden aan het formulier toevoegen. Als een botsing pas na die stappen naar boven komt, is weigeren niet meer gratis — het doel heeft al pagina's opgenomen, de objecten van de bron dragen nummers waarmee geen van beide bestanden begon, en de aanroeper heeft geen toestand om op terug te vallen behalve beide bestanden opnieuw van schijf te laden. MergeDocumentEx verzamelt eerst de namen op toplevel van beide documenten in een geordende, hoofdlettergevoelige set en past de strategie daarop toe. Onder dfsReject laat een botsing de aanroep 0 teruggeven met LastErrorCode op 705, en beide documenten blijven precies zoals geladen: u kunt direct na de weigering een veldwaarde uit het brondocument lezen en de originele tekst terugkrijgen

De scan zelf is goedkoop. Met n namen in het doel en m in de bron kost het sorteren ervan in één set in de orde van (n + m) log(n + m) vergelijkingen, dus een pakket met enkele honderden velden voegt niets toe dat u opmerkt naast het parsen van de bestanden

PDF Library for Delphi: volgorde-van-operaties-diagram dat een merge die dubbele veldnamen pas na hernummering en pagina-boominpassing ontdekt afzet tegen MergeDocumentEx dat eerst namen verzamelt, zodat een weigering beide documenten onaangetast laat
Een merge die veldnamen pas na hernummering en pagina-boominpassing bekijkt, heeft geen schone rollback; MergeDocumentEx vergelijkt vooraf een geordende, hoofdlettergevoelige naamenset, wat van weigeren een schone no-op maakt

Drie eigenschappen van de scan komen naar boven in echte formulierpakketten:

  • Alleen velden op toplevel worden vergeleken. In een hiërarchisch formulier betekent dat de partiele naam van de ouder, dus twee formulieren die elk een ouder hebben die applicant heet, botsen zelfs als hun kinderen verschillen, en auto-nummering hernoemt de ouder: de binnenkomende kinderen lezen dan als applicant_2.name en applicant_2.address
  • Binnenkomende namen komen in de set terwijl ze worden gecontroleerd. Een brondocument dat al twee velden op toplevel met dezelfde naam draagt, triggert de strategie bij het tweede, zelfs als het doel helemaal geen veld met die naam heeft
  • Velden met een lege partiele naam worden overgeslagen, en wanneer een van beide documenten geen AcroForm heeft, is er niets te vergelijken, dus de merge gaat onder elke strategie door

De laadkant heeft één valkuil van eigen makelij. LoadFromFile voegt een nieuw document toe aan de bibliotheek en selecteert het, dus de identifier om vast te houden is degene die SelectedDocument na elke load teruggeeft. Grijp hem vóór de load en u houdt een ander document vast dan hetgeen waarvan u denkt dat u erin samenvoegt

uses
  SysUtils, PDFlibrary;

procedure BuildPack(const Part1, Part2, OutFile: WideString);
var
  Lib: TPDFlib;
  TargetDoc, SourceDoc: Integer;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile(Part1, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part1]);
    TargetDoc := Lib.SelectedDocument;   // lezen na de load, niet ervoor

    if Lib.LoadFromFile(Part2, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part2]);
    SourceDoc := Lib.SelectedDocument;

    Lib.SelectDocument(TargetDoc);       // het geselecteerde document ontvangt de merge
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // Dubbele namen op toplevel: beide documenten zijn onaangeroerd,
      // dus SourceDoc kan direct in een tweede poging terug
      WriteLn('Duplicate field names in ', Part2, ', retrying with auto-numbering');
      if Lib.MergeDocumentEx(SourceDoc, dfsAutoNumber) = 0 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
    end;

    Lib.SaveToFile(OutFile);
  finally
    Lib.Free;
  end;
end;

Streng eerst, soepel daarna. Die vorm met twee stappen werkt alleen omdat de weigering SourceDoc geladen en intact laat; bij een merge die halverwege faalt, zou de fallback-tak moeten beginnen met beide bestanden opnieuw te laden. Specifiek op 705 controleren telt ook, want een ongeldige documentidentifier of een strategiewaarde buiten bereik laat de aanroep met een andere code falen, en opnieuw proberen met een andere strategie lost geen van beide op

Een strategie kiezen: weigeren, delen of hernummeren

Voor onbeheerde pijplijnen: maak dfsReject de standaard en behandel 705 als een ticket voor wie de bronformulieren beheert. Eén veld upstream hernoemen is goedkoper dan maanden later ontdekken dat een exportmapping stilletjes stopte met matchen omdat een merge Total_2 had uitgevonden. De automatische strategieen verdienen hun plek wanneer een mens naar de formulieren heeft gekeken en heeft beslist wat de gedeelde namen betekenen

dfsMerge houdt de gedeelde naam bewust vast. Voordat er iets wordt toegevoegd, worden de waarde en de standaardwaarde van het doelfeld gekopieerd naar het binnenkomende veld, dus het samengevoegde bestand begint consistent en een viewer die widgets op naam groepeert, ziet één logisch veld met één waarde. De twee veldwoordenboeken blijven aparte objecten, elk met zijn eigen pagina, appearance en actions. Ze in één woordenboek vouwen zou opmaak en gedrag weggooien dat bij het binnenkomende formulier hoort, en die afweging is een cosmetische vereenvoudiging niet waard

dfsAutoNumber hernoemt binnenkomende duplicaten door een numeriek achtervoegsel toe te voegen, te beginnen bij _2 en het eerste vrije te nemen. Heeft het doel al Shared en Shared_2, dan wordt de nieuwkomer Shared_3. Het resultaat hangt alleen af van de aanwezige namen, nooit van objectnummers, dus hetzelfde paar bestanden twee keer samenvoegen levert beide keren dezelfde namen op — een eigenschap waar downstream-FDF-imports en databasemappings op vertrouwen

PDF Library for Delphi: drie uitkomsten voor dubbele velden na MergeDocumentEx: dfsReject die fout 705 teruggeeft met beide formulieren intact, dfsMerge die widgets met gedeelde naam synchroniseert tot één logische waarde, en dfsAutoNumber die een reproduceerbaar achtervoegsel _2 toevoegt
dfsReject houdt beide documenten onaangetast voor een weloverwogen herhaling, dfsMerge behandelt meerdere gelijknamige widgets als één logisch veld met één gesynchroniseerde waarde, en dfsAutoNumber deelt stabiele achtervoegsels uit waar externe mappings rekening mee moeten houden

De keuze tussen de twee automatische strategieen komt neer op één vraag: moet het vullen van het ene besturingselement het andere vullen? Voor de naam van de ondertekenaar die op elk deel van een pakket terugkomt, ja, en dfsMerge past. Voor een totaal dat op elk formulier anders wordt berekend, nee. Kies daar dfsAutoNumber, of beter, hernoem het veld in het bronformulier zodat het achtervoegsel nooit verschijnt

Wat bevat het samengevoegde formulier daarna?

Neem een doel met een tekstveld op toplevel Shared met de waarde "Target value" en een bron met zijn eigen Shared. Na dfsMerge telt FormFieldCount twee velden, beide getiteld Shared, beide rapporterend "Target value". Na dfsAutoNumber geeft dezelfde invoer Shared en Shared_2, en het binnenkomende veld houdt de waarde die het in het bronbestand had

Het resultaat van dfsMerge heeft een scherpe rand, en die zit in uw eigen vulcode. FindFormFieldByTitle geeft de eerste index terug waarvan de titel matcht, en SetFormFieldValue schrijft naar precies één veld. Een routine die Shared één keer opzoekt en zet, werkt de kopie van het doel bij en laat de binnenkomende kopie de waarde houden die hij bij de merge ontving. Het opgeslagen bestand bevat nu twee velden met één naam en twee verschillende waarden, en welke een viewer toont is aan de viewer. Schrijf in plaats daarvan elke match weg:

// Zet elk veld dat Title draagt; geeft terug hoeveel zijn geschreven.
// Na een dfsMerge-merge kan één logisch veld op verschillende indexes verschijnen
function SetAllFieldsNamed(Lib: TPDFlib; const Title, Value: WideString): Integer;
var
  I: Integer;
begin
  Result := 0;
  for I := 1 to Lib.FormFieldCount do
    if Lib.GetFormFieldTitle(I) = Title then
    begin
      if Lib.SetFormFieldValue(I, Value) = 1 then
        Inc(Result)
      else
        WriteLn(Format('Field %d (%s) not written, error %d',
          [I, Title, Lib.LastErrorCode]));   // alleen-lezenvelden belanden hier
    end;
end;

Voordat u een samengevoegd pakket aan een datafeed koppelt, dumpt u wat de merge werkelijk heeft opgeleverd. Een lus van twee regels is genoeg, en hij vangt de hernoemde ouders en _2-achtervoegsels vóórdat een importtaak dat doet:

for I := 1 to Lib.FormFieldCount do
  WriteLn(Format('%3d  %-30s  %s',
    [I, Lib.GetFormFieldTitle(I), Lib.GetFormFieldValue(I)]));

Een formulierpakket in de praktijk samenstellen

Een geslaagde merge verbruikt het brondocument. Het wordt uit de documentlijst van de bibliotheek verwijderd, dus DocumentCount daalt met één, en de oude identifier SourceDoc mag niet opnieuw worden gebruikt. Het samengevoegde document neemt de hogere van de twee PDF-versies aan: een PDF 2.0-formulier in een 1.7-document samenvoegen levert een 2.0-bestand op, wat telt als een downstream-archiveringsstap een bepaalde versie verwacht

De mergevolgorde beslist wier namen overleven. Het geselecteerde document houdt elk van zijn namen, en hernoemingen of waardekopieen gelden alleen voor de binnenkomende velden, dus A in B samenvoegen en B in A samenvoegen geven verschillende auto-genummerde resultaten. Heeft een pakket een primair formulier — hetgeen waarvan uw backoffice de veldnamen al kent — maak het dan het doel en voeg de aanvullingen erin samen

Onderteken als laatste. Een handtekening dekt de bytes van de revisie die hij ondertekende, en samenvoegen herschrijft het bestand, dus een deel dat vóór de assemblage werd ondertekend draagt geen handtekening meer die bij het document hoort. Stel het pakket samen, controleer de veldlijst, en breng daarna de handtekeningen aan op het voltooide bestand. Gaat het alleen om pagina's aan elkaar plakken en doen de formulieren er niet toe, dan is snelle PDF-merge met byte-reference-shifting de snellere route

Plan de datakant samen met de merge. Als veldwaarden aankomen uit een extern systeem dat velden bij naam adresseert, leg de naamgeving dan vast voordat u dfsAutoNumber kiest, want Shared_2 matcht niet met een mapping die Shared verwacht. Waarde-import- en exportformaten worden behandeld in FDF-, XFDF- en XFA-formuliergegevensuitwisseling. Berekeningscripts en acties die velden bij naam refereren, worden door hernoemen op dezelfde manier geraakt, en interactieve formulieracties en JavaScript laat zien waar die referenties wonen

Formuliermerge met duplicaatbewustzijn, het vullen van velden en digitaal ondertekenen maken allemaal deel uit van dezelfde bibliotheek voor Delphi-, C++Builder- en Free Pascal-projecten. De productpagina van PDF Library for Delphi somt de rest van de formulier- en documentassemblage-API op