Saving Mechanism

PSPDFKit for Web allows modification of multiple domain objects. These objects include annotations, bookmarks, comments, form fields, and form field values.

Server-Backed Deployments

By default, local changes are always synced to the server. This means you can always use the backend API to interact with these objects. This auto-save behavior can be configured by the Configuration#autoSaveMode configuration option.

Before the change is sent to the server, we assign a stable ID (ULID). This ID is also used by the server, and it allows you to track updates that happen before the server responds. If you would like to ensure a local change has been saved by the server, you can use ensure*Saved methods (e.g. Instance.ensureAnnotationSaved for annotations):

Copy
1
2
3
4
5
6
7
PSPDFKit.load(configuration).then(async instance => {
  const createdAnnotation = await instance.createAnnotation(newAnnotation);
  const savedAnnotation = await instance.ensureAnnotationSaved(
    createdAnnotation
  );
  console.log(savedAnnotation.id); // => '01BS964AM5Z01J9MKBK64F22BQ'
});
Copy
1
2
3
4
5
6
7
8
PSPDFKit.load(configuration).then(function(instance) {
  instance
    .createAnnotation(newAnnotation)
    .then(instance.ensureAnnotationSaved)
    .then(function(savedAnnotation) {
      console.log(savedAnnotation.id); // => '01BS964AM5Z01J9MKBK64F22BQ'
    });
});

Standalone Deployments

In a standalone PSPDFKit for Web installation, changes will be stored in memory until they are exported. The same persisting steps are traversed, which means we still differentiate between saved and unsaved changes, and exported Instant JSON will only contain changes that were saved. Please see the guide on importing and exporting for more information.

Configuration#autoSaveMode

If nothing else is configured, PSPDFKit for Web will have auto-save enabled. This means that local changes are automatically synced. You can use Configuration#autoSaveMode to configure exactly when saving occurs.

Save Mode Use Case
default If nothing is configured, PSPDFKit.AutoSaveMode.INTELLIGENT or PSPDFKit.AutoSaveMode.IMMEDIATE will be used, based on the presence of Instant.
PSPDFKit.AutoSaveMode.IMMEDIATE Changes are saved whenever something changes, as long as they are in a valid state. This is useful for real-time updates but increases server load.
PSPDFKit.AutoSaveMode.INTELLIGENT Changes are saved whenever we detect a complete operation. This merges multiple operations into one server request and saves, for example, on deselect.
PSPDFKit.AutoSaveMode.DISABLED Changes are not saved by default. You can use PSPDFKit.Instance#save to trigger a save manually whenever you want.
1
PSPDFKit.load({ autoSaveMode: PSPDFKit.AutoSaveMode.INTELLIGENT, ... });
1
PSPDFKit.load({ autoSaveMode: PSPDFKit.AutoSaveMode.INTELLIGENT, ... });

Reacting to Unsaved Changes

You can check to see if there are any unsaved changes by calling Instance.hasUnsavedChanges.

If you wish to react to save state changes, you can register listeners for the document.saveStateChange event. The emitted event contains the property hasUnsavedChanges with the current value of the Instance.hasUnsavedChanges method:

1
2
3
instance.addEventListener("document.saveStateChange", event => {
  console.log(`Save state changed: ${event.hasUnsavedChanges}`);
});
Copy
1
2
3
instance.addEventListener("document.saveStateChange", function(event) {
  console.log("Save state changed: ".concat(event.hasUnsavedChanges));
});