Escribe un nombre en la casilla Applicant de la página 1 de un paquete de solicitudes recién combinado, pasa al campo siguiente, y en muchos visores la casilla Applicant de la página 6 se rellena con el mismo texto. Nadie conectó esos dos controles. Las partes 1 y 3 del paquete las escribió gente distinta, ambas llamaron Applicant a un campo de nivel superior, y un formulario PDF identifica un campo por su nombre completo. Dos campos con un mismo nombre son, para el formato de archivo, un mismo campo dibujado dos veces
La solución es decidir qué debe significar un nombre compartido antes de que la combinación ocurra: rechazarlo, conservarlo a propósito o renombrar al recién llegado. Decidirlo después es mucho más difícil de lo que suena
Qué entiende ISO 32000 por nombre de campo
El nombre de un campo es su identidad, y la especificación lo dice. ISO 32000-1 §12.7.3.2 construye el nombre completo 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 completo y los describe como representaciones distintas del mismo campo subyacente, que solo deberían diferir en el aspecto. Concatenar los arrays Fields de dos formularios escritos de forma independiente produce exactamente esa situación por accidente
El daño depende de lo que contuvieran los campos en colisión. Un Date que significaba fecha de nacimiento en un formulario y fecha de firma en otro tiene ahora una única ranura de valor, y el valor por el que se decante el visor aterriza en los dos sitios. Un Total en una hoja de gastos y un Total en un formulario de depósito discrepan en cuanto se calcula cualquiera. 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 de los dos widgets aprobó realmente el firmante
Las mayúsculas también importan. Los nombres parciales son cadenas de texto y nada en la especificación los normaliza, así que Total y total son dos campos distintos. Una comprobación de colisiones que pase los nombres a minúsculas antes de comparar informa de conflictos que no existen, y bajo una política de renombrado renombra campos que nadie necesitaba tocar
Comprobar los nombres antes de que nada se mueva
PDF Library for Delphi trata la colisión en MergeDocumentEx(DocumentID, DuplicateFieldStrategy), que combina el documento identificado por DocumentID en el documento seleccionado actualmente y resuelve cada conflicto de nombres antes de renumerar un solo objeto. La estrategia es un valor TPDFlibDuplicateFieldStrategy: dfsReject, dfsMerge o dfsAutoNumber. El MergeDocument normal sigue concatenando los dos arrays de campos raíz sin cambios, que es la decisión correcta cuando ambos formularios son tuyos y sabes 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 añadir sus campos al formulario. Si una colisión solo asoma después de esos pasos, rechazar ya no es gratis — el destino ya absorbió páginas, los objetos del origen llevan números con los que ningún archivo empezó, y el que llama no tiene estado al que volver salvo recargar ambos archivos desde disco. MergeDocumentEx recopila 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. Con dfsReject, una colisión hace que la llamada devuelva 0 con LastErrorCode a 705, y ambos documentos quedan tal cual estaban cargados: puedes leer un valor de campo del documento de origen justo después del rechazo y recuperar el texto original
El barrido 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 añade nada que puedas notar junto al parseo de los archivos
Tres propiedades del barrido se dejan ver 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 tenga un padre llamado
applicantcolisionan aunque sus hijos difieran, y la numeración automática renombra al padre: los hijos entrantes pasan a leerseapplicant_2.nameyapplicant_2.address - Los nombres entrantes se unen al conjunto a medida que se comprueban. Un documento de origen que ya lleve dos campos de nivel superior con el mismo nombre dispara la estrategia con el segundo, aunque el destino no tenga ningún campo con ese nombre
- Los campos con nombre parcial vacío se saltan, y cuando alguno de los dos documentos no tiene AcroForm no hay nada que comparar, así que la combinación prosigue bajo cualquier estrategia
El lado de la carga tiene su propia trampa. LoadFromFile añade un documento nuevo a la biblioteca y lo selecciona, así que el identificador que hay que conservar es el que SelectedDocument devuelve tras cada carga. Cógelo antes de la carga y estarás sujetando un documento distinto del que crees que es tu destino de combinación
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; // se lee 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 ir 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, luego indulgente. Esa forma de dos pasos solo funciona porque el rechazo deja SourceDoc cargado e intacto; con una combinación que falla a medias, la rama de reserva tendría que empezar recargando ambos archivos. Comprobar 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 otro código, y reintentar con otra estrategia no arregla ninguno de los dos
Elegir estrategia: rechazar, compartir o renumerar
Para pipelines desatendidos, haz de dfsReject el valor por defecto y trata el 705 como un tiquete para quien posea los formularios de origen. Renombrar un campo arriba en la cadena una vez sale más barato que descubrir meses después que un mapeo de exportación dejó de encajar en silencio porque una combinación inventó Total_2. Las estrategias automáticas se ganan su sitio cuando una persona ha mirado los formularios y decidido qué significan los nombres compartidos
dfsMerge conserva el nombre compartido a propósito. Antes de añadir nada, el valor y el valor predeterminado del campo de destino se copian en el 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 con su página, su apariencia y sus acciones. Fundirlos en un 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 añadiendo 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 da los mismos nombres ambas veces — una propiedad de la que dependen las importaciones FDF de aguas abajo y los mapeos de base de datos
Elegir entre las dos estrategias automáticas se reduce a una pregunta: ¿rellenar un control debe rellenar el otro? Para el nombre del firmante repetido en cada parte de un paquete, sí, y dfsMerge encaja. Para un total que se calcula de forma distinta en cada formulario, no. Allí elige dfsAutoNumber, o mejor, renombra el campo en el formulario de origen para que el sufijo nunca aparezca
¿Qué contiene el formulario combinado después?
Toma un destino con un campo de texto de nivel superior Shared que lleva «Target value» y un origen con su propio Shared. Tras dfsMerge, FormFieldCount cuenta dos campos, ambos titulados Shared, ambos informando «Target value». Tras dfsAutoNumber, la misma entrada da Shared y Shared_2, y el campo entrante conserva el valor que tuviera en el archivo de origen
El resultado de dfsMerge tiene un filo peligroso, y está en tu propio código de relleno. FindFormFieldByTitle devuelve el primer índice cuyo título encaja, 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 con el valor que recibió en el momento de la combinación. El archivo guardado contiene ahora dos campos con un nombre y dos valores distintos, y cuál muestra el visor depende del visor. Escribe en todas las coincidencias en su lugar:
// Establece cada campo que lleve 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 acaban aquí
end;
end;
Antes de enchufar un paquete combinado a un flujo de datos, vuelca lo que la combinación produjo realmente. Un bucle de dos líneas basta, y caza a 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 viejo identificador SourceDoc no debe volver a usarse. El documento combinado toma la mayor de las dos versiones PDF: combinar un formulario PDF 2.0 en un documento 1.7 da un archivo 2.0, algo que importa si un paso de archivado de aguas abajo espera una versión concreta
El orden de combinación decide qué nombres sobreviven. El documento seleccionado conserva todos sus nombres, y los renombrados o copias de valor solo se aplican jamás a los campos entrantes, así que combinar A en B y combinar B en A dan resultados de numeración automática distintos. Cuando un paquete tiene un formulario principal — el formulario cuyos nombres de campo ya conoce tu back office — hazlo el destino y combina los complementos dentro
Firma al final. Una firma cubre los bytes de la revisión que firmó, y combinar reescribe el archivo, así que una parte firmada antes del ensamblaje ya no lleva una firma que corresponda con el documento. Ensambla el paquete, revisa la lista de campos y aplica después las firmas al archivo terminado. Si el trabajo es solo coser páginas y los formularios no importan, la combinación rápida de PDF con desplazamiento de referencias de byte es la vía más rápida
Planifica el lado de los datos junto con la combinación. Si los valores de campo llegan de un sistema externo que direcciona los campos por nombre, cierra el tema de nombres antes de elegir dfsAutoNumber, porque Shared_2 no encajará con un mapeo que espera Shared. Los formatos de importación y exportación de valores están tratados en el intercambio de datos de formulario FDF, XFDF y XFA. Los scripts de cálculo y las acciones que referencian campos por nombre sufren el renombrado igual, y las acciones de formulario interactivas y JavaScript muestra dónde viven esas referencias
La combinación de formularios consciente de duplicados, el relleno de campos y la firma digital forman parte de la misma biblioteca para proyectos Delphi, C++Builder y Free Pascal. La página de producto de PDF Library for Delphi lista el resto de la API de formularios y ensamblado de documentos