Customize Annotation Serialization

Annotation classes understand how to serialize their properties into XFDF according to the XFDF specification. This can be customized in WebViewer to serialize custom properties and read those properties back in. This is especially useful when storing the XFDF externally, as custom attributes/elements outside the specification will be ignored by WebViewer when used to save to the document.

To change the serialization behavior for an annotation class, you can use the setCustomSerializeHandler API.

Annotations.setCustomSerializeHandler(Annotations.RectangleAnnotation, function(element, pageMatrix, options) {
  const annot = options.annotation;
  options.originalSerialize(element, pageMatrix)
  if (annot.Width > 100) {
    element.setAttribute('myAttr', annot.myProperty);
  }
  return element;
});

<square page="0" rect="170.090,587.300,337.210,693.110" color="#E44234" flags="print" name="fa7f93a0-4049-e95d-3179-d0820470ade5" title="Guest" subject="Rectangle" date="D:20221016023516-07'00'" creationdate="D:20221016023516-07'00'" myAttr="1"/>

To change an annotation class to read custom attributes/elements in the XFDF, you can use the setCustomDeserializeHandler API to change that behavior.

Annotations.setCustomDeserializeHandler(Annotations.RectangleAnnotation, function(element, pageMatrix, options) {
  const annot = options.annotation;
  options.originalDeserialize(element, pageMatrix)
  if (annot.Width > 100) {
    annot.myProperty = element.getAttribute('myAttr');
  }
});

Both APIs, setCustomSerializeHandler and setCustomDeserializeHandler, require new, custom function handlers to be provided. They are similar to the serialize and deserialize functions on annotations except with an additional options parameter.

// Serialize handler signature
function(element, pageMatrix, options) {
  ...
  return element;
}

// Deserialize handler signature
function(element, pageMatrix, options) {
  ...
}

The options parameter contains the annotation being serialized/deserialized. It also includes the original serialize and deserialize functions, originalSerialize and originalDeserialize, so that you can perform regular operations and then building on top of existing functionality.

When customizing annotation serialization and/or deserialization, the original respective function is preserved. Calling an API to change the behavior again will not overwrite the original, preserved function. This allows the original behavior of the annotation to be restored when you want to restore the original behavior.

// Restore serialization behavior
Annotations.restoreSerialize(Annotations.RectangleAnnotation);

// Restore deserialization behavior
Annotations.restoreDeserialize(Annotations.RectangleAnnotation);

Change how annotations render using your custom properties.