2020.1 Migration Guide

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

Notable Changes

  • PSPDFKit.I18n#localeData has been deprecated because we have adopted React Intl version 3.x.x changes. This version has dropped support for providing custom localization data in favor of using the standard Intl Web API for pluralization and other localization rules, which means that you no longer need to provide these rules if you want to support additional locales.

    This also means you will no longer be able to provide localization rules for locales not supported by the browser, but considering the large number of locales supported by modern browsers, this should not pose a problem.

    Browsers that do not support the Intl API (like IE11 and Safari < 13) will include a polyfill for Intl.PluralRules, as well as an individual polyfill for each of the supported locales. If you want to continue supporting these browsers when providing additional locales, you can do so by including the corresponding locale polyfill:

    // Add the locale to the locales list (Wolof language).
PSPDFKit.I18n.locales.push("wo");
// Is this browser using the `Intl.PluralRules` polyfill?
if (Intl.PluralRules.polyfilled) {
  // Then include the plural rules locale data polyfill.
  await import("@formatjs/intl-pluralrules/dist/locale-data/wo");
}
// Add Wolof translations for messages.
PSPDFKit.I18n.messages["wo"] = wolofMessages;
// Change current language to Wolof
instance.setLocale("wo");
Warning

Internet Explorer 11 is no longer supported in our Web SDK as of version 2022.5. Edge 18 is no longer supported in our Web SDK as of version 2023.2.

Add the locale data polyfills to your local node_modules folder by installing them using either npm or yarn:

yarn add @formatjs/intl-pluralrules
npm i @formatjs/intl-pluralrules

A deprecation warning will be shown each time cloudyBorderInsetRect is used. In the next major version, cloudyBorderInsetRect will finally be removed.

If you use the cloudyBorderInsetRect property in your code, you will have to update it so it does not break once the property is removed in the next major version.

Also, when you create a new rectangle or ellipse annotation with the cloudyBorderIntensity property set and there is no cloudyBorderInset or cloudyBorderInsetRect defined, a default cloudyBorderInset will be applied with values following this formula:

const inset = 4.5 * cloudyBorderIntensity + strokeWidth / 2;

This default cloudyBorderInset value ensures that the cloudy border is not cropped and that it’s just wide enough for the cloudy border to fit in it. If you wish to set a cloudyBorderInset with 0 values, do it explicitly instead, using the following:

const inset = new PSPDFKit.Geometry.Inset({
  left: 0,
  top: 0,
  right: 0,
  bottom: 0
});

Or, to make it less verbose, use the utility static class method PSPDFKit.Geometry.Inset#fromValue:

const inset = PSPDFKit.Geometry.Inset.fromValue(0);

  • event.formField has been removed from the documentation of PSPDFKit.AnnotationsFocusEvent and PSPDFKit.AnnotationsBlurEvent. It has never been part of the event payload, and this change only affects the aforementioned documentation, so it cannot break your implementation in any way. However, if you were relying on this, you may need to review your event listener logic in case the absence of this event.formField object may have been affecting its behavior. If you think you still need this object, you can easily get the formField associated with a particular annotation by using the following code:

    instance.addEventListener("annotations.blur", event => {
  instance.getFormFields().then(formFields => {
    const formField = formFields.find(
      formField => formField.name === event.annotation.formFieldName
    );
    console.log(formField);
  });
});

    If you are using event.formField, here is the change you need to make:

    Before

    instance.addEventListener("annotations.focus", event => {
  console.log(event.formField);
});

instance.addEventListener("annotations.blur", event => {
  console.log(event.formField);
});

    After

    instance.addEventListener("annotations.focus", event => {
  instance.getFormFields().then(formFields => {
    const formField = formFields.find(
      formField => formField.name === event.annotation.formFieldName
    );
    console.log(formField);
  });
});

instance.addEventListener("annotations.blur", event => {
  instance.getFormFields().then(formFields => {
    const formField = formFields.find(
      formField => formField.name === event.annotation.formFieldName
    );
    console.log(formField);
  });
});

  • When the Digital Signatures component is included in the license, PSPDFKit.Instance#exportPDF will export signed documents as incrementally saved by default so as to prevent modifying signed data, which would invalidate the document’s digital signatures. However, setting the incremental flag to false will override this behavior.

    If the Digital Signatures component is not included in the license, the former behavior will be followed and signed documents will be exported as fully saved by default. In order to prevent signed data corruption in this case, the incremental flag should be explicitly set:

    instance.exportPDF({ incremental: true });

  • Previously, the object returned by PSPDFKit.ViewState#viewportPadding had the vertical value under the horizontal property and vice versa. This has been now fixed. If you were relying on the previous returned value, you will need to adjust your implementation accordingly.

  • The order in which annotations are rendered has been modified. In previous versions, annotations of the same type would be rendered in the same layer, in the following order from back to front:

    • Text markup

    • Link

    • Text

    • Widget

    • Stamp

    • Image

    • Ink

    • Shape

    • Note

    Beginning with the current release, annotations will be rendered in the same order they are in the document, regardless of their type. New annotations will always be rendered on top of the last one that has been added.

    If your implementation relies on the former annotation rendering order, you may need to rearrange the order in which annotations are created so as to continue obtaining the same result.

    You would need to first create the annotations that you want to be rendered in the background, followed by the ones that you want to be rendered in the foreground. For example: First create text annotations, then stamp annotations, then ink and shape annotations, in that order. This way, your annotations will keep rendering in the order they had with the former behavior.

    If your annotations never overlap, this change will probably not affect your implementation at all.

  • The note annotation icon in the main toolbar has been updated.

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

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