# # PDF Form API Migration Guide

This section is designed to assist developers in migrating from older versions (10.0.0 or earlier) of Foxit PDF SDK for Web to the latest version, with a primary focus on the migration of the form module. The migration process involves changes to the API, functional differences, and compatibility issues. Please read and follow this guide carefully to ensure a smooth migration process.

## # Migration Steps

1. Evaluate Current Status

   - Identify the Current SDK Version: Confirm that the SDK version currently in use is 10.0.0 or earlier.
   - Review Existing Code: Inspect all code related to PDF form operations to ensure a clear understanding of the implemented features and dependencies.

2. Install the New Version of SDK

   Use the following command to install the latest version of the SDK:

       npm i --save @foxitsoftware/foxit-pdf-sdk-for-web@latest

3. API Mapping

   - Create Form Fields:

     - Previous Version:

           const doc = pdfViewer.getCurrentPDFDoc();
           await doc.loadPDFForm();
           const form = doc.getPDFForm();

           const pageIndex = 0;
           const fieldName = "Push Button";
           const fieldType = PDF.form.constant.Field_Type.PushButton;
           const rect = {
               left: 0,
               right: 100,
               top: 100,
               bottom: 0
           };
           await form.addControl(
               pageIndex,
               fieldName,
               fieldType,
               rect
           );

     - New Version:

           const doc = pdfViewer.getCurrentPDFDoc();
           const form = doc.getPDFForm();
           const pdfRect = {
               left: 0,
               right: 100,
               top: 0,
               bottom: 100
           };
           await form.createPushButton({
               pdfRect,
               pageIndex: 0,
               rotate: 0,
           });

           await form.createTextField({
               pdfRect,
               pageIndex: 0,
               rotate: 0,
           });

           await form.createImageButton({
               pdfRect,
               pageIndex: 0,
               rotate: 0,
               imagePath: 'https://example.com/image.png'
           });
           await form.createDatetime({
               pdfRect,
               pageIndex: 0,
               rotate: 0,
               timeformat: 'yyyy-mm-DD'
           });
           await form.createCheckbox({
               pdfRect,
               pageIndex: 0,
               rotate: 0
           });
           await form.createRadioButton({
               pdfRect,
               pageIndex: 0,
               rotate: 0
           });
           await form.createComboBox({
               pdfRect,
               pageIndex: 0,
               rotate: 0
           });
           await form.createListBox({
               pdfRect,
               pageIndex: 0,
               rotate: 0
           });
           await form.createSignature({
               pdfRect,
               pageIndex: 0,
               rotate: 0
           });

   - Delete Form Fields:

     - Previous Version:

           const doc = pdfViewer.getCurrentPDFDoc();
           const form = doc.getPDFForm();
           // Delete the form field and all its associated form widgets.
           await form.removeField("Push Button0");

     - New Version:

           const doc = pdfViewer.getCurrentPDFDoc();
           const page = await doc.getPageByIndex(0);
           // Delete the specified form field. If the field has no other associated form fields, the field itself will be automatically deleted.
           const widgetObjNumber = 881;
           await page.removeAnnotByObjectNumber(widgetObjNumber);

   - Get Form Fields:

     - Previous Version:

           const doc = pdfViewer.getCurrentPDFDoc();
           const form = doc.getPDFForm();
           // Get form field by index
           const field = form.getFieldByIndex(0);
           // Get a list of form fields by name prefix
           const fields = form.getField("Push Button0");

     - New Version:

           const doc = pdfViewer.getCurrentPDFDoc();
           const form = doc.getPDFForm();
           // Get a form field by exact name. If the field does not exist, an exception will be thrown
           const field = await form.getField("Push Button0");
           // Get all form fields
           const allFields = await form.getFields();
           // Get a list of form fields by name prefix
           const fields = await form.getFieldsByNamePrefix("Push Button");
           // Get a form field by page index and coordinates
           const fieldAtPosition = await form.getFieldAtPosition(0, { x: 0, y: 0 });

4. Form Widget and Field Property Reading and Modification

   In the new version, methods for reading properties have been changed from synchronous to asynchronous.

   - Previous Version:

         const doc = pdfViewer.getCurrentPDFDoc();
         const form = doc.getPDFForm();
         const field = form.getFieldByIndex(0);

         const mappingName = field.getMappingName();
         const alternateName = field.getAlternateName();
         const value = field.getValue();
         const alignment = field.getAlignment();
         const options = field.getOptions();
         const maxLength = field.getMaxLength();
         const type = field.getType();

   - New Version:

         const doc = pdfViewer.getCurrentPDFDoc();
         const form = doc.getPDFForm();
         const field = form.getFieldByIndex(0);

         const mappingName = await field.getMappingName();
         const alternateName = await field.getAlternateName();
         const value = await field.getValue();
         const alignment = await field.getAlignment();
         const options = await field.getOptions();
         const maxLength = await field.getMaxLength();
         const type = await field.getType();

         // New APIs
         await field.getDefaultValue();
         await field.isCheckedByDefault();
         await field.getWidgetsCount();
         await field.getWidget(0);
         await field.isRequired();
         await field.isReadonly();
         await field.getDateTimeFormat();
         await field.getValidateActionInfo();
         await field.getCalculateActionInfo();
         const { type, isImage, isDateOrTime } = await field.getExtType();

5. Event Change

   - ViewerEvents.focusOnControl

     - Previous Version:

           pdfViewer.eventEmitter.on(ViewerEvents.focusOnControl control => {
               // The type of `control` here is PDFControl
           })

     - New Version:

           // The new version has modified the event parameter type
           pdfViewer.eventEmitter.on(ViewerEvents.focusOnControl, widget  => {
               // Here, the type of widget is Widget
           })

6. Action API Changes

   Please refer to the PDF Action API Migration Guide.

7. Signature Workflow API Changes

   Please refer to the Signature Workflow API Migration Guide.

8. UI Implementation Changes

   Changes involve the following UI components:

   - Context menu for form widget
   - Form widget property dialog
   - UI components triggered by actions (e.g., alert pop-ups, confirm pop-ups, dropdown menus, etc.)

   In the new version, these components all support customization. You can refer to the customization documentation for each component:

   - Customize Context Menu for Form Widgets
   - Customize Date-Time Picker for PDF Forms
   - Customize Form Widget Property Dialog
   - Customize UI Components Triggered by Action
   - Customize Signature Widget UI