Digite um nome na caixa Applicant da página 1 de um recém-mesclado pacote de inscrição, passe para o campo seguinte e, em muitos visualizadores, a caixa Applicant da página 6 se preenche com o mesmo texto. Ninguém ligou esses dois controles. As partes 1 e 3 do pacote foram escritas por pessoas diferentes, ambas chamaram um campo de nível superior de Applicant, e um formulário PDF identifica um campo pelo seu nome totalmente qualificado. Dois campos com um só nome são, do ponto de vista do formato de arquivo, um campo desenhado duas vezes
A correção é decidir o que um nome compartilhado deve significar antes de a mesclagem acontecer: recusá-lo, mantê-lo de propósito ou renomear o recém-chegado. Decidir depois é muito mais difícil do que parece
O que a ISO 32000 entende por nome de campo
Um nome de campo é identidade, e a especificação diz isso. A ISO 32000-1 §12.7.3.2 constrói o nome totalmente qualificado a partir do nome parcial (a entrada T) de um campo e de cada um dos seus ancestrais, unidos por pontos. A mesma seção permite que vários dicionários de campo compartilhem um nome totalmente qualificado e os descreve como representações diferentes do mesmo campo subjacente, que deveriam diferir apenas na aparência. Concatenar os arrays Fields de dois formulários escritos independentemente produz exatamente esse arranjo por acidente
O dano depende do que os campos em colisão guardavam. Um Date que significava data de nascimento em um formulário e data de assinatura em outro agora tem uma única posição de valor, e o valor em que o visualizador se decidir cai nos dois lugares. Um Total em uma folha de despesas e um Total em um formulário de depósito vão discordar no momento em que qualquer um for calculado. Campos de assinatura são o pior caso: dois widgets de assinatura em páginas diferentes, um nome, e nenhuma resposta limpa sobre qual widget o signatário realmente aprovou
Maiúsculas e minúsculas também importam. Nomes parciais são strings de texto e nada na especificação os normaliza, então Total e total são dois campos diferentes. Uma checagem de colisão que converte nomes para minúsculas antes de comparar reporta conflitos que não existem e, sob uma política de renomeação, renomeia campos que ninguém precisava tocar
Conferindo nomes antes de qualquer coisa se mover
O PDF Library for Delphi trata a colisão no MergeDocumentEx(DocumentID, DuplicateFieldStrategy), que mescla o documento identificado por DocumentID no documento atualmente selecionado e resolve todo conflito de nome antes de um único objeto ser renumerado. A estratégia é um valor TPDFlibDuplicateFieldStrategy: dfsReject, dfsMerge ou dfsAutoNumber. O MergeDocument simples ainda concatena os dois arrays de campos raiz sem mudanças, o que é a escolha certa quando você é o dono dos dois formulários e sabe que os nomes são disjuntos
A ordem é todo o desenho. Uma mesclagem precisa deslocar os números de objeto do documento entrante para que não choquem com os do destino, costurar as suas páginas na árvore de páginas do destino e anexar os seus campos ao formulário. Se uma colisão só aparece depois desses passos, recusar deixa de ser de graça — o destino já absorveu páginas, os objetos da origem carregam números que nenhum arquivo tinha no começo, e quem chama não tem estado para onde voltar, a não ser recarregar os dois arquivos do disco. O MergeDocumentEx coleta primeiro os nomes de campos de nível superior dos dois documentos em um conjunto ordenado e case-sensitive e aplica a estratégia contra esse conjunto. Sob dfsReject, uma colisão faz a chamada retornar 0 com LastErrorCode definido como 705, e ambos os documentos permanecem exatamente como carregados: você pode ler um valor de campo do documento de origem logo após a recusa e receber o texto original de volta
A varredura em si é barata. Com n nomes no destino e m na origem, ordená-los em um conjunto custa da ordem de (n + m) log(n + m) comparações, então um pacote com algumas centenas de campos não acrescenta nada que você perceberia ao lado da análise dos arquivos
Três propriedades da varredura aparecem em pacotes de formulários reais:
- Só os campos de nível superior são comparados. Em um formulário hierárquico, isso significa o nome parcial do pai, então dois formulários que tenham cada um um pai chamado
applicantcolidem mesmo que os filhos difiram, e a numeração automática renomeia o pai: os filhos entrantes passam a se ler comoapplicant_2.nameeapplicant_2.address - Nomes entrantes entram no conjunto conforme são checados. Um documento de origem que já carrega dois campos de nível superior com o mesmo nome dispara a estratégia no segundo, mesmo quando o destino não tem campo nenhum com esse nome
- Campos com nome parcial vazio são pulados, e quando um dos documentos não tem AcroForm não há nada para comparar, então a mesclagem segue adiante sob qualquer estratégia
O lado do carregamento tem uma armadilha própria. O LoadFromFile adiciona um novo documento à biblioteca e o seleciona, então o identificador a guardar é o que o SelectedDocument retorna após cada carga. Pegue-o antes da carga e você estará segurando um documento diferente daquele em que acredita estar mesclando
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; // leia depois da carga, não antes
if Lib.LoadFromFile(Part2, '') = 0 then
raise Exception.CreateFmt('Cannot load %s', [Part2]);
SourceDoc := Lib.SelectedDocument;
Lib.SelectDocument(TargetDoc); // o documento selecionado recebe a mesclagem
if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
begin
if Lib.LastErrorCode <> 705 then
raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
// Nomes de nível superior duplicados: ambos os documentos ficam intocados,
// então o SourceDoc pode ir direto para uma segunda tentativa
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;
Rigoroso primeiro, tolerante depois. Esse formato de dois passos só funciona porque a recusa deixa o SourceDoc carregado e intacto; com uma mesclagem que falha no meio do caminho, o ramo de fallback teria de começar recarregando os dois arquivos. Verificar especificamente o 705 também importa, porque um identificador de documento inválido ou um valor de estratégia fora da faixa falha a chamada com outro código, e tentar de novo com outra estratégia não conserta nenhum dos dois
Escolhendo uma estratégia: recusar, compartilhar ou renumerar
Para pipelines não assistidos, faça do dfsReject o padrão e trate o 705 como um ticket para quem é o dono dos formulários de origem. Renomear um campo a montante uma vez custa menos do que descobrir meses depois que um mapeamento de exportação silenciosamente deixou de casar porque uma mesclagem inventou um Total_2. As estratégias automáticas ganham o seu lugar quando uma pessoa olhou os formulários e decidiu o que os nomes compartilhados significam
O dfsMerge mantém o nome compartilhado de propósito. Antes de qualquer coisa ser anexada, o valor e o valor padrão do campo do destino são copiados para o campo entrante, então o arquivo mesclado começa consistente e um visualizador que agrupa widgets por nome vê um campo lógico com um valor. Os dois dicionários de campo permanecem objetos separados, cada um mantendo a própria página, aparência e ações. Fundi-los em um dicionário jogaria fora formatação e comportamento que pertencem ao formulário entrante, e essa troca não vale a pena por uma simplificação cosmética
O dfsAutoNumber renomeia duplicatas entrantes anexando um sufixo numérico, começando em _2 e pegando o primeiro livre. Se o destino já tem Shared e Shared_2, o recém-chegado vira Shared_3. O resultado depende apenas dos nomes presentes, nunca dos números de objeto, então mesclar o mesmo par de arquivos duas vezes produz os mesmos nomes nas duas — uma propriedade de que importações FDF a jusante e mapeamentos de banco de dados dependem
Escolher entre as duas estratégias automáticas se resume a uma pergunta: preencher um controle deve preencher o outro? Para o nome do signatário repetido em cada parte de um pacote, sim, e o dfsMerge serve. Para um total calculado de forma diferente em cada formulário, não. Ali, escolha o dfsAutoNumber, ou melhor, renomeie o campo no formulário de origem para que o sufixo nunca apareça
O que o formulário mesclado contém depois?
Considere um destino com um campo de texto de nível superior Shared guardando "Target value" e uma origem com o seu próprio Shared. Depois do dfsMerge, o FormFieldCount conta dois campos, ambos intitulados Shared, ambos reportando "Target value". Depois do dfsAutoNumber, a mesma entrada dá Shared e Shared_2, e o campo entrante mantém o valor que tinha no arquivo de origem
O resultado do dfsMerge tem um fio cortante, e ele está no seu próprio código de preenchimento. O FindFormFieldByTitle retorna o primeiro índice cujo título corresponde, e o SetFormFieldValue escreve em exatamente um campo. Uma rotina que procura Shared uma vez e o define atualiza a cópia do destino e deixa a cópia entrante com o valor que recebeu na mesclagem. O arquivo salvo agora contém dois campos com um nome e dois valores diferentes, e qual deles um visualizador mostra depende do visualizador. Escreva em toda correspondência em vez disso:
// Define todo campo que carrega Title; retorna quantos foram escritos.
// Após uma mesclagem dfsMerge, um campo lógico pode aparecer em vários í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])); // campos somente leitura acabam aqui
end;
end;
Antes de ligar um pacote mesclado a um feed de dados, despeje o que a mesclagem realmente produziu. Um loop de duas linhas basta, e ele pega os pais renomeados e os sufixos _2 antes que um job de importação pegue:
for I := 1 to Lib.FormFieldCount do
WriteLn(Format('%3d %-30s %s',
[I, Lib.GetFormFieldTitle(I), Lib.GetFormFieldValue(I)]));
Montando um pacote de formulários na prática
Uma mesclagem bem-sucedida consome o documento de origem. Ele é removido da lista de documentos da biblioteca, então o DocumentCount cai um, e o antigo identificador SourceDoc não deve ser usado de novo. O documento mesclado assume a maior das duas versões de PDF: mesclar um formulário PDF 2.0 em um documento 1.7 produz um arquivo 2.0, o que importa se um passo de arquivamento a jusante espera uma versão específica
A ordem da mesclagem decide quais nomes sobrevivem. O documento selecionado mantém todos os seus nomes, e renomeações ou cópias de valor só se aplicam aos campos entrantes, então mesclar A em B e mesclar B em A dão resultados de numeração automática diferentes. Quando um pacote tem um formulário primário — aquele cujos nomes de campo o seu back office já conhece — faça dele o destino e mescle os suplementos nele
Assine por último. Uma assinatura cobre os bytes da revisão que ela assinou, e mesclar reescreve o arquivo, então uma parte assinada antes da montagem não carrega mais uma assinatura que corresponda ao documento. Monte o pacote, confira a lista de campos e então aplique as assinaturas ao arquivo pronto. Se o trabalho é só costurar páginas e os formulários não importam, a mesclagem rápida de PDF com deslocamento de referências de bytes é o caminho mais veloz
Planeje o lado dos dados junto com a mesclagem. Se os valores de campo chegam de um sistema externo que endereça campos pelo nome, acerte a nomenclatura antes de escolher o dfsAutoNumber, já que um Shared_2 não vai casar com um mapeamento que espera Shared. Os formatos de importação e exportação de valores estão cobertos em intercâmbio de dados de formulários FDF, XFDF e XFA. Scripts de cálculo e ações que referenciam campos pelo nome são afetados por renomeação da mesma forma, e ações de formulários interativos e JavaScript mostra onde essas referências vivem
Mesclagem de formulários ciente de duplicatas, preenchimento de campos e assinatura digital fazem parte da mesma biblioteca para projetos Delphi, C++Builder e Free Pascal. A página do produto PDF Library for Delphi lista o restante da API de montagem de formulários e documentos