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
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
applicantheet, botsen zelfs als hun kinderen verschillen, en auto-nummering hernoemt de ouder: de binnenkomende kinderen lezen dan alsapplicant_2.nameenapplicant_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
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