Skip to content

Commit 8865747

Browse files
SF4524LogeshKumarSF4524LogeshKumar
committed
1008615: UG Forms Core - Updates Part I
1 parent e906795 commit 8865747

15 files changed

Lines changed: 2749 additions & 0 deletions

‎Document-Processing/PDF/PDF-Viewer/asp-net-core/forms/custom-data.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
layout: post
3+
title: Add custom data to form fields in ASP.NET Core 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 ASP.NET Core PDF Viewer.
5+
platform: document-processing
6+
control: PDF Viewer
7+
documentation: ug
8+
---
9+
10+
# Add Custom Data to PDF Form Fields in ASP.NET Core PDF Viewer
11+
12+
The **Syncfusion ASP.NET Core PDF Viewer** allows you to attach **custom application-specific data** to form fields by using the customData property. This enables you to associate business identifiers, tags, validation hints, or workflow metadata with form fields.
13+
14+
The custom data remains linked to the form field throughout the viewer session and can be accessed or updated whenever the field is queried or modified.
15+
16+
This page explains how to:
17+
- [Add custom data when creating form fields](#add-custom-data-while-creating-pdf-form-fields)
18+
- [Define default custom data for fields created using the UI](#set-default-custom-data-for-pdf-form-fields-added-using-ui)
19+
- [Update or replace custom data for existing fields](#update-or-replace-pdf-form-field-custom-data)
20+
- [Read custom data from form fields](#read-custom-data-from-pdf-form-fields)
21+
- [Apply best practices when using custom data](#best-practices)
22+
23+
**Key Points**
24+
- customData is a **free form object**; you control its structure.
25+
- Use only **serializable values** such as objects, arrays, strings, numbers, and booleans.
26+
- Custom data does not affect the field appearance or behavior unless consumed by your application logic.
27+
28+
## Add Custom Data While Creating PDF Form Fields
29+
30+
You can attach custom data at the time of field creation by passing a **customData** object in the settings parameter of **addFormField()**.
31+
32+
{% tabs %}
33+
{% highlight cshtml tabtitle="Standalone" %}
34+
<div class="text-center">
35+
<ejs-pdfviewer id="pdfviewer" style="height:600px" resourceUrl="https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib" documentPath="https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf">
36+
</ejs-pdfviewer>
37+
</div>
38+
<script type="text/javascript">
39+
document.addEventListener('DOMContentLoaded', function () {
40+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
41+
pdfviewer.documentLoad = function () {
42+
var meta = { businessId: 'C-1024', tags: ['profile','kiosk'], requiredRole: 'admin' };
43+
pdfviewer.formDesignerModule.addFormField('Textbox', {
44+
name: 'Email',
45+
bounds: { X: 146, Y: 229, Width: 200, Height: 24 },
46+
customData: meta
47+
});
48+
};
49+
});
50+
</script>
51+
{% endhighlight %}
52+
{% endtabs %}
53+
54+
## Set Default Custom Data for PDF Form Fields Added Using UI
55+
56+
When users add form fields using the [Form Designer toolbar](../toolbar-customization/form-designer-toolbar), you can define default customData so that newly created fields automatically inherit it. Default custom data can be configured using per-field settings objects such as:
57+
58+
- [textFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_TextFieldSettings)
59+
- [passwordFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_PasswordFieldSettings)
60+
- [checkBoxFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_CheckBoxFieldSettings)
61+
- [radioButtonFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_RadioButtonFieldSettings)
62+
- [listBoxFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_ListBoxFieldSettings)
63+
- [dropDownFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_DropDownFieldSettings)
64+
- [signatureFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_SignatureFieldSettings)
65+
- [initialFieldSettings](https://help.syncfusion.com/cr/aspnetcore-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_InitialFieldSettings)
66+
67+
{% tabs %}
68+
{% highlight cshtml tabtitle="Standalone" %}
69+
<div class="text-center">
70+
<ejs-pdfviewer id="pdfviewer" style="height:600px" resourceUrl="https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib" documentPath="https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf">
71+
</ejs-pdfviewer>
72+
</div>
73+
<script type="text/javascript">
74+
document.addEventListener('DOMContentLoaded', function () {
75+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
76+
// Example for textbox defaults
77+
pdfviewer.textFieldSettings = {
78+
name: 'Textbox',
79+
customData: { group: 'contact', createdBy: 'designer', requiredRole: 'user' }
80+
};
81+
82+
// Example for checkbox defaults
83+
pdfviewer.checkBoxFieldSettings = {
84+
name: 'Checkbox',
85+
customData: { consentType: 'marketing', defaultChecked: false }
86+
};
87+
});
88+
</script>
89+
{% endhighlight %}
90+
{% endtabs %}
91+
92+
## Update or Replace PDF Form Field Custom Data
93+
94+
You can modify the customData of an existing form field by using the [updateFormField()](https://ej2.syncfusion.com/documentation/api/pdfviewer/index-default#updateformfields) method. The field can be identified using either its object reference or field ID.
95+
96+
{% tabs %}
97+
{% highlight cshtml tabtitle="Standalone" %}
98+
<div class="text-center">
99+
<ejs-pdfviewer id="pdfviewer" style="height:600px" resourceUrl="https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib" documentPath="https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf">
100+
</ejs-pdfviewer>
101+
</div>
102+
<script type="text/javascript">
103+
document.addEventListener('DOMContentLoaded', function () {
104+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
105+
var fields = pdfviewer.retrieveFormFields();
106+
var target = fields.find(function (f) { return f.name === 'Email'; });
107+
if (target) {
108+
var merged = Object.assign({}, target.customData || {}, { updatedAt: Date.now(), verified: true });
109+
pdfviewer.formDesignerModule.updateFormField(target, { customData: merged });
110+
}
111+
});
112+
</script>
113+
{% endhighlight %}
114+
{% endtabs %}
115+
116+
**Tip:**
117+
Merge new values with the existing customData object before calling [updateFormField()](https://ej2.syncfusion.com/documentation/api/pdfviewer/index-default#updateformfields) to avoid overwriting previously stored data.
118+
119+
## Read Custom Data from PDF Form Fields
120+
121+
You can access the customData property from any form field at any point in your application flow, such as:
122+
- After the document is loaded
123+
- During save or submit operations
124+
- While performing validation or conditional routing
125+
126+
{% tabs %}
127+
{% highlight cshtml tabtitle="Standalone" %}
128+
<div class="text-center">
129+
<ejs-pdfviewer id="pdfviewer" style="height:600px" resourceUrl="https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib" documentPath="https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf">
130+
</ejs-pdfviewer>
131+
</div>
132+
<script type="text/javascript">
133+
document.addEventListener('DOMContentLoaded', function () {
134+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
135+
pdfviewer.documentLoad = function () {
136+
var fields = pdfviewer.retrieveFormFields();
137+
fields.forEach(function (f) {
138+
console.log('Field:', f.name, 'customData:', f.customData);
139+
if (f.customData && f.customData.requiredRole === 'admin') {
140+
// mark field for special handling
141+
}
142+
});
143+
};
144+
});
145+
</script>
146+
{% endhighlight %}
147+
{% endtabs %}
148+
149+
## Best Practices
150+
151+
- Treat customData as application metadata, not display data.
152+
- Use it to drive business rules, validation logic, and workflow decisions.
153+
- Keep the data minimal and structured for easy processing.
154+
- When cloning or copying form fields, ensure customData is copied or updated as required.
155+
156+
[View Sample on GitHub](https://github.com/SyncfusionExamples/asp-core-pdf-viewer-examples)
157+
158+
## See Also
159+
160+
- [Form Designer overview](./overview)
161+
- [Form Designer Toolbar](../toolbar-customization/form-designer-toolbar)
162+
- [Create form fields](./overview-create-forms)
163+
- [Group form fields](../group-form-fields)
164+
- [Form flags](./form-constrain)
165+
- [Form validation](./form-validation)
166+
- [Form fields API](./form-fields-api)

0 commit comments

Comments
 (0)