Foxit Developer

PDF Form API Migration Guide ​

This guide helps you migrate from Foxit PDF SDK for Web 10.0.0 or earlier to the latest release, with a focus on the form module. The migration involves API changes, behavior differences, and compatibility considerations. Follow this guide carefully for a smooth upgrade.

Migration steps ​

  1. Assess your current state

    • Identify your SDK version: Confirm you are on 10.0.0 or earlier.
    • Review existing code: Audit all PDF form logic and dependencies.

  2. Install the new SDK

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

  3. API mapping

    • Create form fields:

      • Previous version:

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

      • Current version:

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

    • Remove form fields:

      • Previous version:

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

      • Current version:

        javascript
        const doc = pdfViewer.getCurrentPDFDoc();
const page = await doc.getPageByIndex(0);
// Remove a widget; if it was the last widget on the field, the field is removed too
const widgetObjNumber = 881;
await page.removeAnnotByObjectNumber(widgetObjNumber);

    • Get form fields:

      • Previous version:

        javascript
        const doc = pdfViewer.getCurrentPDFDoc();
const form = doc.getPDFForm();
// By index
const field = form.getFieldByIndex(0);
/// By name prefix
const fields = form.getField("Push Button0");

      • Current version:

        javascript
        const doc = pdfViewer.getCurrentPDFDoc();
const form = doc.getPDFForm();
// Exact name; throws if missing
const field = await form.getField("Push Button0");
// All fields
const allFields = await form.getFields();
// By name prefix
const fields = await form.getFieldsByNamePrefix("Push Button");
// By page index and position
const fieldAtPosition = await form.getFieldAtPosition(0, { x: 0, y: 0 });

  4. Reading and updating field properties

    Property accessors are async in the new version.

    • Previous version

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

    • Current version

      javascript
      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 changes

    • ViewerEvents.focusOnControl

      • Previous version

        javascript
        pdfViewer.eventEmitter.on(ViewerEvents.focusOnControl control => {
    // control is PDFControl
})

      • Current version

        javascript
        // Event argument type changed
pdfViewer.eventEmitter.on(ViewerEvents.focusOnControl, widget  => {
    // widget is Widget
})

  6. Action API changes

    See PDF Action API Migration Guide.

  7. Signature workflow changes

    See PDF Signature Workflow API Migration Guide.

  8. UI changes

    These UI pieces changed and can be customized in the new version:

    • Form widget context menu
    • Form widget properties dialog
    • Action-triggered UI (alert, confirm, popup menu, and so on)

    See: