Dari formulir yang bisa diisi ke rekaman yang dibekukan: isi dan ratakan AcroForm

Spec: ISO 32000-2, §12.7

Sekilas

Sebuah formulir PDF memiliki dua kehidupan. Pertama ia bisa diisi: seperangkat field bertipe yang seseorang ketikkan ke dalamnya, centang, atau pilih darinya. Lalu, ketika kesepakatan dibuat, ia menjadi sebuah rekaman beku: nilai-nilainya dicetak ke dalam halaman itu sendiri sehingga setiap penampil, pada setiap perangkat, melihat persis apa yang disepakati. NextPDF membangun yang pertama dan menghasilkan yang kedua, dengan satu jaminan yang disengaja — ia tidak akan diam-diam membuang nilai-nilainya di tengah jalan.

Mengapa ini penting

Jurang antara “apa yang saya isi” dan “apa yang Anda lihat” adalah tempat formulir menjadi salah.

Sebuah field yang bisa diisi, secara teknis, adalah sebuah widget interaktif kecil yang digambar di atas halaman. Penampil yang berbeda dapat merendernya secara berbeda. Ada yang menghormati nilai yang tersimpan, ada yang membangun ulang tampilannya dari sebuah fon yang tidak Anda miliki, ada yang membiarkan seorang pembaca menyuntingnya lagi. Untuk sebuah draf yang Anda ingin agar kolaborator terus menyuntingnya, itulah intinya. Untuk salinan yang ditandatangani atas apa yang disepakati, itu adalah sebuah liabilitas: rekaman itu tidak seharusnya bergantung pada aplikasi mana yang membukanya, dan ia tidak seharusnya dapat disunting setelah fakta.

Meratakan menutup jurang itu. Ia mengambil nilai saat ini dari setiap field dan mencetaknya ke dalam halaman sebagai grafik biasa yang tak dapat diubah — jenis konten yang sama dengan sebuah heading atau sebuah logo. Setelah itu, tidak ada field untuk disunting dan tidak ada tampilan untuk dibangun ulang. Dokumen menampilkan satu hal, hal yang sama, di mana-mana.

Versi singkat

Sebuah AcroForm adalah formulir interaktif dokumen: sebuah pohon field bertipe yang dideklarasikan dalam katalog (Spec: ISO 32000-2, §12.7).
Setiap field dijadikan terlihat oleh sebuah widget annotation — persegi panjang di halaman yang Anda klik atau ketik ke dalamnya (Spec: ISO 32000-2, §12.5).
NextPDF mengirimkan builder bertipe untuk setiap kontrol formulir non-tanda-tangan yang didukung — text, checkbox, radio, list box dan combo box (choice), dan push button — ditambah sebuah field manager yang menulisnya sebagai objek PDF yang benar.
Meratakan merender nilai setiap field ke dalam content stream halaman dan menghapus formulir interaktif yang kini berlebihan, meninggalkan sebuah rekaman beku.
Jika Anda meminta untuk meratakan sebuah dokumen yang tidak memiliki halaman, NextPDF tidak diam-diam menghancurkan nilai field Anda. Ia mempertahankan formulirnya, memperingatkan Anda, dan membiarkan Anda menambahkan sebuah halaman lalu meratakan dengan benar.

Bagaimana NextPDF menanganinya

Model mentalnya adalah dua lapisan. Field adalah datanya: sebuah nama, sebuah tipe, sebuah nilai, dan seperangkat flag. Widget adalah gambarnya: sebuah persegi panjang pada sebuah halaman tertentu yang membiarkan sebuah penampil berinteraksi dengan field itu (Spec: ISO 32000-2, §12.5). Satu field bahkan dapat muncul melalui beberapa widget — itulah persis bagaimana sebuah radio group bekerja, beberapa pilihan di halaman yang terhubung ke satu nilai yang mendasarinya.

NextPDF memberi setiap tipe field builder bertipenya sendiri, sehingga Anda tidak pernah merakit sebuah dictionary mentah dengan tangan. Tipe itu membawa detail yang PDF-correct untuk Anda. Sebuah checkbox, sebuah radio button, dan sebuah push button sama-sama berbagi tipe formulir yang mendasarinya dalam spec dan dibedakan oleh flag-nya; mesin menyetel flag itu dari tipe yang Anda pilih, alih-alih meminta Anda mengingat bit mana yang berarti “radio”. Sebuah list box dan sebuah combo box keduanya adalah field choice; sekali lagi, builder yang memilih pengodean yang tepat. Anda menyatakan tipe field sekali, dalam kata-kata, dan byte-nya menyusul.

Meratakan adalah separuh kedua. Flattener mengelompokkan widget annotation berdasarkan halaman pemiliknya, menggunakan persegi panjang setiap widget untuk penempatan pada halaman itu, lalu merender setiap nilai sebagai sederet kecil operator content-stream — setel sebuah warna, setel sebuah posisi teks, gambar glif-glifnya — yang ditambahkan ke konten halaman itu yang sudah ada (Spec: ISO 32000-2, §8.4). Nilai itu berhenti menjadi field yang hidup dan menjadi tinta yang tercetak. Karena formulirnya tidak lagi membawa field interaktif apa pun, mesin kemudian menghapus entri AcroForm: tidak ada lagi yang tersisa untuk menjadi interaktif.

Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
Place the widgetsEach field is drawn as a widget annotation — a rectangle on a chosen page that a viewer can type into, tick, or pick from.
Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
Drop the interactive formWith every value baked in, remove the AcroForm so nothing remains editable — a frozen record of what was agreed.

From a fillable form to a frozen record: declare typed fields, draw their on-page widgets, fill in values, then flatten those values into immutable page graphics and drop the now-empty interactive form.

Contoh praktis

Sebuah formulir kecil yang representatif: bangun beberapa field bertipe, lalu ratakan menjadi sebuah rekaman beku.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();

// Typed builders, called straight on the document. You pick the field
// type by choosing its builder method — textField, checkBox, comboBox —
// and you pass the value to freeze at creation time. The engine writes
// the spec-correct PDF type and flags for you.
$document->textField('full_name', x: 40, y: 700, w: 220, h: 18, default: 'Ada Lovelace');
$document->checkBox('agree_terms', x: 40, y: 660, size: 14, checked: true);
$document->comboBox(
    'plan',
    x: 40,
    y: 620,
    w: 160,
    h: 18,
    items: ['Starter', 'Team', 'Enterprise'],
    selected: 'Team',
);

// Flatten: the values become immutable page graphics and the
// interactive AcroForm is dropped. The result is a frozen record.
$document->flattenForms();

$bytes = $document->getPdfData();

Sebelum flattenForms(), ini adalah sebuah formulir yang bisa diisi. Setelahnya, nilai yang sama dicetak ke dalam halaman dan tidak ada field yang tersisa untuk diubah. Anda memilih tipe field dengan memilih metode builder-nya — textField, checkBox, comboBox — sehingga sebuah tipe yang keliru tidak dapat dikodekan sebagai sebuah string yang longgar: sebuah salah ketik adalah sebuah panggilan ke sebuah metode yang tidak ada, tertangkap sebelum field apa pun ditulis, bukan sebuah field yang diam-diam salah. Itu adalah pendirian menolak-menebak yang sama yang diambil seluruh mesin lainnya; lihat an API that refuses to guess.

Kesalahpahaman umum

Jebakannya adalah meyakini bahwa mengisi sebuah field membekukannya. Tidak. Sebuah field yang terisi tetap membawa sebuah nilai hidup yang dapat disunting oleh sebuah penampil yang cakap, dan sebuah tampilan yang akan dibangun ulang oleh sebagian penampil. “Saya menyetel nilainya” dan “dokumen kini sebuah rekaman tetap” adalah dua keadaan yang berbeda. Hanya meratakan yang menyeberang dari satu ke yang lain, karena hanya meratakan yang mengubah nilai itu menjadi grafik halaman yang tidak lagi berperilaku seperti sebuah field.

Kesalahan kebalikannya adalah meratakan sebuah draf yang masih Anda butuhkan untuk mengumpulkan masukan. Begitu diratakan, field-nya lenyap — itulah seluruh intinya — jadi ratakan salinan yang Anda maksudkan untuk menjadi final, bukan salinan yang masih Anda edarkan.

Ada satu nuansa operabilitas yang layak diketahui. Jika Anda meminta mesin untuk meratakan sebuah dokumen yang tidak memiliki halaman, ia tidak diam-diam membuang nilai field Anda. Tidak ada permukaan halaman untuk mencetaknya, jadi alih-alih melucuti formulir interaktif dan menihilkan nilainya — sebuah kehilangan data yang total dan tak terlihat — NextPDF mempertahankan formulirnya, menjaga setiap nilai tetap utuh dan tetap interaktif, dan memunculkan sebuah peringatan yang memberi tahu Anda apa yang terjadi. Anda menambahkan sebuah halaman dan meratakan lagi. Ini adalah sebuah rancangan tanpa-kehilangan-data yang disengaja: mesin lebih memilih mengembalikan sebuah dokumen yang masih bisa diisi disertai sebuah peringatan yang jelas daripada sebuah dokumen yang diam-diam dikosongkan. Nilai-nilai yang dipercayakan kepada Anda adalah satu hal yang tidak boleh pernah dibuang oleh sebuah proses meratakan.

Batasan dan ruang lingkup

Dukungan formulir NextPDF adalah inti penuh: builder bertipe untuk kontrol field interaktif yang umum, sebuah form flattener, dan sebuah field manager yang menulis field sebagai objek PDF yang benar. Halaman ini menggambarkan permukaan inti itu.

AcroForm fields and flattening — edition availability
Edition	Availability
Core	Typed builders for text, checkbox, radio, choice (list box and combo box), and push-button fields; widget placement; a field manager; and a form flattener that bakes values into page graphics. Available in every edition.
Pro	Not in this edition
Enterprise	Not in this edition

Meratakan bersifat satu arah secara rancangan. Ia menghapus formulir interaktif sehingga rekamannya tetap; ia bukan sebuah sakelar “kunci sementara”, dan tidak ada un-flatten yang menurunkan kembali field yang dapat disunting dari grafik yang tercetak. Jika Anda membutuhkan sebuah salinan yang dapat terus disunting orang, simpan formulir yang belum diratakan dan ratakan sebuah duplikat.

Meratakan juga bukan sebuah tanda tangan. Ia membuat sebuah dokumen tidak dapat disunting dalam pengertian penampil biasa, tetapi ia tidak membuktikan secara kriptografis siapa yang menghasilkannya atau bahwa ia tidak berubah sejak itu. Ketika rekamannya harus terbukti adalah yang disepakati, ratakan lalu tandatangani; lihat how signatures sit in a PDF.

Terakhir, sebuah formulir yang ber-tag dan dapat diakses adalah perhatian yang terpisah dari yang diratakan. Jika versi yang bisa diisi harus dapat digunakan dengan teknologi bantu, field-nya membutuhkan nama dan struktur yang dapat diakses selagi ia masih interaktif; lihat what makes a PDF accessible.

Dokumen terkait

What makes a PDF accessible — field formulir yang ber-tag dan nama yang dapat diakses, untuk tahap yang bisa diisi.
An API that refuses to guess — mengapa tipe field adalah sebuah enum bertipe, bukan sebuah string yang harus ditafsirkan mesin.
The anatomy of a PDF file — tempat katalog, halaman, dan annotation yang menjadi bahan baku sebuah formulir benar-benar berada.
How signatures sit in a PDF — bagaimana membuat sebuah rekaman beku terbukti adalah yang disepakati.

Glosarium

AcroForm — formulir interaktif sebuah PDF: pohon field bertipe yang dideklarasikan dalam document catalogue yang membuat berkas bisa diisi (Spec: ISO 32000-2, §12.7).
Field — sisi data dari sebuah kontrol formulir: sebuah nama, sebuah tipe, sebuah nilai, dan flag. Independen dari bagaimana ia terlihat di halaman.
Widget annotation — persegi panjang yang terlihat dan dapat diklik pada sebuah halaman yang melaluinya sebuah penampil berinteraksi dengan sebuah field (Spec: ISO 32000-2, §12.5). Satu field dapat memiliki beberapa.
Choice field — sebuah field yang menawarkan seperangkat opsi: sebuah list box menampilkannya terbuka, sebuah combo box menampilkan sebuah drop-down. Keduanya adalah tipe field PDF yang sama.
Flatten — merender nilai saat ini dari setiap field ke dalam halaman sebagai grafik yang tak dapat diubah dan menghapus formulir interaktif, menghasilkan sebuah rekaman beku.
Frozen record — sebuah dokumen yang diratakan: ia menampilkan satu hal tetap di setiap penampil dan tidak memiliki field yang tersisa untuk disunting.