Skip to content

Commit ac452f3

Browse files
SF4524LogeshKumarSF4524LogeshKumar
committed
1008847: Forms UG Update MVC II
1 parent f98d88a commit ac452f3

12 files changed

Lines changed: 2116 additions & 9 deletions

File tree

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

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
layout: post
3+
title: Add custom data to form fields in MVC 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 MVC PDF Viewer.
5+
platform: document-processing
6+
control: PDF Viewer
7+
documentation: ug
8+
---
9+
10+
# Add Custom Data to PDF Form Fields in MVC PDF Viewer
11+
12+
The **Syncfusion MVC 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+
35+
<div style="width:100%;height:600px">
36+
@Html.EJS().PdfViewer("pdfviewer").DocumentPath("https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf").Render()
37+
</div>
38+
39+
<script>
40+
document.addEventListener("DOMContentLoaded", function () {
41+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
42+
pdfviewer.documentLoad = function () {
43+
var meta = { businessId: 'C-1024', tags: ['profile','kiosk'], requiredRole: 'admin' };
44+
pdfviewer.formDesignerModule.addFormField('Textbox', {
45+
name: 'Email',
46+
bounds: { X: 146, Y: 229, Width: 200, Height: 24 },
47+
customData: meta
48+
});
49+
};
50+
});
51+
</script>
52+
53+
{% endhighlight %}
54+
{% endtabs %}
55+
56+
## Set Default Custom Data for PDF Form Fields Added Using UI
57+
58+
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:
59+
60+
- [textFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_TextFieldSettings)
61+
- [passwordFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_PasswordFieldSettings)
62+
- [checkBoxFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_CheckBoxFieldSettings)
63+
- [radioButtonFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_RadioButtonFieldSettings)
64+
- [listBoxFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_ListBoxFieldSettings)
65+
- [dropDownFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_DropDownFieldSettings)
66+
- [signatureFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_SignatureFieldSettings)
67+
- [initialFieldSettings](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#Syncfusion_EJ2_PdfViewer_PdfViewer_InitialFieldSettings)
68+
69+
{% tabs %}
70+
{% highlight cshtml tabtitle="Standalone" %}
71+
72+
<div style="width:100%;height:600px">
73+
@Html.EJS().PdfViewer("pdfviewer").DocumentPath("https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf").Render()
74+
</div>
75+
76+
<script>
77+
document.addEventListener("DOMContentLoaded", function () {
78+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
79+
// Example for textbox defaults
80+
pdfviewer.textFieldSettings = {
81+
name: 'Textbox',
82+
customData: { group: 'contact', createdBy: 'designer', requiredRole: 'user' }
83+
};
84+
85+
// Example for checkbox defaults
86+
pdfviewer.checkBoxFieldSettings = {
87+
name: 'Checkbox',
88+
customData: { consentType: 'marketing', defaultChecked: false }
89+
};
90+
});
91+
</script>
92+
93+
{% endhighlight %}
94+
{% endtabs %}
95+
96+
## Update or Replace PDF Form Field Custom Data
97+
98+
You can modify the customData of an existing form field by using the [updateFormField()](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#updateFormField) method. The field can be identified using either its object reference or field ID.
99+
100+
{% tabs %}
101+
{% highlight cshtml tabtitle="Standalone" %}
102+
103+
<div style="width:100%;height:600px">
104+
@Html.EJS().PdfViewer("pdfviewer").DocumentPath("https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf").Render()
105+
</div>
106+
107+
<script>
108+
document.addEventListener("DOMContentLoaded", function () {
109+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
110+
// Retrieve existing fields
111+
var fields = pdfviewer.retrieveFormFields();
112+
var target = fields.find(function (f) { return f.name === 'Email'; });
113+
114+
if (target) {
115+
// Merge with existing customData to avoid overwriting
116+
var merged = Object.assign({}, target.customData || {}, { updatedAt: Date.now(), verified: true });
117+
pdfviewer.formDesignerModule.updateFormField(target, { customData: merged });
118+
}
119+
});
120+
</script>
121+
122+
{% endhighlight %}
123+
{% endtabs %}
124+
125+
**Tip:**
126+
Merge new values with the existing customData object before calling [updateFormField()](https://help.syncfusion.com/cr/aspnetmvc-js2/syncfusion.ej2.pdfviewer.pdfviewer.html#updateFormField) to avoid overwriting previously stored data.
127+
128+
## Read Custom Data from PDF Form Fields
129+
130+
You can access the customData property from any form field at any point in your application flow, such as:
131+
- After the document is loaded
132+
- During save or submit operations
133+
- While performing validation or conditional routing
134+
135+
{% tabs %}
136+
{% highlight cshtml tabtitle="Standalone" %}
137+
138+
<div style="width:100%;height:600px">
139+
@Html.EJS().PdfViewer("pdfviewer").DocumentPath("https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf").Render()
140+
</div>
141+
142+
<script>
143+
document.addEventListener("DOMContentLoaded", function () {
144+
var pdfviewer = document.getElementById('pdfviewer').ej2_instances[0];
145+
pdfviewer.documentLoad = function () {
146+
var fields = pdfviewer.retrieveFormFields();
147+
fields.forEach(function (f) {
148+
console.log('Field:', f.name, 'customData:', f.customData);
149+
if (f.customData && f.customData.requiredRole === 'admin') {
150+
// mark field for special handling
151+
}
152+
});
153+
};
154+
});
155+
</script>
156+
157+
{% endhighlight %}
158+
{% endtabs %}
159+
160+
## Best Practices
161+
162+
- Treat customData as application metadata, not display data.
163+
- Use it to drive business rules, validation logic, and workflow decisions.
164+
- Keep the data minimal and structured for easy processing.
165+
- When cloning or copying form fields, ensure customData is copied or updated as required.
166+
167+
[View Sample on GitHub](https://github.com/SyncfusionExamples/mvc-pdf-viewer-examples)
168+
169+
## See Also
170+
171+
- [Form Designer overview](./overview)
172+
- [Form Designer Toolbar](../toolbar-customization/form-designer-toolbar)
173+
- [Create form fields](./overview-create-forms)
174+
- [Group form fields](../group-form-fields)
175+
- [Form flags](./form-constrain)
176+
- [Form validation](./form-validation)
177+
- [Form fields API](./form-fields-api)

0 commit comments

Comments
 (0)