Public APIs for Widget and Annotation Properties

Technical Support
,
1

Hello Apryse Support Team,

We hope this message finds you well. We’re reaching out for assistance with accessing certain properties in WebViewer and would greatly appreciate your guidance.

Environment

  • WebViewer Version: 11.7.1
  • Framework: Angular
  • Issue Type: API Request

Problem Description

We are currently accessing internal/private properties of WebViewer objects directly, which unfortunately causes our code to break between releases as these internal property names change. We understand this is not the recommended approach and would be grateful if you could help us identify the proper public API methods to access these properties reliably.

Required Public APIs

We would be extremely grateful if you could point us to the appropriate public getter/setter methods for the following properties:

1. Field Manager - Array Property (Currently Jg)

const fields = fieldManager.getFields() as Core.Annotations.Forms.Field[];
fields.forEach((field) => {
    let field2: any = field;
    field2.Jg = []; // We need to empty this array
});

What we’re looking for: A public setter method to clear/set this array property, if available.

2. Annotation ReadOnly Property (Currently Jsa.ReadOnly)

const annotation: Core.Annotations.Annotation = annotations[i];
const annotation2: any = annotation;
if (annotation2?.ReadOnly == true || annotation2.Jsa.ReadOnly) {
    // logic here
}

What we’re looking for: A public getter method to access the ReadOnly property from the Jsa object.

3. Widget Annotation Initial Value (Currently ie)

if (annotation instanceof this.instance!.Core.Annotations.WidgetAnnotation) {
    const annotation2: any = annotation;
    data = {
        initialValue: annotation2.ie,
        // other properties
    };
}

What we’re looking for: A public getter method to access the initial value property.

4. Annotation ID Properties (Currently yCa and Uk)

let annotations = this.instance!.Core.annotationManager.getAnnotationsList();
for (let i = 0; i < annotations.length; i++) {
    const annotation = annotations[i];
    const annotation2: any = annotation;
    if (annotationId && (annotation2.yCa == annotationId || annotation2.Uk == annotationId)) {
        return annotation;
    }
}

What we’re looking for: Public getter methods for these ID properties.

5. Widget ID Properties (Currently Nl and Bn)

if (widgetId && (annotation2.Nl == widgetId || annotation2.Bn == widgetId)) {
    return annotation;
}

What we’re looking for: Public getter methods for these widget ID properties.

6. Annotation Page Number (Currently jO)

getAnnotationPageNumber(annotation: Core.Annotations.Annotation): number {
    const annot2: any = annotation;
    return +annot2.jO;
}

What we’re looking for: A public getter method to get the page number of an annotation.

Additional Question

We were wondering if there might be a comprehensive documentation page that maps all object attributes to their corresponding public API methods? This would be incredibly helpful for us to avoid accessing internal properties in the future and ensure our code remains stable across WebViewer updates.

What Would Help Us

  1. Public API methods/properties for all the above use cases
  2. Documentation reference for object attribute mapping (if available)
  3. Any guidance on best practices for these scenarios

Thank you so much for your support!

Best regards,
William

2

Hello, I’m AiRon, an automated tech support bot :robot:
While you wait for one of our customer support representatives, I can help you with your question.


It seems you’re looking for reliable public API methods to access and manipulate certain properties in WebViewer without relying on internal properties that may change between releases. This is a great approach to ensure long-term stability in your code.

Some things you can try:

  • For clearing or setting fields in the Field Manager, utilize the fieldManager.getField(fieldName) to retrieve a specific field and then manipulate its properties through the public API methods for form fields.

  • To check if an annotation is read-only, use the annotation.isReadOnly() method.

  • For accessing the initial value of a Widget Annotation, use the annotation.getCustomData(‘key’) method, assuming the initial value is stored as custom data.

  • To get the ID of an annotation, use annotation.getId(), which provides a stable identifier for each annotation.

  • For widget IDs, similar to annotations, use widget.getId() to retrieve the identifier.

  • To get the page number of an annotation, use annotation.getPageNumber().



Here are some resources that might help you:

  • Annotations and Tools Guide: This guide offers detailed information on annotation manipulation, including how to access and modify annotation properties.

  • Forms and Field Manager Guide: Learn how to work with form fields and access their properties using the public API.

  • Edit Annotation Style Properties: Understand how to style annotations programmatically using the public API.

  • Open Documents by URL: While not directly related, this guide provides insights into the loading and handling of documents, which might assist in understanding document context.

  • WebViewer Guides: A collection of guides covering various aspects of WebViewer, including best practices and advanced configurations.



Hopefully, this helps you solve your problem while you wait for a human to get back to you.

3

Hi there,

We strongly recommend you not to use the minified variables as they will be updated on every version update, and thus do not have a page that maps all object attributes to the corresponding public APIs.

For the list of equivalent properties you are looking for, you should be able to access all of it via the regular properties/methods based on the corresponding API documentation page.

1 - Array property for the fields
Based on our API documentation, we have 4 properties that correlate to an array:

  • children
  • widgets
  • action
  • options

2 Annotation ReadOnly property
Please use the annotation’s ReadOnly property:

3. Widget Annotation Initial Value (Currently ie)
I think you are looking for the defaultValue of the WidgetAnnotation property:

4. Annotation ID Properties (Currently yCa and Uk)
You can use the ID property of the annotation directly:

5. Widget ID Properties (Currently Nl and Bn)
Please use the ID property of the widget:

6. Annotation Page Number (Currently jO)
You can use the getPageNumber API of the annotation:

Best regards,
Kevin

1 Like
4

Hi Kevin,

Thank you for your response and the documentation links.

I’m testing the suggested solutions, but I’ve encountered a couple of issues that I hope you can help clarify:

Issue 1: ReadOnly Property Discrepancy

The annotation.ReadOnly property returns a different value compared to the internal Jsa.ReadOnly property that we actually need:

const annotation: Core.Annotations.Annotation = annotations[i];
console.log(annotation?.ReadOnly); // output: false
const annotation2: any = annotation;
console.log(annotation2.Jsa); // output: {ReadOnly: true}

As you can see, annotation.ReadOnly returns false while the internal Jsa.ReadOnly returns true. We specifically need the value from Jsa.ReadOnly for our logic. Is there a public API to access this specific ReadOnly property from the Jsa object?

Issue 2: Setting Field Array Properties

Regarding the field array properties (children, widgets, action, options), I can see these are read-only properties without public setters. I tried using the field.set() method as follows:

field.set({ widgets: [field.widgets![0]] });

But this doesn’t seem to work. Could you please provide guidance on how to properly modify these array properties, particularly the widgets array? We need to be able to clear or modify the widgets array for our field management logic.

Best regards,
William

1 Like
5

Hi there,

Issue 1: ReadOnly Property Discrepancy
Could you clarify your use-case for requiring this specific property on the annotation?
I am unable to see the annotation’s ‘Jsa’ property on 11.7.1 build but it may be the widget flag option for widget annotations:

Issue 2: Setting Field Array Properties
To modify the fields, please follow this guide:

best regards,
Kevin

1 Like
6

Hi Kevin,

Thank you for the responses. Let me clarify both issues:

Issue 1: ReadOnly Property Discrepancy

The annotations in my document were set as read-only on the backend side using this C# code:

using pdftron.PDF.PDFDoc doc = new(new MemoryStream(pdf));
pdftron.PDF.Field foundField = doc.GetField(field.AcroFieldTag);
foundField.SetFlag(Field.Flag.e_read_only, true);

When I access these annotations on the frontend with WebViewer 11.7.1:

  • annotation.ReadOnly returns false
  • annotation2.Jsa.ReadOnly returns true (which is the correct value)

The Jsa property appears to contain the actual field flags set from the backend. How can I access this backend-set read-only flag through the public API?

Issue 2: Setting Field Array Properties

The example you provided shows how to modify widget properties, but I need to completely remove all widgets from a field (empty the widgets array), not modify their properties.

In my use case, after reassigning widgets to new separate fields with widget.setField(newField), I need to completely disconnect them from the original field by clearing its widgets array.

How can I achieve this with the public API? Is there a method like field.clearWidgets() or field.removeAllWidgets()?

Currently I’m using: field2.Jg = [] (internal property) but I need the public API equivalent.

Best regards

1 Like
7

Hi there,

#1
It looks like the backend code directly sets the flag with the setFlag API. You should be able to access the same flag via the getFieldFlag API in the client side WebViewer.
I.e.

widgetAnnotation.getFieldFlags() 
// returns an object containing flag properties. If it has a ReadOnly flag set, it should show up like this: 
// {Required: true, ReadOnly: true}ReadOnly: trueRequired: true[[Prototype]]: Object

#2 We don’t have an API that clears all the associated widgets from a field, but you could find the associated widget, then delete them from the document.
I.e.

const widgets = field.widgets;  

widgets.forEach(widget => {
  instance.Core.annotationManager.deleteAnnotation(widget);
});

// field.widgets should now return an empty array

Note that a form field can have many widgets (the visual UI elements for user input), but a widget can only be associated to a single field. Setting the field’s widget to an empty array would not actually clear the UI elements (the widget Annotations).

best regards,
Kevin

1 Like