Add form flattening to README

README.md

@@ -55,8 +55,9 @@
 - [Usage Examples](#usage-examples)
   - [Create Document](#create-document)
   - [Modify Document](#modify-document)
-  - [Create Form](#create-form) - _**new!**_
-  - [Fill Form](#fill-form) - _**new!**_
+  - [Create Form](#create-form)
+  - [Fill Form](#fill-form)
+  - [Flatten Form](#flatten-form) - _**new!**_
   - [Copy Pages](#copy-pages)
   - [Embed PNG and JPEG Images](#embed-png-and-jpeg-images)
   - [Embed PDF Pages](#embed-pdf-pages)
@@ -84,8 +85,9 @@
 
 - Create new PDFs
 - Modify existing PDFs
-- Create forms - _**new!**_
-- Fill forms - _**new!**_
+- Create forms
+- Fill forms
+- Flatten forms - _**new!**_
 - Add Pages
 - Insert Pages
 - Remove Pages
@@ -413,6 +415,54 @@ const pdfBytes = await pdfDoc.save()
 //   • Rendered in an <iframe>
 ```
 
+### Flatten Form
+
+_This example produces [this PDF](assets/pdfs/examples/flatten_form.pdf)_ (when [this PDF](assets/pdfs/form_to_flatten.pdf) is used for the `formPdfBytes` variable).
+
+<!-- [Try the JSFiddle demo](https://jsfiddle.net/Hopding/0mwfqkv6/3/) -->
+
+<!-- prettier-ignore -->
+```js
+import { PDFDocument } from 'pdf-lib'
+
+// This should be a Uint8Array or ArrayBuffer
+// This data can be obtained in a number of different ways
+// If your running in a Node environment, you could use fs.readFile()
+// In the browser, you could make a fetch() call and use res.arrayBuffer()
+const formPdfBytes = ...
+
+// Load a PDF with form fields
+const pdfDoc = await PDFDocument.load(formPdfBytes)
+
+// Get the form containing all the fields
+const form = pdfDoc.getForm()
+
+// Fill the form's fields
+form.getTextField('Text1').setText('Some Text');
+
+form.getRadioGroup('Group2').select('Choice1');
+form.getRadioGroup('Group3').select('Choice3');
+form.getRadioGroup('Group4').select('Choice1');
+
+form.getCheckBox('Check Box3').check();
+form.getCheckBox('Check Box4').uncheck();
+
+form.getDropdown('Dropdown7').select('Infinity');
+
+form.getOptionList('List Box6').select('Honda');
+
+// Flatten the form's fields
+form.flatten();
+
+// Serialize the PDFDocument to bytes (a Uint8Array)
+const pdfBytes = await pdfDoc.save()
+
+// For example, `pdfBytes` can be:
+//   • Written to a file in Node
+//   • Downloaded from the browser
+//   • Rendered in an <iframe>
+```
+
 ### Copy Pages
 
 _This example produces [this PDF](assets/pdfs/examples/copy_pages.pdf)_ (when [this PDF](assets/pdfs/with_update_sections.pdf) is used for the `firstDonorPdfBytes` variable and [this PDF](assets/pdfs/with_large_page_count.pdf) is used for the `secondDonorPdfBytes` variable).

scratchpad/index.ts

@@ -3,24 +3,43 @@ import { openPdf, Reader } from './open';
 import { PDFDocument } from 'src/index';
 
 (async () => {
-  // Create a new PDFDocument
-  const pdfDoc = await PDFDocument.create();
+  // This should be a Uint8Array or ArrayBuffer
+  // This data can be obtained in a number of different ways
+  // If your running in a Node environment, you could use fs.readFile()
+  // In the browser, you could make a fetch() call and use res.arrayBuffer()
+  const formPdfBytes = fs.readFileSync('assets/pdfs/form_to_flatten.pdf');
 
-  // Set the title and include the new option.
-  pdfDoc.setTitle('Scratchpad Test Doc', { showInWindowTitleBar: true });
+  // Load a PDF with form fields
+  const pdfDoc = await PDFDocument.load(formPdfBytes);
 
-  // Add a blank page to the document
-  const page = pdfDoc.addPage([550, 750]);
+  // Get the form containing all the fields
+  const form = pdfDoc.getForm();
 
-  // Manual test...
-  page.drawText(
-    `The window's title should match what we set in the metadata.`,
-    { x: 15, y: 400, size: 15 },
-  );
+  // Fill the form's fields
+  form.getTextField('Text1').setText('Some Text');
 
-  // Save the PDF
+  form.getRadioGroup('Group2').select('Choice1');
+  form.getRadioGroup('Group3').select('Choice3');
+  form.getRadioGroup('Group4').select('Choice1');
+
+  form.getCheckBox('Check Box3').check();
+  form.getCheckBox('Check Box4').uncheck();
+
+  form.getDropdown('Dropdown7').select('Infinity');
+
+  form.getOptionList('List Box6').select('Honda');
+
+  // Flatten the form's fields
+  form.flatten();
+
+  // Serialize the PDFDocument to bytes (a Uint8Array)
   const pdfBytes = await pdfDoc.save();
 
+  // For example, `pdfBytes` can be:
+  //   • Written to a file in Node
+  //   • Downloaded from the browser
+  //   • Rendered in an <iframe>
+
   fs.writeFileSync('out.pdf', pdfBytes);
-  openPdf('out.pdf', Reader.Acrobat);
+  openPdf('out.pdf', Reader.Preview);
 })();

src/api/form/PDFForm.ts

@@ -513,10 +513,19 @@ export default class PDFForm {
   }
 
   /**
-   * Flatten all form fields.
+   * Flatten all fields in this [[PDFForm]].
    *
-   * Flattening a form field will take the current appearance and make that part
-   * of the pages content stream. All form fields and annotations associated are removed.
+   * Flattening a form field will take the current appearance for each of that
+   * field's widgets and make them part of their page's content stream. All form
+   * fields and annotations associated are then removed. Note that once a form
+   * has been flattened its fields can no longer be accessed or edited.
+   *
+   * This operation is often used after filling form fields to ensure a
+   * consistent appearance across different PDF readers and/or printers.
+   * Another common use case is to copy a template document with form fields
+   * into another document. In this scenario you would load the template
+   * document, fill its fields, flatten it, and then copy its pages into the
+   * recipient document - the filled fields will be copied over.
    *
    * For example:
    * ```js