Section:

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.

The APIs in this guide are only available in WebViewer 7.1+.

Customizing serialization

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

JavaScript (v7.0+)

1Annotations.setCustomSerializeHandler(Annotations.RectangleAnnotation, function(element, pageMatrix, options) {
2  const annot = options.annotation;
3  options.originalSerialize(element, pageMatrix)
4  if (annot.Width > 100) {
5    element.setAttribute('myAttr', annot.myProperty);
6  }
7  return element;
8});

Related Links

sh

1<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"/>

Customizing deserialization

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

JavaScript (v7.0+)

1Annotations.setCustomDeserializeHandler(Annotations.RectangleAnnotation, function(element, pageMatrix, options) {
2  const annot = options.annotation;
3  options.originalDeserialize(element, pageMatrix)
4  if (annot.Width > 100) {
5    annot.myProperty = element.getAttribute('myAttr');
6  }
7});

Related Links

Handler function

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.

JavaScript (v7.0+)

1// Serialize handler signature
2function(element, pageMatrix, options) {
3  ...
4  return element;
5}
6
7// Deserialize handler signature
8function(element, pageMatrix, options) {
9  ...
10}

Related Links

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.

Restoring original behaviors

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.

JavaScript (v7.0+)

1// Restore serialization behavior
2Annotations.restoreSerialize(Annotations.RectangleAnnotation);
3
4// Restore deserialization behavior
5Annotations.restoreDeserialize(Annotations.RectangleAnnotation);

Related Links

Next steps

Change how annotations render using your custom properties.

Did you find this helpful?

Trial setup questions?

Ask experts on Discord

Need other help?

Contact Support

Pricing or product questions?

Contact Sales