2020.5 Migration Guide

PSPDFKit for Web 2020.5 comes with a few improvements that might require an ad hoc migration.

Notable Changes

Unified CRUD API

• This release introduces a unified API for creating, updating, deleting, and saving objects:

  • Instance#create

  • Instance#update

  • Instance#delete

  • Instance#ensureChangesSaved

  These methods support a single change or an array of changes allowing batched updates. Each of them resolves with an array of resolved changes (created/updated/deleted/saved). Operations are performed even if some batched changes can’t be executed. In this case, the methods reject with an array containing the resolved changes or errors for failed changes.

  Supported change types are: annotations, bookmarks, form fields, form field values, and comments.

• Most existing Instance methods for performing modifications and saving objects have been deprecated:

  Deprecated Method	Replacement
  createAnnotation/FormField/Bookmark	Instance#create
  updateAnnotation/FormField/Bookmark	Instance#update
  deleteAnnotation/FormField/Bookmark	Instance#delete
  hasUnsavedAnnotations/FormFields/FormFieldValues/Bookmarks/Comments	Instance#hasUnsavedChanges
  ensureAnnotation/FormField/BookmarkSaved	Instance#ensureChangesSaved
  saveAnnotations/FormFields/FormFieldValues/Bookmarks/Comments	Instance#save

  To migrate your existing use of CRUD-related methods, update the method name. If you’re using the result value, make sure to update this too since the new unified CRUD methods return an array of changes instead of a single change. For example:

  // Deprecated code:
  const createdAnnotation = await instance.createAnnotation(newAnnotation);
  console.log(`Created annotation with ID ${createdAnnotation.id}`);
  
  // Should be replaced with:
  const [createdAnnotation] = await instance.create(newAnnotation);
  console.log(`Created annotation with ID ${createdAnnotation.id}`);

• Instance#save and Instance#ensureChangesSaved now report errors for some changes when a save fails.

• In contrast to the now-deprecated Instance#createAnnotation, Instance#create fails when creating a widget annotation without its associated form field. Make sure to create both in the same create method call:

  const widget = new PSPDFKit.Annotations.WidgetAnnotation({
    id: PSPDFKit.generateInstantId(),
    pageIndex: 0,
    formFieldName: "MyFormField",
    boundingBox: new PSPDFKit.Geometry.Rect({
      left: 100,
      top: 75,
      width: 200,
      height: 80
    })
  });
  const formField = new PSPDFKit.FormFields.TextFormField({
    name: "MyFormField",
    annotationIds: new PSPDFKit.Immutable.List([widget.id]),
    value: "Text shown in the form field"
  });
  
  instance.create([widget, formField]);

ℹ️ Note: A created form field requires the widget annotation ID before the annotation is created. This means you must assign a unique UID for your widget annotation when using this new API. You can generate a proper UID via the newly introduced PSPDFKit#generateInstantId.

If you use PSPDFKit Server, please make sure you read the 2020.5 Server Migration Guide.

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