Artykuł techniczny

Scalanie formularzy PDF w Delphi: reguły pól zduplikowanych

Wpisz nazwisko w polu Applicant na stronie 1 świeżo scalonego pakietu aplikacyjnego, przejdź tabulatorem, i w wielu przeglądarkach pole Applicant na stronie 6 wypełni się tym samym tekstem. Nikt tych dwóch kontrolek nie spiął ze sobą. Część 1 i część 3 pakietu pisały różne osoby i obie nazwały pole najwyższego poziomu Applicant, a formularz PDF identyfikuje pole po jego w pełni kwalifikowanej nazwie. Dwa pola o jednej nazwie są — z punktu widzenia formatu pliku — jednym polem narysowanym dwa razy

Rozwiązaniem jest zdecydowanie, co wspólna nazwa ma znaczyć, zanim scalenie nastąpi: odmówić, zostawić ją celowo, albo przemianować nowego przybysza. Decydowanie po fakcie jest znacznie trudniejsze, niż brzmi

Co ISO 32000 rozumie przez nazwę pola

Nazwa pola to tożsamość i specyfikacja mówi to wprost. ISO 32000-1 §12.7.3.2 buduje w pełni kwalifikowaną nazwę z nazwy częściowej (wpisu T) pola i każdego z jego przodków, sklejanych kropkami. Ta sama sekcja pozwala kilku słownikom pól dzielić jedną w pełni kwalifikowaną nazwę i opisuje je jako różne reprezentacje tego samego pola bazowego, które powinny różnić się tylko wyglądem. Sklejenie tablic Fields dwóch niezależnie napisanych formularzy produkuje dokładnie taki układ — przypadkiem

Szkody zależą od tego, co kolidujące pola trzymały. Date, które na jednym formularzu znaczy data urodzenia, a na drugim data podpisu, ma teraz jedno miejsce na wartość i to, na czym zdecyduje przeglądarka, ląduje w obu. Total na arkuszu wydatków i Total na formularzu wpłaty rozmijną się w chwili, gdy ktokolwiek je policzy. Pola podpisu to najgorszy przypadek: dwa widżety podpisu na różnych stronach, jedna nazwa i żadnej czystej odpowiedzi, który widżet podpisujący faktycznie zatwierdził

Wielkość liter też ma znaczenie. Nazwy częściowe to łańcuchy tekstowe i nic w specyfikacji ich nie normalizuje wielkości, więc Total i total to dwa różne pola. Kontrola kolizji, która przed porównaniem zdejmie wielkość liter, zgłasza konflikty, które nie istnieją, a przy polityce przemianowywania przemianuje pola, których nikt nie musiał ruszać

Sprawdzanie nazw, zanim cokolwiek ruszy

PDF Library for Delphi załatwia kolizję w MergeDocumentEx(DocumentID, DuplicateFieldStrategy), które scala dokument wskazany przez DocumentID z aktualnie wybranym dokumentem i rozstrzyga każdy konflikt nazw, zanim pojedynczy obiekt zostanie przenumerowany. Strategia to wartość TPDFlibDuplicateFieldStrategy: dfsReject, dfsMerge albo dfsAutoNumber. Zwykłe MergeDocument nadal skleja obie główne tablice pól bez zmian — właściwy wybór, gdy oba formularze są twoje i wiesz, że ich nazwy się nie przecinają

Kolejność to cały projekt. Scalenie musi przesunąć numery obiektów dokumentu wchodzącego, żeby nie kolidowały z docelowymi, wszyć jego strony w drzewo stron celu i dopisać jego pola do formularza. Jeśli kolizja wychodzi dopiero po tych krokach, odmowa przestaje być darmowa — cel już wchłonął strony, obiekty źródła niosą numery, z którymi żaden plik nie wystartował, a wywołujący nie ma stanu, do którego mógłby wrócić, poza ponownym wczytaniem obu plików z dysku. MergeDocumentEx najpierw zbiera nazwy pól najwyższego poziomu obu dokumentów do uporządkowanego, rozróżniającego wielkość liter zbioru i stosuje strategię względem tego zbioru. Pod dfsReject kolizja sprawia, że wywołanie zwraca 0 z LastErrorCode ustawionym na 705, a oba dokumenty zostają dokładnie takie, jak zostały wczytane: zaraz po odmowie możesz wyciągnąć wartość pola z dokumentu źródłowego i dostać oryginalny tekst

Samo skanowanie jest tanie. Przy n nazwach w celu i m w źródle posortowanie ich do jednego zbioru kosztuje rząd (n + m) log(n + m) porównań, więc pakiet z kilkuset polami nie dokłada niczego, co zauważyłbyś obok parsowania plików

PDF Library for Delphi: Diagram kolejności operacji zestawiający stare scalanie odkrywające zduplikowane nazwy pól dopiero po renumeracji i zszywaniu drzewa stron z MergeDocumentEx zbierającym nazwy najpierw, tak że odrzucenie zostawia oba dokumenty nietknięte
Przenumerowanie i zszywanie drzewa stron dzieją się, zanim starsze scalenie w ogóle obejrzy nazwy pól, nie zostawiając czystego wycofania. MergeDocumentEx porównuje z góry uporządkowany, rozróżniający wielkość liter zbiór nazw, co zamienia odmowę w czysty no-op

Trzy własności skanu wychodzą na jaw w prawdziwych pakietach formularzy:

  • Porównywane są tylko pola najwyższego poziomu. W formularzu hierarchicznym to znaczy częściowa nazwa rodzica, więc dwa formularze, z których każdy ma rodzica applicant, kolidują, choćby ich dzieci się różniły, a autonumerowanie przemianowuje rodzica: dzieci wchodzące czytają się wtedy jako applicant_2.name i applicant_2.address
  • Nazwy wchodzące dołączają do zbioru w trakcie sprawdzania. Dokument źródłowy, który sam już niesie dwa pola najwyższego poziomu o tej samej nazwie, wyzwala strategię na tym drugim, nawet gdy cel nie ma pola o tej nazwie wcale
  • Pola z pustą nazwą częściową są pomijane, a gdy którykolwiek dokument nie ma AcroForm, nie ma czego porównywać, więc scalenie idzie dalej przy dowolnej strategii

Strona wczytywania ma jedną własną pułapkę. LoadFromFile dodaje nowy dokument do biblioteki i go wybiera, więc identyfikatorem do zapamiętania jest ten, który SelectedDocument zwraca po każdym wczytaniu. Złap go przed wczytaniem, a trzymasz inny dokument niż ten, w który myślisz, że scalasz

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;   // czytaj po wczytaniu, nie przed

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

    Lib.SelectDocument(TargetDoc);       // wybrany dokument przyjmuje scalenie
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // Zduplikowane nazwy najwyższego poziomu: oba dokumenty są nietknięte,
      // więc SourceDoc może prosto wrócić do drugiej próby
      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;

Najpierw ostro, potem łagodnie. Ten dwuetapowy kształt działa tylko dlatego, że odmowa zostawia SourceDoc wczytany i nienaruszony; przy scaleniu, które polegnie w pół drogi, gałąź zapasowa musiałaby zacząć od ponownego wczytania obu plików. Sprawdzanie akurat 705 też ma znaczenie, bo nieprawidłowy identyfikator dokumentu albo strategia poza zakresem zawalą wywołanie z innym kodem, a ponawianie z inną strategią żadnego z tych dwóch nie naprawi

Wybór strategii: odrzuć, udostępnij albo przenumeruj

W potokach nienadzorowanych ustaw dfsReject jako domyślną i traktuj 705 jako zgłoszenie dla właściciela formularzy źródłowych. Jednorazowa zmiana nazwy pola u źródła jest tańsza niż odkrycie po miesiącach, że mapowanie eksportu po cichu przestało się dopasowywać, bo scalenie wymyśliło Total_2. Strategie automatyczne zasługują na swoje miejsce, gdy człowiek obejrzał formularze i zdecydował, co wspólne nazwy znaczą

dfsMerge zostawia wspólną nazwę celowo. Zanim cokolwiek zostanie dopisane, wartość i wartość domyślna pola docelowego są kopiowane do pola wchodzącego, więc scalony plik startuje spójnie, a przeglądarka grupująca widżety po nazwie widzi jedno pole logiczne z jedną wartością. Oba słowniki pól pozostają osobnymi obiektami, każdy ze swoją stroną, wyglądem i akcjami. Sklejenie ich w jeden słownik wyrzuciłoby formatowanie i zachowanie należące do formularza wchodzącego, a tego targu nie opłaca się zawierać dla kosmetycznego uproszczenia

dfsAutoNumber przemianowuje wchodzące duplikaty przez dopisanie numerycznego sufiksu, startując od _2 i biorąc pierwszy wolny. Jeśli cel ma już Shared i Shared_2, nowy przybysz staje się Shared_3. Wynik zależy tylko od obecnych nazw, nigdy od numerów obiektów, więc scalenie tej samej pary plików dwa razy daje te same nazwy oba razy — własność, na której polegają importy FDF po drodze i mapowania bazodanowe

Trzy wyniki zduplikowanych pól w PDF Library for Delphi po MergeDocumentEx: dfsReject zwracający błąd 705 z obiema formularzami nietkniętymi, dfsMerge synchronizujący widżety o wspólnych nazwach do jednej wartości logicznej i dfsAutoNumber dodający odtwarzalny przyrostek _2
dfsReject zachowuje oba dokumenty w nienaruszonym stanie na wypadek świadomej ponownej próby, dfsMerge traktuje kilka widżetów o tej samej nazwie jako jedno pole logiczne przechowujące jedną synchronizowaną wartość, a dfsAutoNumber wręcza stabilne nazwy z sufiksami, których zewnętrzne mapowania muszą się spodziewać

Wybór między dwiema automatycznymi strategiami sprowadza się do jednego pytania: czy wypełnienie jednej kontrolki ma wypełnić drugą? Dla nazwiska podpisującego powtórzonego w każdej części pakietu — tak, pasuje dfsMerge. Dla sumy liczonej inaczej na każdym formularzu — nie. Weź tam dfsAutoNumber, a jeszcze lepiej, przemianuj pole w formularzu źródłowym, żeby sufiks w ogóle nie wystąpił

Co scalony formularz zawiera potem?

Weź cel z polem tekstowym najwyższego poziomu Shared trzymającym „Target value" i źródło z własnym Shared. Po dfsMerge FormFieldCount liczy dwa pola, oba zatytułowane Shared, oba raportujące „Target value". Po dfsAutoNumber te same dane wejściowe dają Shared i Shared_2, a pole wchodzące zachowuje wartość, którą miało w pliku źródłowym

Wynik dfsMerge ma ostrą krawędź i siedzi ona w twoim własnym kodzie wypełniającym. FindFormFieldByTitle zwraca pierwszy indeks, którego tytuł pasuje, a SetFormFieldValue pisze do dokładnie jednego pola. Rutyna, która znajdzie Shared raz i ustawi go, zaktualizuje kopię docelową i zostawi kopię wchodzącą z wartością otrzymaną przy scaleniu. Zapisany plik zawiera teraz dwa pola o jednej nazwie i dwóch różnych wartościach, a to, które pokaże przeglądarka, zależy od przeglądarki. Pisz do każdego dopasowania:

// Ustawia każde pole niosące Title; zwraca, ile ich zostało zapisanych.
// Po scaleniu dfsMerge jedno pole logiczne może pojawić się na kilku indeksach
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]));   // pola tylko do odczytu lądują tutaj
    end;
end;

Zanim wpniesz scalony pakiet do zasilania danymi, zrób zrzut tego, co scalenie faktycznie wyprodukowało. Wystarczy pętla dwulinijkowa, i wyłapie przemianowanych rodziców oraz sufiksy _2, zanim zrobi to zadanie importu:

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

Składanie pakietu formularzy w praktyce

Udane scalenie konsumuje dokument źródłowy. Znika z listy dokumentów biblioteki, więc DocumentCount spada o jeden, a starego identyfikatora SourceDoc nie wolno już użyć. Scalony dokument bierze wyższą z dwóch wersji PDF: scalenie formularza PDF 2.0 do dokumentu 1.7 daje plik 2.0, co ma znaczenie, gdy krok archiwizacji po drodze oczekuje konkretnej wersji

Kolejność scalenia rozstrzyga, czyje nazwy przeżyją. Wybrany dokument zachowuje każdą swoją nazwę, a przemianowania i kopie wartości dotykają tylko pól wchodzących, więc scalenie A do B i scalenie B do A dają różne wyniki autonumerowania. Gdy pakiet ma formularz podstawowy — ten, którego nazw pól back office już zna — zrób go celem i scalaj w niego dodatki

Podpisuj na końcu. Podpis obejmuje bajty rewizji, którą podpisał, a scalenie przepisuje plik, więc część podpisana przed składaniem już nie niesie podpisu pasującego do dokumentu. Złóż pakiet, sprawdź listę pól, potem nałóż podpisy na gotowy plik. Jeśli zadanie to tylko zszywanie stron, a formularze cię nie obchodzi, szybszą drogą jest szybkie scalenie PDF z przesuwem referencji bajtów

Stronę danych planuj razem ze scaleniem. Jeśli wartości pól przychodzą z systemu zewnętrznego adresującego pola po nazwie, załatw nazewnictwo przed wyborem dfsAutoNumber, bo Shared_2 nie dopasuje się do mapowania oczekującego Shared. Formaty importu i eksportu wartości pokrywa artykuł wymiana danych formularzy FDF, XFDF i XFA. Skrypty obliczeniowe i akcje odwołujące się do pól po nazwie cierpią na przemianowywaniu tak samo, a artykuł akcje formularzy interaktywnych i JavaScript pokazuje, gdzie te odwołania mieszkają

Scalanie formularzy świadome duplikatów, wypełnianie pól i podpis cyfrowy to części tej samej biblioteki dla projektów Delphi, C++Builder i Free Pascal. Resztę API formularzy i składania dokumentów wypisuje strona produktu PDF Library for Delphi