2021.6 Migration Guide

With PSPDFKit for Web 2021.6, we removed a handful of APIs that have been deprecated since 2020.5.0. This update:

  • Removes Instance#createAnnotation, Instance#createBookmark, and Instance#createFormField in favor of Instance#create.

  • Removes Instance#saveAnnotations, Instance#saveBookmarks, Instance#saveComments, Instance#saveFormFields, and Instance#saveFormFieldValues in favor of save.

  • Removes Instance#updateAnnotation, Instance#updateBookmark, and Instance#updateFormField in favor of Instance#update.

  • Removes Instance#deleteAnnotations, Instance#deletebookmark, and Instance#deleteFormField in favor of Instance#delete.

  • Removes Instance#ensureAnnotationSaved, Instance#ensureBookmarkSaved, and Instance#ensureFormFieldSaved in favor of Instance#ensureChangesSaved.

  • Removes Instance#hasUnsavedAnnotations, Instance#hasUnsavedBookmarks, Instance#hasUnsavedComments, Instance#hasUnsavedFormFieldValues, and Instance#hasUnsavedFormFields in favor of Instance#hasUnsavedChanges.

Please note that some of these deprecated APIs returned a single result, but the new API will always return an array. Make sure any of your code that relied on this behavior accesses the first element in the array.

Below is an example of how to use the new Instance#update API with a single annotation:

instance.update([annotation]).then((annotations) => {
  const savedAnnotation = annotations[0];
});

If you used to call Instance#createAnnotation to create a widget, and then attached it to a form using Instance#createFormField, you’ll now need to create the form field first.

You’ll also need to generate and set the widget’s ID using PSPDFKit#generateInstantId so that you can reference the widget from the form field before it’s added to the document.

Here’s an example of how you can do this using the new Instance.html#create API:

const annotation = new PSPDFKit.Annotations.WidgetAnnotation({
  id: PSPDFKit.generateInstantId(),
  pageIndex: 0,
  formFieldName: "name",
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 10,
    top: 20,
    width: 60,
    height: 40
  })
});

const form = new PSPDFKit.FormFields.TextFormField({
  name: "name",
  annotationIds: PSPDFKit.Immutable.List([annotation.id]),
  label: "A label"
});

instance.create([annotation, form]);

By default, this makes signatures respect their aspect ratio when being resized by their corner handles. To opt out of this and go back to the old behavior, you can use the new onAnnotationResizeStart callback option:

PSPDFKit.load({
  onAnnotationResizeStart: (event) => {
    if (event.annotation.isSignature && !event.isShiftPressed) {
      return {
        maintainAspectRatio: false
      };
    }

    return undefined;
  }
});

For a full list of changes, please check out the changelog.

Migrate PSPDFKit Server

For more information, please take a look at the PSPDFKit Server 2021.6 Migration Guide.