1026449: Blazor PDF Viewer Forms Restructure and Revamp

Document-Processing-toc.html

@@ -1193,14 +1193,30 @@
 									<li><a href="/document-processing/pdf/pdf-viewer/blazor/redaction/mobile-view">Mobile View</a></li>
 								</ul>
 							</li>
-							<li>Form Designer
-								<ul>
-									<li><a href="/document-processing/pdf/pdf-viewer/blazor/form-designer/overview">Overview</a></li>
-									<li><a href="/document-processing/pdf/pdf-viewer/blazor/form-designer/create-programmatically">Programmatic Support</a></li>
-									<li><a href="/document-processing/pdf/pdf-viewer/blazor/form-designer/ui-interactions">UI Interactions</a></li>
-									<li><a href="/document-processing/pdf/pdf-viewer/blazor/form-designer/form-designer-in-mobile-view">Mobile View</a></li>
-									<li><a href="/document-processing/pdf/pdf-viewer/blazor/form-designer/custom-font">Custom Font</a></li>
-									<li><a href="/document-processing/pdf/pdf-viewer/blazor/form-designer/events">Events</a></li>
+							<li>Forms
+								<ul>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/overview">Overview</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/form-filling">Fill form fields</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/form-designer">Form Designer and Toolbar</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/overview-create-forms">Create, Edit, Style and Remove Form Fields</a>
+										<ul>
+											<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/manage-form-fields/create-form-fields">Create form fields</a></li>
+											<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/manage-form-fields/modify-form-fields">Modify form fields</a></li>
+											<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/manage-form-fields/customize-form-fields">Customize form fields</a></li>
+											<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/manage-form-fields/move-resize-form-fields">Move and Resize form fields</a></li>
+											<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/manage-form-fields/remove-form-fields">Remove form fields</a></li>
+										</ul>
+									</li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/export-import-formfields">Export and Import Form Fields</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/custom-data">Add custom data in form fields</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/group-form-fields">Grouping form fields</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/form-constrain">Form Field Flags</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/custom-font">Custom fonts</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/form-handling-best-practices">PDF Form Handling Best Practices</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/form-field-events">Form Field events</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/flatten-form-fields">Flatten form fields</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/read-form-field-values">Read form fields</a></li>
+									<li><a href="/document-processing/pdf/pdf-viewer/blazor/forms/form-designer-in-mobile-view">Mobile View</a></li>
 								</ul>
 							</li>
 							<li> <a href="/document-processing/pdf/pdf-viewer/blazor/form-filling">Form Filling</a></li>

Document-Processing/PDF/PDF-Viewer/blazor/forms/custom-data.md

@@ -0,0 +1,183 @@
+---
+layout: post
+title: Add custom data to form fields in Blazor SfPdfViewer | Syncfusion
+description: Learn how to attach, update, and read custom data on PDF form fields using programmatic APIs in the Syncfusion Blazor SfPdfViewer.
+platform: document-processing
+control: SfPdfViewer
+documentation: ug
+---
+
+# Add Custom Data to PDF Form Fields in Blazor SfPdfViewer
+
+The **Syncfusion Blazor SfPdfViewer** 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.
+
+Custom data remains associated with the form field for the duration of the viewer session and can be accessed or updated whenever the field is queried or modified.
+
+This article explains how to:
+- [Add custom data when creating form fields programmatically](#add-custom-data-while-creating-pdf-form-fields)
+- [Update or replace custom data for existing fields](#update-or-replace-pdf-form-field-custom-data)
+- [Read custom data from form fields](#read-custom-data-from-pdf-form-fields)
+- [Apply best practices when using custom data](#best-practices)
+
+**Key Points**
+- `CustomData` is a **free form object**; you control its structure.
+- Use only **serializable values** such as objects, arrays, strings, numbers, and booleans.
+- Custom data does not affect the field appearance or behavior unless consumed by your application logic.
+
+## Add Custom Data While Creating PDF Form Fields
+
+Attach custom data at field creation by passing a `CustomData` object to the form field when using [`AddFormFieldsAsync()`](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.SfPdfViewer.PdfViewerBase.html#Syncfusion_Blazor_SfPdfViewer_PdfViewerBase_AddFormFieldsAsync_System_Collections_Generic_List_Syncfusion_Blazor_SfPdfViewer_FormFieldInfo__).
+
+{% tabs %}
+{% highlight razor %} 
+
+@using Syncfusion.Blazor.SfPdfViewer
+@using System.Collections.Generic
+
+<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
+    <PdfViewerEvents DocumentLoaded="@AddFormFieldsWithCustomData"></PdfViewerEvents>
+</SfPdfViewer2>
+
+@code {
+    private SfPdfViewer2? viewer;
+    private string DocumentPath = "wwwroot/data/form-designer.pdf";
+
+    private async Task AddFormFieldsWithCustomData()
+    {
+        if (viewer == null) return;
+
+        // Define custom metadata
+        var customMetadata = new Dictionary<string, object>
+        {
+            { "businessId", "C-1024" },
+            { "tags", new[] { "profile", "kiosk" } },
+            { "requiredRole", "admin" }
+        };
+
+        // Create a TextBox field with custom data
+        var textField = new TextBoxField
+        {
+            Name = "Email",
+            CustomData = customMetadata,
+            Bound = new Bound { X = 146, Y = 229, Width = 200, Height = 24 }
+        };
+
+        // Add the field to the document
+        await viewer.AddFormFieldsAsync(new List<FormFieldInfo> { textField });
+    }
+}
+{% endhighlight %}
+{% endtabs %}
+
+
+
+
+## Update or Replace PDF Form Field Custom Data
+
+Modify an existing field's `CustomData` by using the [`UpdateFormFieldsAsync()`](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.SfPdfViewer.PdfViewerBase.html#Syncfusion_Blazor_SfPdfViewer_PdfViewerBase_UpdateFormFieldsAsync_Syncfusion_Blazor_SfPdfViewer_FormField_) method. Retrieve fields using [`GetFormFieldsAsync()`](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.SfPdfViewer.PdfViewerBase.html#Syncfusion_Blazor_SfPdfViewer_PdfViewerBase_GetFormFieldsAsync) and update the CustomData property.
+
+{% tabs %}
+{% highlight razor %}
+
+@using Syncfusion.Blazor.SfPdfViewer
+@using Syncfusion.Blazor.Buttons
+@using System.Collections.Generic
+
+<SfButton OnClick="@UpdateFirstFieldCustomData">Update First Field Custom Data</SfButton>
+
+<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
+</SfPdfViewer2>
+
+@code {
+    private SfPdfViewer2? viewer;
+    private string DocumentPath = "wwwroot/data/form-designer.pdf";
+
+    private async Task UpdateFirstFieldCustomData()
+    {
+        if (viewer == null) return;
+
+        // Get all form fields
+        var fields = await viewer.GetFormFieldsAsync();
+        if (fields.Count == 0) return;
+
+        // Get the first field
+        var targetField = fields[0];
+
+        // Update custom data
+        var updatedCustomData = new Dictionary<string, object>
+        {
+            { "group", "profile" },
+            { "flags", new[] { "pii", "masked" } },
+            { "updatedAt", DateTime.Now.Ticks }
+        };
+
+        targetField.CustomData = updatedCustomData;
+
+        // Update the field
+        await viewer.UpdateFormFieldsAsync(targetField);
+    }
+}
+{% endhighlight %}
+{% endtabs %}
+
+**Tip:**
+Merge new values into the existing `CustomData` object before calling [`UpdateFormFieldsAsync()`](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.SfPdfViewer.PdfViewerBase.html#Syncfusion_Blazor_SfPdfViewer_PdfViewerBase_UpdateFormFieldsAsync_Syncfusion_Blazor_SfPdfViewer_FormField_) to avoid unintentionally overwriting existing metadata.
+
+## Read Custom Data from PDF Form Fields
+
+Access the `CustomData` property from any form field at any point in the application flow using [`GetFormFieldsAsync()`](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.SfPdfViewer.PdfViewerBase.html#Syncfusion_Blazor_SfPdfViewer_PdfViewerBase_GetFormFieldsAsync), for example:
+- after the document is loaded
+- during save or submit operations
+- while performing validation or conditional routing
+
+{% tabs %}
+{% highlight razor %}
+
+@using Syncfusion.Blazor.SfPdfViewer
+
+<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
+    <PdfViewerEvents DocumentLoaded="@OnDocumentLoaded"></PdfViewerEvents>
+</SfPdfViewer2>
+
+@code {
+    private SfPdfViewer2? viewer;
+    private string DocumentPath = "wwwroot/data/form-designer.pdf";
+
+    private async Task OnDocumentLoaded()
+    {
+        if (viewer == null) return;
+
+        // Get all form fields
+        var fields = await viewer.GetFormFieldsAsync();
+
+        // Access custom data from each field
+        foreach (var field in fields)
+        {
+            Console.WriteLine($"Field: {field.Name}");
+            if (field.CustomData != null)
+            {
+                Console.WriteLine($"Custom Data: {System.Text.Json.JsonSerializer.Serialize(field.CustomData)}");
+            }
+        }
+    }
+}
+{% endhighlight %}
+{% endtabs %}
+
+## Best Practices
+
+- Treat `CustomData` as application metadata, not display data.
+- Use it to drive business rules, validation logic, and workflow decisions.
+- Keep the data minimal and structured for easy processing.
+- When cloning or copying form fields, ensure `CustomData` is copied or updated as required.
+
+[View Sample on GitHub](https://github.com/SyncfusionExamples/blazor-pdf-viewer-examples)
+
+## See Also
+
+- [Programmatic Support for Form Designer](./create-programmatically)
+- [Create form fields programmatically](./create-programmatically)
+- [Update form fields programmatically](./create-programmatically)
+- [Group form fields](./group-form-fields)
+- [Form constraints](./form-constrain)
+- [Read form field values](./read-form-field-values)

Document-Processing/PDF/PDF-Viewer/blazor/form-designer/custom-font.md → Document-Processing/PDF/PDF-Viewer/blazor/forms/custom-font.md

@@ -15,8 +15,9 @@ The Blazor SfPdfViewer supports loading, using, and saving custom fonts for form
 
 To ensure correct rendering and saving of form fields that use custom fonts (especially when fonts are not installed on the host system), set the `FallbackFontCollection` property and load the TTF files the application can access. Add those font family names to the `FontFamilies` (string[]) property so the fonts appear in the Font Family dropdown in the property dialog. Ensure TTF files are available at the configured path (for example, `wwwroot/Data`) and that font licenses permit distribution with the application.
 
-```cshtml
-@page "/"
+{% tabs %}
+{% highlight razor %}
+
 
 <SfPdfViewer2 @ref="pdfViewer" Height="100%" Width="100%" DocumentPath="@DocumentPath" FontFamilies="@FontFamilies">
     <PdfViewerEvents Created="@Created"></PdfViewerEvents>
@@ -39,8 +40,9 @@ To ensure correct rendering and saving of form fields that use custom fonts (esp
         pdfViewer!.FallbackFontCollection.Add("Ojuju", new MemoryStream(System.IO.File.ReadAllBytes("wwwroot/Data/Ojuju-Regular.ttf")));
     }
 }
-```
-![Custom Font Support for Form Fields in Blazor SfPdfViewer](../form-designer/form-designer-images/custom_font_support_for_form_fields.png)
+{% endhighlight %}
+{% endtabs %}
+![Custom Font Support for Form Fields in Blazor SfPdfViewer](../forms/form-designer-images/custom_font_support_for_form_fields.png)
 
 [View sample in GitHub](https://github.com/SyncfusionExamples/blazor-pdf-viewer-examples/tree/master/Common/Custom%20Font%20Support%20For%20FormFields).
 
@@ -54,8 +56,9 @@ The Blazor SfPdfViewer allows loading, editing, and saving custom fonts for sign
 
 To ensure correct rendering and saving of signatures that use custom fonts (especially when those fonts are not installed on the host system), set the `FallbackFontCollection` property and load the TTF files the application can access. Add the font family names to the `SignatureFonts` (string[]) property so they appear in the signature dialog. Verify that the font files are reachable at the configured path (for example, `wwwroot/Data`) and that licensing allows distribution.
 
-```cshtml
-@page "/"
+{% tabs %}
+{% highlight razor %}
+
 
 <SfPdfViewer2 @ref="Viewer" DocumentPath="@DocumentPath" Height="100%" Width="100%">
     <PdfViewerEvents Created="@Created"></PdfViewerEvents>
@@ -80,16 +83,18 @@ To ensure correct rendering and saving of signatures that use custom fonts (espe
         pdfViewer!.FallbackFontCollection.Add("Inspiration", new MemoryStream(System.IO.File.ReadAllBytes("wwwroot/Data/Inspiration-Regular.ttf")));
     }
 }
-```
-![Custom Font Support for Signature Field in Blazor SfPdfViewer](../form-designer/form-designer-images/custom_font_support_signature_fields.png)
+{% endhighlight %}
+{% endtabs %}
+![Custom Font Support for Signature Field in Blazor SfPdfViewer](../forms/form-designer-images/custom_font_support_signature_fields.png)
 
 [View sample in GitHub](https://github.com/SyncfusionExamples/blazor-pdf-viewer-examples/tree/master/Common/Custom%20Font%20Support%20For%20Signature%20Field).
 
 When using Google Fonts or other externally hosted fonts with the PDF Viewer, load the fonts in the application to ensure consistent rendering. This is required because FreeText annotations render directly onto the canvas and need the fonts available in the hosting environment.
 
 The following example illustrates how to load custom fonts in FreeText annotations using fonts from Google Fonts or other external sources.
 
-```cshtml
+{% tabs %}
+{% highlight razor %}
 <script>
     window.addEventListener('DOMContentLoaded', () => {
         var fontFamily = ["Allura, Tangerine, Sacramento, Inspiration"];
@@ -103,7 +108,8 @@ The following example illustrates how to load custom fonts in FreeText annotatio
         }
     });
 </script>
-```
+{% endhighlight %}
+{% endtabs %}
 
 N> If external fonts are not loaded in the environment, importing and rendering FreeText annotations that reference those fonts may show minor differences. This typically occurs only with fonts referenced from web-based sources.