|
| 1 | +--- |
| 2 | +layout: post |
| 3 | +title: Add custom data to form fields in JavaScript Pdf Viewer | Syncfusion |
| 4 | +description: Learn how to attach, update, and read custom Data on PDF form fields using the Form Designer UI and APIs in the Syncfusion JavaScript PDF Viewer. |
| 5 | +platform: document-processing |
| 6 | +control: PDF Viewer |
| 7 | +documentation: ug |
| 8 | +--- |
| 9 | + |
| 10 | +# Add custom data to form fields in JS |
| 11 | + |
| 12 | +You can associate arbitrary metadata with any form field using the customData property. This is useful for storing business IDs, validation hints, tags, or any app-specific information alongside the field. The data stays with the field object during the viewer session and can be accessed whenever you query or update fields. |
| 13 | + |
| 14 | +N> customData is a free-form object. You control both its shape and how it is used in your application. |
| 15 | + |
| 16 | +## Add custom data when creating fields (programmatically) |
| 17 | + |
| 18 | +Pass a customData object in the second parameter of addFormField. You can include any serializable values. |
| 19 | + |
| 20 | +```js |
| 21 | +// Inject required modules (ES5) |
| 22 | +ej.pdfviewer.PdfViewer.Inject( |
| 23 | + ej.pdfviewer.Toolbar, |
| 24 | + ej.pdfviewer.Magnification, |
| 25 | + ej.pdfviewer.Navigation, |
| 26 | + ej.pdfviewer.LinkAnnotation, |
| 27 | + ej.pdfviewer.ThumbnailView, |
| 28 | + ej.pdfviewer.BookmarkView, |
| 29 | + ej.pdfviewer.TextSelection, |
| 30 | + ej.pdfviewer.Annotation, |
| 31 | + ej.pdfviewer.FormDesigner, |
| 32 | + ej.pdfviewer.FormFields |
| 33 | +); |
| 34 | + |
| 35 | +var viewer = new ej.pdfviewer.PdfViewer({ |
| 36 | + documentPath: 'https://cdn.syncfusion.com/content/pdf/form-designer.pdf', |
| 37 | + resourceUrl: 'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib' |
| 38 | +}); |
| 39 | +viewer.appendTo('#pdfViewer'); |
| 40 | + |
| 41 | +viewer.documentLoad = function() { |
| 42 | + var meta = { businessId: 'C-1024', tags: ['profile', 'kiosk'], requiredRole: 'admin' }; |
| 43 | + viewer.formDesignerModule.addFormField('Textbox', { |
| 44 | + name: 'Email', |
| 45 | + bounds: { X: 146, Y: 229, Width: 200, Height: 24 }, |
| 46 | + // Attach any custom metadata your app needs |
| 47 | + customData: meta |
| 48 | + }); |
| 49 | +}; |
| 50 | +``` |
| 51 | + |
| 52 | +N> To configure the server-backed PDF Viewer, set: |
| 53 | +`viewer.serviceUrl = 'https://document.syncfusion.com/web-services/pdf-viewer/api/pdfviewer/';` |
| 54 | + |
| 55 | +## Set default custom data for UI-created fields |
| 56 | + |
| 57 | +When users add fields via the Form Designer toolbar, you can predefine default customData using the per-field settings objects. |
| 58 | + |
| 59 | +```js |
| 60 | +// Example: default custom data for all new Textbox fields added from the toolbar |
| 61 | +viewer.textFieldSettings = { |
| 62 | + name: 'Textbox', |
| 63 | + customData: { group: 'contact', createdBy: 'designer', requiredRole: 'user' } |
| 64 | +}; |
| 65 | +``` |
| 66 | + |
| 67 | +You can do the same for other field types using passwordFieldSettings, checkBoxFieldSettings, radioButtonFieldSettings, listBoxFieldSettings, dropDownFieldSettings, signatureFieldSettings, and initialFieldSettings. |
| 68 | + |
| 69 | +## Update or replace custom data on existing fields |
| 70 | + |
| 71 | +Use updateFormField to set or modify the customData of any existing field (retrieved by object or ID). |
| 72 | + |
| 73 | +```js |
| 74 | +var fields = viewer.retrieveFormFields(); |
| 75 | +var target = fields[0]; |
| 76 | +viewer.formDesignerModule.updateFormField(target, { |
| 77 | + customData: { group: 'profile', flags: ['pii', 'masked'], updatedAt: Date.now() } |
| 78 | +}); |
| 79 | +``` |
| 80 | + |
| 81 | +Tip: You can merge new values with existing ones in your app code before calling updateFormField. |
| 82 | + |
| 83 | +## Read custom data |
| 84 | + |
| 85 | +You can read customData from any field at any time. Typical entry points: |
| 86 | +- After document load |
| 87 | +- On your own UI actions (save, validate, route, etc.) |
| 88 | + |
| 89 | +```js |
| 90 | +viewer.documentLoad = function() { |
| 91 | + var fields = viewer.retrieveFormFields(); |
| 92 | + fields.forEach(function(f) { |
| 93 | + console.log('Field', f.name, 'customData:', f.customData); |
| 94 | + }); |
| 95 | +}; |
| 96 | +``` |
| 97 | + |
| 98 | +## Notes and best practices |
| 99 | + |
| 100 | +- Keep customData small and serializable (plain objects, arrays, numbers, strings, booleans). |
| 101 | +- Treat customData as application metadata. Use it to drive business rules, validation, or routing in your app. |
| 102 | +- When cloning or copying fields in your UI, also copy or adjust customData as needed. |
| 103 | + |
| 104 | +[View Sample on GitHub](https://github.com/SyncfusionExamples/javascript-pdf-viewer-examples) |
| 105 | + |
| 106 | +## See also |
| 107 | + |
| 108 | +- [Form Designer overview](./overview) |
| 109 | +- [Form Designer Toolbar](../toolbar-customization/form-designer-toolbar) |
| 110 | +- [Create form fields](./Create-edit-Style-del-formFields/create-formfields) |
| 111 | +- [Edit form fields](./Create-edit-Style-del-formFields/edit-formfields) |
| 112 | +- [Group form fields](./group-formfields) |
| 113 | +- [Form constrain](./form-constrain) |
| 114 | +- [Form validation](./form-validation) |
| 115 | +- [Form fields API](./formfields-api) |
0 commit comments