# 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

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.
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
```

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 });

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();

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
})

Action API Changes

Please refer to the PDF Action API Migration Guide.
Signature Workflow API Changes

Please refer to the Signature Workflow API Migration Guide.
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:

← Integration of ServiceWorker PDF Action API Migration Guide →