Artículo técnico

Combinar formularios PDF: campos duplicados en Delphi

Escriba un nombre en el cuadro Applicant de la página 1 de un paquete de solicitud recién combinado, pase al siguiente campo, y en muchos visores el cuadro Applicant de la página 6 se llena con el mismo texto. Nadie conectó esos dos controles. La parte 1 y la parte 3 del paquete las escribió gente distinta, ambos pusieron Applicant a un campo de nivel superior, y un formulario PDF identifica un campo por su nombre completamente calificado. Dos campos con un solo nombre son, hasta donde llega el formato de archivo, un solo campo dibujado dos veces

La solución es decidir qué debe significar un nombre compartido antes de que ocurra la combinación: rechazarlo, conservarlo a propósito o renombrar al recién llegado. Decidir después es mucho más difícil de lo que suena

Qué entiende ISO 32000 por nombre de campo

Un nombre de campo es identidad, y la especificación lo dice. ISO 32000-1 §12.7.3.2 construye el nombre completamente calificado a partir del nombre parcial (la entrada T) de un campo y de cada uno de sus ancestros, unidos con puntos. La misma sección permite que varios diccionarios de campo compartan un nombre completamente calificado y los describe como representaciones distintas del mismo campo subyacente, que solo deberían diferir en cómo se ven. Concatenar los arreglos Fields de dos formularios escritos de forma independiente produce exactamente ese arreglo por accidente

El daño depende de lo que contenían los campos en colisión. Un Date que significaba fecha de nacimiento en un formulario y fecha de firma en otro ahora tiene un único espacio de valor, y el valor que el visor decida aterriza en ambos lugares. Un Total en una hoja de gastos y un Total en un formulario de depósito discreparán en el momento en que cualquiera de los dos se calcule. Los campos de firma son el peor caso: dos widgets de firma en páginas distintas, un nombre, y ninguna respuesta limpia sobre cuál widget aprobó realmente el firmante

Las mayúsculas y minúsculas también importan. Los nombres parciales son cadenas de texto y nada en la especificación los pliega, así que Total y total son dos campos distintos. Una verificación de colisiones que convierte los nombres a minúsculas antes de comparar reporta conflictos que no existen, y bajo una política de renombrado renombra campos que nadie necesitaba tocar

Verificar los nombres antes de que nada se mueva

PDF Library for Delphi maneja la colisión en MergeDocumentEx(DocumentID, DuplicateFieldStrategy), que combina el documento identificado por DocumentID en el documento actualmente seleccionado y resuelve cada conflicto de nombres antes de que un solo objeto se renumere. La estrategia es un valor TPDFlibDuplicateFieldStrategy: dfsReject, dfsMerge o dfsAutoNumber. El MergeDocument sencillo sigue concatenando los dos arreglos raíz de campos sin cambios, que es la decisión correcta cuando usted posee ambos formularios y sabe que sus nombres no se cruzan

El orden es todo el diseño. Una combinación tiene que desplazar los números de objeto del documento entrante para que no choquen con los del destino, coser sus páginas en el árbol de páginas del destino y anexar sus campos al formulario. Si una colisión solo sale a la luz después de esos pasos, rechazar ya no es gratis — el destino ya absorbió páginas, los objetos del origen cargan números con los que ningún archivo empezó, y el llamador no tiene estado al que regresar salvo recargar ambos archivos desde disco. MergeDocumentEx recolecta primero los nombres de campo de nivel superior de ambos documentos en un conjunto ordenado y sensible a mayúsculas y aplica la estrategia contra ese conjunto. Bajo dfsReject una colisión hace que la llamada devuelva 0 con LastErrorCode en 705, y ambos documentos quedan exactamente como estaban cargados: puede leer un valor de campo del documento de origen justo después del rechazo y recibir el texto original

El escaneo en sí es barato. Con n nombres en el destino y m en el origen, ordenarlos en un solo conjunto cuesta del orden de (n + m) log(n + m) comparaciones, así que un paquete de unos cientos de campos no agrega nada que usted note junto al parseo de los archivos

PDF Library for Delphi: Diagrama de orden de operaciones que contrasta una combinación que descubre nombres de campo duplicados solo después de renumerar y coser el árbol de páginas con MergeDocumentEx recolectando los nombres primero, de modo que un rechazo deja ambos documentos intactos
Una combinación que examina los nombres de campo solo después de renumerar y coser el árbol de páginas no tiene rollback limpio. MergeDocumentEx compara de entrada un conjunto de nombres ordenado y sensible a mayúsculas, lo que convierte el rechazo en un no-op limpio

Tres propiedades del escaneo aparecen en paquetes de formularios reales:

  • Solo se comparan los campos de nivel superior. En un formulario jerárquico eso significa el nombre parcial del padre, así que dos formularios que cada uno tiene un padre llamado applicant colisionan aunque sus hijos difieran, y el auto-numerado renombra al padre: los hijos entrantes entonces se leen como applicant_2.name y applicant_2.address
  • Los nombres entrantes se unen al conjunto a medida que se verifican. Un documento de origen que ya lleva dos campos de nivel superior con el mismo nombre dispara la estrategia en el segundo, incluso cuando el destino no tiene ningún campo con ese nombre
  • Los campos con nombre parcial vacío se omiten, y cuando alguno de los documentos no tiene AcroForm no hay nada que comparar, así que la combinación procede bajo cualquier estrategia

El lado de carga tiene una trampa propia. LoadFromFile agrega un nuevo documento a la biblioteca y lo selecciona, así que el identificador que hay que conservar es el que SelectedDocument devuelve después de cada carga. Si lo toma antes de la carga, está sosteniendo un documento distinto del que cree que es su destino

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;   // léalo después de la carga, no antes

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

    Lib.SelectDocument(TargetDoc);       // el documento seleccionado recibe la combinación
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // Nombres de nivel superior duplicados: ambos documentos quedan intactos,
      // así que SourceDoc puede volver directo a un segundo intento
      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;

Primero estricto, después tolerante. Esa forma de dos pasos solo funciona porque el rechazo deja a SourceDoc cargado e intacto; con una combinación que falla a medias, la rama de respaldo tendría que empezar recargando ambos archivos. Verificar específicamente el 705 también importa, porque un identificador de documento inválido o un valor de estrategia fuera de rango hacen fallar la llamada con un código distinto, y reintentar con otra estrategia no arreglará ninguno de los dos

Elegir una estrategia: rechazar, compartir o renumerar

Para pipelines desatendidos, haga de dfsReject el valor predeterminado y trate el 705 como un ticket para quien sea dueño de los formularios de origen. Renombrar un campo upstream una vez es más barato que descubrir meses después que un mapeo de exportación dejó de coincidir en silencio porque una combinación inventó Total_2. Las estrategias automáticas se ganan su lugar cuando un humano miró los formularios y decidió qué significan los nombres compartidos

dfsMerge conserva el nombre compartido a propósito. Antes de que nada se anexe, el valor y el valor predeterminado del campo del destino se copian al campo entrante, así que el archivo combinado arranca consistente y un visor que agrupa widgets por nombre ve un campo lógico con un valor. Los dos diccionarios de campo siguen siendo objetos separados, cada uno conservando su propia página, apariencia y acciones. Plegarlos en un solo diccionario tiraría formato y comportamiento que pertenecen al formulario entrante, y ese intercambio no vale la pena por una simplificación cosmética

dfsAutoNumber renombra los duplicados entrantes agregando un sufijo numérico, empezando en _2 y tomando el primero libre. Si el destino ya tiene Shared y Shared_2, el recién llegado se convierte en Shared_3. El resultado depende solo de los nombres presentes, nunca de los números de objeto, así que combinar el mismo par de archivos dos veces produce los mismos nombres ambas veces — una propiedad de la que dependen las importaciones FDF posteriores y los mapeos de base de datos

PDF Library for Delphi tres resultados de campos duplicados tras MergeDocumentEx: dfsReject devolviendo el error 705 con ambos formularios intactos, dfsMerge sincronizando widgets con nombre compartido en un valor lógico único, y dfsAutoNumber agregando un sufijo _2 reproducible
dfsReject deja ambos documentos prístinos para un reintento informado, dfsMerge trata varios widgets con el mismo nombre como un campo lógico que sostiene un valor sincronizado, y dfsAutoNumber reparte nombres con sufijo estables que los mapeos externos deben anticipar

Elegir entre las dos estrategias automáticas se reduce a una pregunta: ¿llenar un control debe llenar el otro? Para el nombre del firmante repetido en cada parte del paquete, sí, y dfsMerge encaja. Para un total que se calcula distinto en cada formulario, no. Elija ahí dfsAutoNumber, o mejor, renombre el campo en el formulario de origen para que el sufijo nunca aparezca

¿Qué contiene el formulario combinado después?

Tome un destino con un campo de texto de nivel superior Shared que sostiene «Target value» y un origen con su propio Shared. Tras dfsMerge, FormFieldCount cuenta dos campos, ambos titulados Shared, ambos reportando «Target value». Tras dfsAutoNumber, la misma entrada da Shared y Shared_2, y el campo entrante conserva el valor que tenía en el archivo de origen

El resultado de dfsMerge tiene un filo afilado, y vive en su propio código de llenado. FindFormFieldByTitle devuelve el primer índice cuyo título coincide, y SetFormFieldValue escribe exactamente en un campo. Una rutina que busca Shared una vez y lo establece actualiza la copia del destino y deja la copia entrante sosteniendo el valor que recibió al momento de la combinación. El archivo guardado ahora contiene dos campos con un nombre y dos valores distintos, y cuál muestra el visor depende del visor. Escriba cada coincidencia:

// Establece cada campo que lleva Title; devuelve cuántos se escribieron.
// Tras una combinación dfsMerge un campo lógico puede aparecer en varios índices
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]));   // los campos de solo lectura terminan aquí
    end;
end;

Antes de conectar un paquete combinado a un flujo de datos, descargue lo que la combinación realmente produjo. Un bucle de dos líneas basta, y atrapa los padres renombrados y los sufijos _2 antes de que lo haga un trabajo de importación:

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

Ensamblar un paquete de formularios en la práctica

Una combinación exitosa consume el documento de origen. Se elimina de la lista de documentos de la biblioteca, así que DocumentCount baja en uno, y el antiguo identificador SourceDoc no debe usarse de nuevo. El documento combinado toma la más alta de las dos versiones PDF: combinar un formulario PDF 2.0 en un documento 1.7 produce un archivo 2.0, lo que importa si un paso de archivado posterior espera una versión particular

El orden de combinación decide qué nombres sobreviven. El documento seleccionado conserva cada uno de sus nombres, y los renombrados o copias de valor solo aplican jamás a los campos entrantes, así que combinar A en B y combinar B en A dan resultados auto-numerados distintos. Cuando un paquete tiene un formulario primario — el cuyos nombres de campo ya conoce su back office — hágalo el destino y combine los suplementos en él

Firme al final. Una firma cubre los bytes de la revisión que firmó, y combinar reescribe el archivo, así que una parte que se firmó antes del ensamblaje ya no lleva una firma que coincida con el documento. Ensamble el paquete, revise la lista de campos, y luego aplique las firmas al archivo terminado. Si el trabajo se trata solo de coser páginas y los formularios no importan, la combinación rápida de PDF con desplazamiento de referencias de bytes es la ruta más veloz

Planifique el lado de datos junto con la combinación. Si los valores de campo llegan de un sistema externo que direcciona campos por nombre, resuelva el nombrado antes de elegir dfsAutoNumber, porque Shared_2 no coincidirá con un mapeo que espera Shared. Los formatos de importación y exportación de valores están cubiertos en intercambio de datos de formulario FDF, XFDF y XFA. Los scripts de cálculo y las acciones que referencian campos por nombre se ven afectados por el renombrado de la misma manera, y acciones de formularios interactivos y JavaScript muestra dónde viven esas referencias

La combinación de formularios consciente de duplicados, el llenado de campos y la firma digital son parte de la misma biblioteca para proyectos Delphi, C++Builder y Free Pascal. La página del producto PDF Library for Delphi lista el resto de la API de formularios y ensamblaje de documentos