|
| 1 | +--- |
| 2 | +layout: post |
| 3 | +title: Form constraints in the TypeScript PDF Viewer component | Syncfusion |
| 4 | +description: Learn how to configure form field constraints such as isReadOnly, isRequired, and isPrint in the Syncfusion TypeScript PDF Viewer. |
| 5 | +platform: document-processing |
| 6 | +control: PDF Viewer |
| 7 | +documentation: ug |
| 8 | +--- |
| 9 | + |
| 10 | +# Form constraints in TypeScript PDF Viewer |
| 11 | + |
| 12 | +The PDF Viewer components provides support to control user interaction and output behavior of form fields using the following constraints: |
| 13 | + |
| 14 | +- isReadOnly: Prevents users from editing a field. |
| 15 | +- isRequired: Marks a field as mandatory and participates in validation. |
| 16 | +- isPrint: Includes the field appearance when printing or exporting with print. |
| 17 | + |
| 18 | +You can set these properties when you create fields, update them later programmatically, or configure default settings so fields created from the Form Designer toolbar inherit the values. |
| 19 | + |
| 20 | +## isReadOnly |
| 21 | + |
| 22 | +Use `isReadOnly` to make a field non-editable in the UI while keeping it modifiable via code. |
| 23 | + |
| 24 | +- Creation |
| 25 | +```ts |
| 26 | +pdfviewer.formDesignerModule.addFormField('Textbox', { |
| 27 | + name: 'EmployeeId', |
| 28 | + bounds: { X: 146, Y: 229, Width: 150, Height: 24 }, |
| 29 | + isReadOnly: true, |
| 30 | + value: 'EMP-0001' |
| 31 | +} as TextFieldSettings); |
| 32 | +``` |
| 33 | + |
| 34 | +- Update existing field |
| 35 | +```ts |
| 36 | +const field = pdfviewer.formFieldCollections.find(f => f.name === 'EmployeeId'); |
| 37 | +if (field) { |
| 38 | + pdfviewer.formDesignerModule.updateFormField(field, { isReadOnly: false } as TextFieldSettings); |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +- Default for new Textbox fields |
| 43 | +```ts |
| 44 | +pdfviewer.textFieldSettings = { isReadOnly: true }; |
| 45 | +``` |
| 46 | + |
| 47 | +## isRequired |
| 48 | + |
| 49 | +Use `isRequired` to mark fields as mandatory so they participate in validation during print/download. Turn on validation with enableFormFieldsValidation and handle validateFormFields to block actions if required fields are empty. |
| 50 | + |
| 51 | +- Creation |
| 52 | +```ts |
| 53 | +pdfviewer.formDesignerModule.addFormField('Textbox', { |
| 54 | + name: 'Email', |
| 55 | + bounds: { X: 146, Y: 260, Width: 220, Height: 24 }, |
| 56 | + isRequired: true, |
| 57 | + tooltip: 'Email is required' |
| 58 | +} as TextFieldSettings); |
| 59 | +``` |
| 60 | + |
| 61 | +- Validation wiring |
| 62 | +```ts |
| 63 | +pdfviewer.enableFormFieldsValidation = true; |
| 64 | +pdfviewer.validateFormFields = (args: any) => { |
| 65 | + //validateFormFields event triggers when fields are empty. |
| 66 | + alert("Please fill all required fields. Missing: "+args.formField[0].name); |
| 67 | +}; |
| 68 | +``` |
| 69 | + |
| 70 | +- Default for new Textbox fields |
| 71 | +```ts |
| 72 | +pdfviewer.textFieldSettings = { isRequired: true }; |
| 73 | +``` |
| 74 | + |
| 75 | +## isPrint |
| 76 | + |
| 77 | +Use `isPrint` to control whether a field’s appearance is included when printing the PDF from the viewer. |
| 78 | + |
| 79 | +- Creation (do not print a signature field) |
| 80 | +```ts |
| 81 | +pdfviewer.formDesignerModule.addFormField('SignatureField', { |
| 82 | + name: 'ApplicantSign', |
| 83 | + bounds: { X: 57, Y: 923, Width: 200, Height: 43 }, |
| 84 | + isPrint: false |
| 85 | +} as SignatureFieldSettings); |
| 86 | +``` |
| 87 | + |
| 88 | +- Update existing field |
| 89 | +```ts |
| 90 | +const sign = pdfviewer.formFieldCollections.find(f => f.name === 'ApplicantSign'); |
| 91 | +if (sign) { |
| 92 | + pdfviewer.formDesignerModule.updateFormField(sign, { isPrint: true } as SignatureFieldSettings); |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +- Default for new signature fields |
| 97 | +```ts |
| 98 | +pdfviewer.signatureFieldSettings = { isPrint: false }; |
| 99 | +``` |
| 100 | + |
| 101 | +N> Printing can be invoked programmatically using pdfviewer.print.print(); fields with isPrint: false will not appear in the print output. |
| 102 | + |
| 103 | +## Set constraints when creating a field |
| 104 | + |
| 105 | +Use `addFormField` to create fields and pass the constraint properties in the settings object. The example below adds a Textbox and a Signature field with different constraint combinations. |
| 106 | + |
| 107 | +```ts |
| 108 | +import { PdfViewer, Toolbar, Magnification, Navigation, LinkAnnotation, ThumbnailView, BookmarkView, |
| 109 | + TextSelection, Annotation, FormDesigner, FormFields, TextFieldSettings, SignatureFieldSettings } from '@syncfusion/ej2-pdfviewer'; |
| 110 | + |
| 111 | +PdfViewer.Inject(Toolbar, Magnification, Navigation, LinkAnnotation, ThumbnailView, BookmarkView, |
| 112 | + TextSelection, Annotation, FormDesigner, FormFields); |
| 113 | + |
| 114 | +let pdfviewer: PdfViewer = new PdfViewer({ |
| 115 | + documentPath: 'https://cdn.syncfusion.com/content/pdf/form-designer.pdf', |
| 116 | + resourceUrl: 'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib' |
| 117 | +}); |
| 118 | +pdfviewer.appendTo('#PdfViewer'); |
| 119 | + |
| 120 | +pdfviewer.documentLoad = () => { |
| 121 | + // Read-only Textbox that is printed but not required |
| 122 | + pdfviewer.formDesignerModule.addFormField('Textbox', { |
| 123 | + name: 'EmployeeId', |
| 124 | + bounds: { X: 146, Y: 229, Width: 150, Height: 24 }, |
| 125 | + isReadOnly: true, |
| 126 | + isRequired: false, |
| 127 | + isPrint: true, |
| 128 | + value: 'EMP-0001' |
| 129 | + } as TextFieldSettings); |
| 130 | + |
| 131 | + // Required Signature field that is not included in print |
| 132 | + pdfviewer.formDesignerModule.addFormField('SignatureField', { |
| 133 | + name: 'ApplicantSign', |
| 134 | + bounds: { X: 57, Y: 923, Width: 200, Height: 43 }, |
| 135 | + isReadOnly: false, |
| 136 | + isRequired: true, |
| 137 | + isPrint: false, |
| 138 | + tooltip: 'Sign to accept the terms' |
| 139 | + } as SignatureFieldSettings); |
| 140 | +}; |
| 141 | +``` |
| 142 | + |
| 143 | +N> To configure the server-backed PDF Viewer, add the following serviceUrl in index.ts: |
| 144 | +`pdfviewer.serviceUrl = 'https://document.syncfusion.com/web-services/pdf-viewer/api/pdfviewer/';` |
| 145 | + |
| 146 | +## Update constraints programmatically |
| 147 | + |
| 148 | +Use `updateFormField` to change constraint flags of an existing field. The snippet below toggles isReadOnly, sets a field as required, and controls whether the field should appear when printing. |
| 149 | + |
| 150 | +```ts |
| 151 | +import { PdfViewer, Toolbar, Magnification, Navigation, LinkAnnotation, ThumbnailView, BookmarkView, |
| 152 | + TextSelection, Annotation, FormDesigner, FormFields, TextFieldSettings } from '@syncfusion/ej2-pdfviewer'; |
| 153 | + |
| 154 | +PdfViewer.Inject(Toolbar, Magnification, Navigation, LinkAnnotation, ThumbnailView, BookmarkView, |
| 155 | + TextSelection, Annotation, FormDesigner, FormFields); |
| 156 | + |
| 157 | +let pdfviewer: PdfViewer = new PdfViewer({ |
| 158 | + documentPath: 'https://cdn.syncfusion.com/content/pdf/form-designer.pdf', |
| 159 | + resourceUrl: 'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib' |
| 160 | +}); |
| 161 | +pdfviewer.appendTo('#PdfViewer'); |
| 162 | + |
| 163 | +pdfviewer.documentLoad = () => { |
| 164 | + // Add a sample textbox |
| 165 | + pdfviewer.formDesignerModule.addFormField('Textbox', { |
| 166 | + name: 'Email', |
| 167 | + bounds: { X: 146, Y: 260, Width: 220, Height: 24 } |
| 168 | + } as TextFieldSettings); |
| 169 | + |
| 170 | + // Retrieve it and update constraint flags |
| 171 | + const field = pdfviewer.formFieldCollections.find(f => f.name === 'Email'); |
| 172 | + if (field) { |
| 173 | + pdfviewer.formDesignerModule.updateFormField(field, { |
| 174 | + isReadOnly: false, |
| 175 | + isRequired: true, |
| 176 | + isPrint: true, |
| 177 | + tooltip: 'Enter a valid email' |
| 178 | + } as TextFieldSettings); |
| 179 | + } |
| 180 | +}; |
| 181 | +``` |
| 182 | + |
| 183 | +## Configure default constraints for newly added fields |
| 184 | + |
| 185 | +Set default settings so all fields created from the Form Designer toolbar inherit the constraint flags. |
| 186 | + |
| 187 | +The example below configures defaults for Textbox and Signature fields. |
| 188 | + |
| 189 | +```ts |
| 190 | +import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, |
| 191 | + BookmarkView, TextSelection, FormDesigner, FormFields } from '@syncfusion/ej2-pdfviewer'; |
| 192 | + |
| 193 | +PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, |
| 194 | + BookmarkView, TextSelection, FormDesigner, FormFields); |
| 195 | + |
| 196 | +let pdfviewer: PdfViewer = new PdfViewer({ documentPath: 'https://cdn.syncfusion.com/content/pdf/form-designer.pdf' }); |
| 197 | +pdfviewer.appendTo('#PdfViewer'); |
| 198 | + |
| 199 | +// Textbox fields will be editable, required, and included in print by default |
| 200 | +pdfviewer.textFieldSettings = { |
| 201 | + isReadOnly: false, |
| 202 | + isRequired: true, |
| 203 | + isPrint: true, |
| 204 | + tooltip: 'Required field' |
| 205 | +}; |
| 206 | + |
| 207 | +// Signature fields will be optional and hidden when printing |
| 208 | +pdfviewer.signatureFieldSettings = { |
| 209 | + isReadOnly: false, |
| 210 | + isRequired: false, |
| 211 | + isPrint: false, |
| 212 | + tooltip: 'Sign if applicable' |
| 213 | +}; |
| 214 | +``` |
| 215 | + |
| 216 | +## Behavior notes |
| 217 | + |
| 218 | +- isReadOnly only blocks user edits in the UI. You can still update the field programmatically. |
| 219 | +- isRequired participates in the built-in validation flow. Enable validation to enforce before print/download. See Validate form fields for details. |
| 220 | +- isPrint controls field appearance in the print output. It does not affect download/export unless printing is triggered. |
| 221 | + |
| 222 | +[View Sample on GitHub](https://github.com/SyncfusionExamples/typescript-pdf-viewer-examples) |
| 223 | + |
0 commit comments