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
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
applicantcolisionan aunque sus hijos difieran, y el auto-numerado renombra al padre: los hijos entrantes entonces se leen comoapplicant_2.nameyapplicant_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
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