Teknik Makale

PDF Formlarını Birleştirme: Yinelenen Alan Kuralları

Yeni birleştirilmiş bir başvuru paketinin 1. sayfasındaki Applicant kutusuna bir ad yazın, sekmeyle geçin ve pek çok görüntüleyicide 6. sayfadaki Applicant kutusu aynı metinle dolar. O iki denetimi kimse birbirine bağlamadı. Paketin 1. ve 3. parçalarını farklı kişiler yazdı, ikisi de üst düzey bir alana Applicant adını verdi ve bir PDF formu bir alanı tam nitelikli adıyla tanır. Dosya biçimi açısından tek ada sahip iki alan, iki kez çizilen tek alandır

Çözüm, birleştirme gerçekleşmeden önce paylaşılan adın ne anması gerektiğine karar vermektir: reddedin, kasıtlı olarak koruyun ya da geleni yeniden adlandırın. Sonradan karar vermek, kulağa geldiğinden çok daha zordur

ISO 32000 bir alan adıyla ne kasteder

Bir alan adı kimliktir ve belirtim bunu böyle söyler. ISO 32000-1 §12.7.3.2, tam nitelikli adı; bir alanın ve her atasının kısmi adından (T girişi) oluşturur, noktalarla birleştirerek. Aynı bölüm, birkaç alan sözlüğünün tam nitelikli bir adı paylaşmasına izin verir ve onları, aynı altta yatan alanın farklı temsilleri olarak tanımlar; bunlar yalnızca görünümlerinde ayrışmalıdır. Bağımsız yazılmış iki formun Fields dizilerini uç uca eklemek, tam olarak o düzeni kazayla üretir

Hasar, çakışan alanların ne taşıdığına bağlıdır. Bir formda doğum tarihi, diğerinde imza tarihi anlamına gelen bir Date, artık tek bir değer yuvasına sahiptir ve görüntüleyicinin hangi değere yerleştiği iki yerde de görünür. Bir gider cetvelindeki Total ile bir havale formundaki Total, biri hesaplandığı an çelişir. İmza alanları en kötü durumdur: farklı sayfalarda iki imza widget'ı, tek ad ve imzalayanın gerçekte hangisini onayladığına dair temiz bir yanıt yok

Büyük/küçük harf de önemlidir. Kısmi adlar metin dizeleridir ve belirtimde onları katlayan hiçbir şey yoktur; Total ile total iki farklı alandır. Karşılaştırmadan önce adları küçük harfe çeviren bir çakışma denetimi, var olmayan çakışmalar bildirir ve bir yeniden adlandırma ilkesi altında kimsenin dokunması gerekmeyen alanları yeniden adlandırır

Hiçbir şey kıpırdamadan önce adları denetlemek

PDF Library for Delphi çakışmayı MergeDocumentEx(DocumentID, DuplicateFieldStrategy) içinde ele alır; bu, DocumentID ile tanımlanan belgeyi o an seçili belgeye birleştirir ve tek bir nesne yeniden numaralandırılmadan her ad çakışmasını çözer. Strateji bir TPDFlibDuplicateFieldStrategy değeridir: dfsReject, dfsMerge ya da dfsAutoNumber. Düz MergeDocument hâlâ iki kök alan dizisini değiştirmeden uç uca ekler; bu, iki formu da sizin sahende olduğunuz ve adlarının ayrık olduğunu bildiğinizde doğru seçimdir

Sıra, tasarımın ta kendisidir. Bir birleştirme, gelen belgenin nesne numaralarını hedefinkilerle çarpışmayacak biçimde kaydırmak, sayfalarını hedefin sayfa ağacına dikmek ve alanlarını forma eklemek zorundadır. Bir çakışma bu adımlardan sonra ortaya çıkarsa reddetmek artık bedava değildir — hedef sayfaları çoktan emmiştir, kaynağın nesneleri iki dosyanın da başlamadığı numaraları taşır ve çağıranın geri döneceği bir durum, iki dosyayı diskten yeniden yüklemekten öte yoktur. MergeDocumentEx her iki belgenin üst düzey alan adlarını önce sıralı, büyük/küçük harfe duyarlı bir kümeye toplar ve stratejiyi o kümeye karşı uygular. dfsReject altında bir çakışma, çağrıyı LastErrorCode 705 olacak biçimde 0 döndürür; iki belge de yüklendikleri haliyle kalır: reddin hemen ardından kaynak belgeden bir alan değeri okuyup orijinal metni geri alabilirsiniz

Taramanın kendisi ucuzdur. Hedefte n, kaynakta m ad varken onları tek bir kümeye sıralamak (n + m) log(n + m) mertebesinde karşılaştırmaya mal olur; yani birkaç yüz alanlı bir paket, dosyaları ayrıştırmanın yanında fark edeceğiniz hiçbir şey eklemez

PDF Library for Delphi: İşlem sırası şeması: yinelenen alan adlarını yalnızca yeniden numaralandırma ve sayfa ağacı dikmesinden sonra keşfeden eski birleştirmeyi, adları önce toplayan ve bir reddin her iki belgeyi de dokunulmamış bıraktığı MergeDocumentEx ile karşılaştırır
Yeniden numaralandırma ve sayfa ağacı dikimi, eski birleştirme alan adlarına hiç bakmadan önce gerçekleşir; temiz bir geri alma bırakmaz. MergeDocumentEx sıralı, büyük/küçük harfe duyarlı ad kümesini baştan karşılaştırır; bu da reddi temiz bir no-op'e dönüştürür

Taramanın üç özelliği gerçek form paketlerinde kendini gösterir:

  • Yalnızca üst düzey alanlar karşılaştırılır. Hiyerarşik bir formda bu, atanın kısmi adı demektir; böylece her birinde applicant adlı bir atası olan iki form, çocukları farklı olsa da çakışır ve otomatik numaralandırma atayı yeniden adlandırır: gelen çocuklar sonra applicant_2.name ve applicant_2.address olarak okunur
  • Gelen adlar, denetlendikleri sırada kümeye katılır. Zaten aynı ada sahip iki üst düzey alan taşıyan bir kaynak belge, ikincisinde stratejiyi tetikler; hedefte o adın hiçbir alanı olmasa bile
  • Kısmi adı boş olan alanlar atlanır ve iki belgeden birinde AcroForm yoksa karşılaştırılacak hiçbir şey yoktur; birleştirme her strateji altında ilerler

Yükleme tarafının kendi tuzağı vardır. LoadFromFile kütüphaneye yeni bir belge ekler ve onu seçer; saklanacak tanımlayıcı, her yüklemeden sonra SelectedDocument'un döndürdüğüdür. Onu yüklemeden önce kaparsanız elinizdeki, birleştirdiğinizi sandığınız belge değildir

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;   // yüklemeden sonra okuyun, önce değil

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

    Lib.SelectDocument(TargetDoc);       // birleştirmeyi seçili belge alır
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // Yinelenen üst düzey adlar: iki belge de el değmemiş,
      // bu yüzden SourceDoc doğrudan ikinci bir denemeye girebilir
      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;

Önce katı, sonra toleranslı. İki adımlı o biçim yalnızca reddin SourceDoc'u yüklü ve sağlam bırakması sayesinde çalışır; yarı yolda başarısız olan bir birleştirmede geri düşüş dalı, iki dosyayı yeniden yükleyerek başlamak zorunda kalırdı. Özellikle 705'i denetlemek de önemlidir, çünkü geçersiz bir belge tanımlayıcısı ya da aralık dışı bir strateji değeri çağrıyı başka bir kodla başarısız kılar ve başka bir stratejiyle yeniden denemek ikisini de düzeltmez

Strateji seçimi: reddet, paylaş ya da yeniden numaralandır

Gözetimsiz hatlar için dfsReject'i öntanımlı yapın ve 705'i, kaynak formların sahibi olan kişiye bir iş fişi olarak görün. Bir alanı akış yukarısında bir kez yeniden adlandırmak, bir birleştirmenin Total_2 uydurduğu için bir dışa aktarma eşlemesinin sessizce eşleşmeyi bıraktığını aylar sonra keşfetmekten ucuzdur. Otomatik stratejiler, bir insan formlara bakmış ve paylaşılan adların ne anlama geldiğine karar vermiş olduğunda hak ettikleri yeri bulur

dfsMerge paylaşılan adı kasıtlı olarak korur. Hiçbir şey eklenmeden önce hedef alanın değeri ile varsayılan değeri gelen alana kopyalanır; böylece birleşik dosya tutarlı başlar ve widget'ları ada göre gruplayan bir görüntüleyici tek değerli tek mantıksal alan görür. İki alan sözlüğü ayrı nesneler olarak kalır; her biri kendi sayfasını, görünümünü ve eylemlerini tutar. Onları tek bir sözlüğe katlamak, gelen forma ait biçimlendirme ile davranışı çöpe atmak olurdu ve o takas, kozmetik bir sadeleşme için değmez

dfsAutoNumber, gelen yinelenenleri sayısal bir sonek ekleyerek yeniden adlandırır; _2'den başlar ve ilk boş olanı alır. Hedefte hâlâ Shared ile Shared_2 varsa gelen, Shared_3 olur. Sonuç yalnızca mevcut adlara bağlıdır, asla nesne numaralarına değil; böylece aynı dosya çiftini iki kez birleştirmek her iki seferde de aynı adları verir — akış aşağısındaki FDF içe aktarmalarının ve veritabanı eşlemelerinin dayandığı özellik budur

PDF Library for Delphi: MergeDocumentEx sonrası üç yinelenen alan sonucu; dfsReject her iki form sağlamken 705 hatasını döndürür, dfsMerge paylaşılan adlı widget'ları tek bir mantıksal değerde eşitler ve dfsAutoNumber yeniden üretilebilir bir _2 son eki ekler
dfsReject, bilinçli bir yeniden deneme için her iki belgeyi de el değmemiş tutar; dfsMerge, aynı adlı birden çok widget'ı tek bir eşitlenmiş değer taşıyan tek mantıksal alan sayar; dfsAutoNumber ise dış eşlemelerin öngörmesi gereken kararlı ekli adlar dağıtır

İki otomatik strateji arasında seçim tek bir soruya indirgenir: bir denetimi doldurmak diğerini de doldurmalı mı? Bir paketin her parçasında tekrarlanan imzalayan adı için evet, dfsMerge uyar. Her formda farklı hesaplanan bir toplam için hayır. Orada dfsAutoNumber'ı seçin; daha iyisi, kaynak formdaki alanı yeniden adlandırın ki sonek hiç görünmesin

Birleştirilmiş form sonrasında ne içerir?

Hedefte "Target value" taşıyan üst düzey bir Shared metin alanı, kaynakta da kendine ait bir Shared olsun. dfsMerge'den sonra FormFieldCount iki alan sayar: ikisi de Shared başlıklı, ikisi de "Target value" bildiriyor. dfsAutoNumber altında aynı girdi Shared ile Shared_2 verir ve gelen alan, kaynak dosyada hangi değere sahipse onu korur

dfsMerge sonucunun keskin bir kenarı vardır ve o, sizin kendi doldurma kodunuzda oturur. FindFormFieldByTitle, başlığı eşleşen ilk indeksi döndürür ve SetFormFieldValue tam olarak tek bir alana yazar. Shared'i bir kez arayıp ayarlayan bir yordam, hedefin kopyasını günceller ve gelen kopyayı birleştirme anında aldığı değerle bırakır. Kaydedilen dosya artık tek ada ve iki farklı değere sahip iki alan içerir ve görüntüleyicinin hangisini göstereceği görüntüleyiciye kalmıştır. Bunun yerine her eşleşmeyi yazın:

// Title taşıyan her alanı ayarlar; kaçının yazıldığını döndürür.
// dfsMerge birleştirmesinden sonra tek mantıksal alan birkaç indekste görünebilir
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]));   // salt-okunur alanlar buraya düşer
    end;
end;

Birleşik bir paketi bir veri hattına bağlamadan önce birleştirmenin gerçekte ürettiğini dökün. İki satırlık bir döngü yeterlidir ve yeniden adlandırılan ataları ile _2 soneklerini, bir içe aktarma işinden önce yakalar:

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

Form paketini pratikte bir araya getirmek

Başarılı bir birleştirme kaynak belgeyi tüketir. Kütüphanenin belge listesinden kaldırılır; DocumentCount'un bir düşmesinin nedeni budur ve eski SourceDoc tanımlayıcısı bir daha kullanılmamalıdır. Birleşik belge, iki PDF sürümünden yüksek olanı alır: bir PDF 2.0 formunu 1.7 belgesine birleştirmek 2.0 dosya verir; akış aşağısındaki bir arşivleme adımı belirli bir sürüm bekliyorsa bu önem taşır

Birleştirme sırası, kimin adlarının hayatta kaldığına karar verir. Seçili belge adlarının hepsini korur; yeniden adlandırmalar ve değer kopyaları yalnızca gelen alanlara uygulanır, dolayısıyla A'yı B'ye birleştirmek ile B'yi A'ya birleştirmek farklı otomatik numaralı sonuçlar verir. Bir paketin birincil bir formu olduğunda — arka ofisinizin alan adlarını hâlihazırda bildiği form — onu hedef yapın ve ekleri ona birleştirin

İmzayı sona bırakın. Bir imza, imzaladığı revizyonun baytlarını kapsar ve birleştirme dosyayı yeniden yazar; montajdan önce imzalanmış bir parça bu yüzden belgeyle eşleşen bir imza taşımaz. Paketi bir araya getirin, alan listesini denetleyin, sonra imzaları bitmiş dosyaya uygulayın. İş yalnızca sayfaları birbirine dikmekle ilgiliyse ve formlar önemsizse, bayt referansı kaydırmayla hızlı PDF birleştirme daha hızlı yoldur

Veri tarafını birleştirmeyle birlikte planlayın. Alan değerleri, alanlara ada göre başvuran harici bir sistemden geliyorsa adlandırmaya dfsAutoNumber'ı seçmeden önce karar verin; çünkü Shared_2, Shared bekleyen bir eşlemeyle eşleşmez. Değer içe ve dışa aktarma biçimleri FDF, XFDF ve XFA form veri değişimi yazısında ele alınır; alanlara ada göre başvuran hesaplama betikleri ve eylemler de yeniden adlandırmadan aynı şekilde etkilenir ve etkileşimli form eylemleri ve JavaScript yazısı o referansların nerede yaşadığını gösterir

Yinelenen alan farkında form birleştirme, alan doldurma ve dijital imzalama, Delphi, C++Builder ve Free Pascal projeleri için aynı kütüphanenin parçalarıdır. PDF Library for Delphi ürün sayfası, form ve belge birleştirme API'sinin geri kalanını listeler