Article technique

Formulaires PDF fusionnés : règles des champs en double

Tapez un nom dans la case Applicant en page 1 d'un dossier de candidature fraîchement fusionné, passez au champ suivant, et dans bien des lecteurs la case Applicant en page 6 se remplit du même texte. Personne n'a câblé ces deux contrôles ensemble. La partie 1 et la partie 3 du dossier ont été écrites par des personnes différentes, toutes deux ont nommé Applicant un champ de premier niveau, et un formulaire PDF identifie un champ par son nom entièrement qualifié. Deux champs avec un même nom sont, du point de vue du format de fichier, un seul champ dessiné deux fois

La parade consiste à décider ce qu'un nom partagé doit signifier avant que la fusion n'arrive : le refuser, le garder à dessein, ou renommer le nouveau venu. Décider après coup est bien plus difficile qu'il n'y paraît

Ce que ISO 32000 entend par nom de champ

Un nom de champ est une identité, et la spécification le dit. ISO 32000-1 §12.7.3.2 construit le nom entièrement qualifié à partir du nom partiel (l'entrée T) d'un champ et de chacun de ses ancêtres, joints par des points. La même section autorise plusieurs dictionnaires de champ à partager un nom entièrement qualifié et les décrit comme des représentations différentes d'un même champ sous-jacent, qui ne devraient différer que par leur apparence. Concaténer les tableaux Fields de deux formulaires écrits indépendamment produit exactement cet arrangement par accident

Le dommage dépend de ce que contenaient les champs en collision. Un Date qui signifiait date de naissance sur un formulaire et date de signature sur un autre n'a plus qu'un emplacement de valeur unique, et la valeur sur laquelle se stabilise le lecteur atterrit aux deux endroits. Un Total sur une note de frais et un Total sur un bulletin de dépôt divergeront dès que l'un des deux sera calculé. Les champs de signature sont le pire cas : deux widgets de signature sur des pages différentes, un seul nom, et aucune réponse propre à la question de savoir quel widget le signataire a réellement approuvé

La casse compte aussi. Les noms partiels sont des chaînes de texte et rien dans la spécification ne les normalise, donc Total et total sont deux champs différents. Un contrôle de collision qui met les noms en minuscules avant de comparer rapporte des conflits qui n'existent pas, et sous une politique de renommage il renomme des champs que personne n'aurait besoin de toucher

Contrôler les noms avant que quoi que ce soit ne bouge

PDF Library for Delphi traite la collision dans MergeDocumentEx(DocumentID, DuplicateFieldStrategy), qui fusionne le document identifié par DocumentID dans le document actuellement sélectionné et règle chaque conflit de nom avant qu'un seul objet ne soit renuméroté. La stratégie est une valeur TPDFlibDuplicateFieldStrategy : dfsReject, dfsMerge ou dfsAutoNumber. Le MergeDocument simple concatène toujours les deux tableaux de champs racine sans les toucher, ce qui est le bon choix quand vous possédez les deux formulaires et savez leurs noms disjoints

L'ordre est tout le design. Une fusion doit décaler les numéros d'objets du document entrant pour qu'ils ne se heurtent pas à ceux de la cible, coudre ses pages dans l'arbre de pages de la cible et annexer ses champs au formulaire. Si une collision ne surgit qu'après ces étapes, refuser n'est plus gratuit : la cible a déjà absorbé des pages, les objets de la source portent des numéros qu'aucun fichier n'avait au départ, et l'appelant n'a plus aucun état de repli à part recharger les deux fichiers depuis le disque. MergeDocumentEx rassemble d'abord les noms de champs de premier niveau des deux documents dans un ensemble ordonné et sensible à la casse, puis applique la stratégie contre cet ensemble. Sous dfsReject, une collision fait retourner 0 à l'appel avec LastErrorCode à 705, et les deux documents restent exactement tels que chargés : vous pouvez lire une valeur de champ dans le document source juste après le refus et retrouver le texte d'origine

Le balayage lui-même est bon marché. Avec n noms dans la cible et m dans la source, les trier en un seul ensemble coûte de l'ordre de (n + m) log(n + m) comparaisons, donc un dossier de quelques centaines de champs n'ajoute rien que vous remarqueriez à côté de l'analyse des fichiers

PDF Library for Delphi : diagramme des ordres d'opération contrastant une fusion qui découvre les noms de champs dupliqués seulement après renumérotation et couture de l'arbre de pages avec MergeDocumentEx collectant les noms d'abord, si bien qu'un refus laisse les deux documents intacts
Une fusion qui examine les noms de champs seulement après renumérotation et couture de l'arbre de pages n'a aucun retour arrière propre. MergeDocumentEx compare un ensemble de noms ordonné et sensible à la casse d'avance, ce qui fait du refus un no-op propre

Trois propriétés du balayage apparaissent dans les vrais dossiers de formulaires :

  • Seuls les champs de premier niveau sont comparés. Dans un formulaire hiérarchique, cela signifie le nom partiel du parent, donc deux formulaires qui ont chacun un parent nommé applicant entrent en collision même si leurs enfants diffèrent, et la numérotation automatique renomme le parent : les enfants entrants se lisent alors applicant_2.name et applicant_2.address
  • Les noms entrants rejoignent l'ensemble au fur et à mesure des vérifications. Un document source qui porte déjà deux champs de premier niveau de même nom déclenche la stratégie sur le second, même quand la cible n'a aucun champ de ce nom
  • Les champs au nom partiel vide sont sautés, et quand l'un des documents n'a pas d'AcroForm il n'y a rien à comparer, donc la fusion avance sous n'importe quelle stratégie

Le côté chargement a un piège à lui. LoadFromFile ajoute un nouveau document à la bibliothèque et le sélectionne, donc l'identifiant à conserver est celui que SelectedDocument renvoie après chaque chargement. Le saisir avant le chargement, et vous tenez un document différent de celui dans lequel vous croyez fusionner

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;   // lire après le chargement, pas avant

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

    Lib.SelectDocument(TargetDoc);       // le document sélectionné reçoit la fusion
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // Noms de premier niveau dupliqués : les deux documents sont intacts,
      // donc SourceDoc peut repartir directement dans une seconde tentative
      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;

Strict d'abord, tolérant ensuite. Cette forme en deux étapes ne marche que parce que le refus laisse SourceDoc chargé et intact ; avec une fusion qui échoue à mi-chemin, la branche de repli devrait commencer par recharger les deux fichiers. Vérifier spécifiquement 705 compte aussi, car un identifiant de document invalide ou une valeur de stratégie hors plage fait échouer l'appel avec un autre code, et retenter avec une autre stratégie ne répare ni l'un ni l'autre

Choisir une stratégie : refuser, partager ou renuméroter

Pour les pipelines sans surveillance, faites de dfsReject le défaut et traitez 705 comme un ticket pour qui possède les formulaires sources. Renommer un champ en amont une fois coûte moins cher que de découvrir des mois plus tard qu'un mappage d'export s'est arrêté silencieusement de correspondre parce qu'une fusion a inventé Total_2. Les stratégies automatiques gagnent leur place quand un humain a regardé les formulaires et décidé ce que les noms partagés signifient

dfsMerge garde le nom partagé délibérément. Avant toute annexion, la valeur et la valeur par défaut du champ cible sont copiées dans le champ entrant, donc le fichier fusionné démarre cohérent et un lecteur qui groupe les widgets par nom voit un champ logique unique avec une valeur. Les deux dictionnaires de champ restent des objets séparés, chacun gardant sa page, son apparence et ses actions. Les fondre en un seul dictionnaire jetterait le formatage et le comportement qui appartiennent au formulaire entrant, et ce troc ne vaut pas la peine pour une simplification cosmétique

dfsAutoNumber renomme les doublons entrants en ajoutant un suffixe numérique, en commençant à _2 et en prenant le premier libre. Si la cible a déjà Shared et Shared_2, le nouveau venu devient Shared_3. Le résultat ne dépend que des noms présents, jamais des numéros d'objets, donc fusionner deux fois la même paire de fichiers donne les mêmes noms les deux fois : une propriété sur laquelle comptent les imports FDF aval et les mappages de bases de données

Trois issues de champs dupliqués dans PDF Library for Delphi après MergeDocumentEx : dfsReject retournant l'erreur 705 avec les deux formulaires intacts, dfsMerge synchronisant les widgets de même nom en une valeur logique unique, et dfsAutoNumber ajoutant un suffixe _2 reproductible
dfsReject garde les deux documents intacts pour une nouvelle tentative éclairée, dfsMerge traite plusieurs widgets de même nom comme un seul champ logique portant une valeur synchronisée, et dfsAutoNumber distribue des noms suffixés stables que les mappages externes doivent anticiper

Choisir entre les deux stratégies automatiques se ramène à une question : remplir un contrôle doit-il remplir l'autre ? Pour le nom du signataire répété sur chaque partie d'un dossier, oui, et dfsMerge convient. Pour un total calculé différemment sur chaque formulaire, non. Prenez dfsAutoNumber là, ou mieux, renommez le champ dans le formulaire source pour que le suffixe n'apparaisse jamais

Que contient le formulaire fusionné ensuite ?

Prenez une cible avec un champ texte de premier niveau Shared tenant "Target value" et une source avec son propre Shared. Après dfsMerge, FormFieldCount compte deux champs, tous deux titrés Shared, tous deux rapportant "Target value". Après dfsAutoNumber, la même entrée donne Shared et Shared_2, et le champ entrant garde la valeur qu'il avait dans le fichier source

Le résultat de dfsMerge a un tranchant, et il se trouve dans votre propre code de remplissage. FindFormFieldByTitle renvoie le premier index dont le titre correspond, et SetFormFieldValue écrit dans exactement un champ. Une routine qui cherche Shared une fois et le positionne met à jour la copie de la cible et laisse la copie entrante tenir la valeur qu'elle a reçue à la fusion. Le fichier sauvegardé contient alors deux champs avec un nom et deux valeurs différentes, et lequel le lecteur montre dépend du lecteur. Écrivez chaque correspondance :

// Positionne chaque champ portant Title ; renvoie combien ont été écrits.
// Après une fusion dfsMerge, un champ logique peut apparaître à plusieurs index
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]));   // les champs en lecture seule atterrissent ici
    end;
end;

Avant de brancher un dossier fusionné dans un flux de données, videz ce que la fusion a réellement produit. Une boucle de deux lignes suffit, et elle attrape les parents renommés et les suffixes _2 avant qu'un travail d'import ne le fasse :

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

Assembler un dossier de formulaires en pratique

Une fusion réussie consomme le document source. Il est retiré de la liste des documents de la bibliothèque, donc DocumentCount baisse d'une unité, et l'ancien identifiant SourceDoc ne doit plus être utilisé. Le document fusionné prend la plus haute des deux versions PDF : fusionner un formulaire PDF 2.0 dans un document 1.7 donne un fichier 2.0, ce qui compte si une étape d'archivage aval attend une version particulière

L'ordre de fusion décide des noms qui survivent. Le document sélectionné garde chacun de ses noms, et les renommages ou copies de valeurs ne s'appliquent qu'aux champs entrants, donc fusionner A dans B et fusionner B dans A donnent des résultats auto-numérotés différents. Quand un dossier a un formulaire principal, celui dont votre back office connaît déjà les noms de champs, faites-en la cible et fusionnez les suppléments dedans

Signez en dernier. Une signature couvre les octets de la révision qu'elle a signée, et fusionner réécrit le fichier, donc une partie signée avant l'assemblage ne porte plus une signature qui correspond au document. Assemblez le dossier, vérifiez la liste des champs, puis appliquez les signatures au fichier fini. Si le travail ne consiste qu'à coudre des pages et que les formulaires importent peu, la fusion PDF rapide par décalage de références d'octets est la voie plus prompte

Planifiez le côté données en même temps que la fusion. Si les valeurs de champs arrivent d'un système externe qui adresse les champs par nom, réglez la nomination avant de choisir dfsAutoNumber, car Shared_2 ne correspondra pas à un mappage qui attend Shared. Les formats d'import et d'export de valeurs sont couverts dans l'échange de données de formulaires FDF, XFDF et XFA. Les scripts de calcul et les actions qui référencent des champs par nom sont touchés par le renommage de la même manière, et les actions de formulaires interactifs et JavaScript montre où vivent ces références

La fusion de formulaires consciente des doublons, le remplissage de champs et la signature numérique font tous partie de la même bibliothèque pour les projets Delphi, C++Builder et Free Pascal. La page produit de PDF Library for Delphi liste le reste de l'API d'assemblage de formulaires et de documents