PrizmDoc® Viewer v13.26 Release - Updated
PrizmDoc Viewer / API Reference / Viewer Control / Namespace: PCCViewer / Class: MarkupLayer
In This Topic
    Class: MarkupLayer
    In This Topic

    PCCViewer. MarkupLayer

    (protected) new MarkupLayer(viewerControl, markReferencesopt)

    The MarkupLayer object is used to group together marks and their associated comments. A layer may be persisted to the web tier using PCCViewer.ViewerControl#saveMarkupLayer. Also, a layer may be stored in a PCCViewer.MarkupLayerCollection where it can be retrieved for later use.

    When creating a layer, mark references may be added. A mark reference is a JSON object that represents a comment that refers to a mark on another layer. When the current user comments on a mark that does not exist in his layer, then his persisted layer record will contain a reference to the mark while the full mark will exist in another record. Because records might be loaded out of order or in an incomplete set, this parameter provides a way to store the mark reference. If the record containing the full mark loads later then the data stored here can be attached to it.

    After creating a layer, marks may be added and removed from it.

    The MarkupLayer object also provides an event subscription method, to get notified of other types of information. See PCCViewer.MarkupLayer.EventType.

    Example

    // Optionally, specify any references to marks on another layer or layers
    var markReference = {
         creationDateTime: "2015-06-12T21:20:58.527Z",
         data: {
             "key1": "value1",
             "key2": "value2"
         },
         markUid: "ZZZrOV8yMDE1LTA2LTExVDE5OjU5OjEwLjE3MlpfNDg2dzI5",
         text: "user 1 comment on user 3 mark"
    };
    
    // Create a new layer
    var layer = new PCCViewer.MarkupLayer(viewerControl, markReference);
    
    //register some events
    layer
        .on(PCCViewer.MarkupLayer.EventType.MarkupLayerCreated, function(ev) {
            alert("Markup layer created.");
        })
        .on(PCCViewer.MarkupLayer.EventType.MarkupLayerDestroyed, function(ev) {
            alert("Markup layer destroyed.");
        })
        .on(PCCViewer.MarkupLayer.EventType.MarksAddedToLayer, function(ev) {
            alert("Mark added to layer: " + ev.marks[0].getId());
        })
        .on(PCCViewer.MarkupLayer.EventType.MarksRemovedFromLayer, function(ev) {
            alert("Mark removed from layer: " + ev.marks[0].getId());
        })
        .on(PCCViewer.MarkupLayer.EventType.MarkupLayerInteractionModeChanged, function(ev) {
            alert("Layer's interaction mode changed to: " + ev.interactionMode);
        })
        .on(PCCViewer.MarkupLayer.EventType.MarkupLayerHidden, function(ev) {
            alert("MarkupLayer#hide() called.");
        })
        .on(PCCViewer.MarkupLayer.EventType.MarkupLayerShown, function(ev) {
            alert("MarkupLayer#show() called.");
        });
    
    // Create a new mark
    var mark = viewerControl.addMark(1, "HighlightAnnotation");
    // Add the mark to the layer
    layer.addMarks(mark);
    // Determine if a mark is contained in a layer
    var markInLayer = layer.hasMark(mark.getId());
    
    

    Parameters:

    Name Type Attributes Description
    viewerControl string

    The PCCViewer.ViewerControl for the loaded document.

    markReferences Object | Array.<Object> <optional>

    The JSON reference node (or an array of them) from the markup layer record.

    Members

    (static, readonly) EventType :string

    A list of events that can be triggered by the PCCViewer.MarkupLayer object.

    Note: This enumeration is for convenience for API developers. Instead of using this enumeration, you can pass string values of the eventType (enumeration values)

    Type:

    • string

    Properties:

    Name Description
    MarkupLayerCreated : string
    MarkupLayerDestroyed : string
    MarksAddedToLayer : string
    MarksRemovedFromLayer : string
    MarkupLayerInteractionModeChanged : string
    MarkupLayerHidden : string
    MarkupLayerShown : string
    See:

    (readonly) id :Object

    Gets the layer's ID.

    This property is defined on all MarkupLayer objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Example

    var id = MarkupLayer.id;
    
    

    Type:

    • Object
    See:

    name :Object

    Gets and sets the layer's name.

    This property is defined on all MarkupLayer objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Example

    var name = MarkupLayer.name;
    
    

    Type:

    • Object
    See:

    originalXmlName :Object

    Gets and sets the layer's original XML name.

    This property is defined on all MarkupLayer objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Example

    var name = MarkupLayer.originalXmlName;
    
    

    Type:

    • Object
    See:

    (readonly) recordId :Object

    Gets the ID of web tier record from which this layer was created.

    This property is defined on all MarkupLayer objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Example

    var recordId = MarkupLayer.recordId;
    
    

    Type:

    • Object
    See:

    (readonly) viewerControl :Object

    Gets the viewer control associated with this layer.

    This property is defined on all MarkupLayer objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Example

    var viewerControl = MarkupLayer.viewerControl;
    
    

    Type:

    • Object
    See:

    Methods

    addMarks(marks) → {PCCViewer.MarkupLayer}

    Used to add marks to the layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var mark = viewerControl.addMark(1, 'HighlightAnnotation'); // Create a new mark
    markupLayer.addMarks(mark);
    
    

    Parameters:

    Name Type Description
    marks PCCViewer.Mark | Array.<PCCViewer.Mark>

    A PCCViewer.Mark object or an array of them.

    Returns:

    The markup layer Object.

    Type
    PCCViewer.MarkupLayer

    copyLayers(markupLayers) → {PCCViewer.MarkupLayer}

    Copies marks from other layers to this layer.

    Note: This method requires that attributes of each page referenced by the layer marks have been obtained by the viewer prior to calling. Use PCCViewer.ViewerControl#requestPageAttributes to obtain the necessary page attributes before calling this method.

    Note: The copied marks are assigned new unique IDs, and any references to the original mark (such as a comment on the mark that is stored in another layer) will not reference the copied mark. A copy of each comment on the mark is put on the copy of the mark in this layer.

    Example

    var markupLayer1 = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var markupLayer2 = viewerControl.getMarkupLayerCollection().getAll()[1]; // Get the second markup layer.
    var markupLayer4 = viewerControl.getMarkupLayerCollection().getAll()[3]; // Get the fourth markup layer.
    // Concatenate layers 2 and 4 to a single array.
    var layersToCopy = markupLayer2.concat(markupLayer4);
    // Copy the layers to this layer.
    markupLayer1.copyLayers(layersToCopy);
    
    

    Parameters:

    Name Type Description
    markupLayers Array.<PCCViewer.MarkupLayer>

    An array of markup layers to copy to this layer.

    Throws:

    If markupLayers is not an array of markup layers known to the viewer.

    Type
    Error

    Returns:

    The markup layer Object on which this method was called.

    Type
    PCCViewer.MarkupLayer

    destroy()

    This method will remove the layer from the viewer control's markup layer collection. Also, it will de-register any event listeners associated with the layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    markupLayer.destroy();
    
    

    getData(key) → {string|object}

    Gets the data value for the given key, or gets a hash containing all key values, if a key was not provided.

    This method is defined on all MarkupLayer objects.

    Example

    // The key "Username" is set the value "Admin".
    layer.setData("Username", "Admin");
    
    // The key "CreatedDate" is set the value "1970-01-01".
    layer.setData("CreatedDate", "1970-01-01");
    
    layer.getData("Username"); // returns "Admin"
    layer.getData();         // returns {"Username":"Admin", "CreatedDate":"1970-01-01"}
    layer.getData("FooBar"); // returns undefined
    
    

    Parameters:

    Name Type Description
    key string

    The key for which to get the data value.

    See:

    Throws:

    If the key argument is null or otherwise not a string.

    Type
    Error

    Returns:

    • If a key argument was provided, it returns the associated value.
    • If a key argument was provided, but a value has not been associated with the key, then it returns undefined.
    • If a key was not provided, it returns a hash object containing all key-value pairs.
    Type
    string | object

    getDataKeys() → {Array.<string>}

    Gets an array of data keys known to this MarkupLayer.

    This method is defined on all MarkupLayer objects.

    Example

    // Returns an empty array before key-value pairs are stored.
    layer.getDataKeys(); // returns []
    
    // Returns a list of all keys.
    layer.setData("Username", "Admin");
    layer.setData("CreatedDate", "1970-01-01");
    layer.getDataKeys(); // returns ["Username", "CreatedDate"]
    
    
    See:

    Returns:

    Returns an array of data keys known to this MarkupLayer. If no data is stored, then an empty array will be returned.

    Type
    Array.<string>

    getId() → {string}

    Gets the layer's ID.

    Returns:

    The ID of the layer.

    Type
    string

    getMarkReferences() → {Array.<Object>}

    Gets the mark references associated with this layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var markReferences = markupLayer.getMarkReferences();
    
    

    Returns:

    An array of mark reference Objects.

    Type
    Array.<Object>

    getMarks() → {Array.<PCCViewer.Mark>}

    Gets the marks associated with this layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var marks = markupLayer.getMarks();
    
    

    Returns:

    An array of {PCCViewer.Mark} Objects.

    Type
    Array.<PCCViewer.Mark>

    getName() → {string}

    Gets the layer's name.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var layerName = markupLayer.getName();
    
    

    Returns:

    The name of the layer.

    Type
    string

    getOriginalXmlName() → {string}

    Gets the name of the web tier XML record from which the marks of this layer were originally stored.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var originalXmlName = markupLayer.getOriginalXmlName();
    
    

    Returns:

    The name of the web tier XML record from which the marks of this layer were originally stored.

    Type
    string

    getRecordId() → {string}

    Gets the ID of web tier record from which this layer was created.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var recordId = markupLayer.getRecordId();
    
    

    Returns:

    The layer record ID

    Type
    string

    getSessionData(key) → {string|object}

    Gets the session data value for the given key, or gets a hash containing all key values, if a key was not provided. Unlike PCCViewer.MarkupLayer#getData, this data is not saved with the annotation, it only lasts for the session.

    This method is defined on all MarkupLayer objects.

    Example

    // The key "Username" is set the value "Admin".
    layer.setSessionData("Username", "Admin");
    
    // The key "CreatedDate" is set the value "1970-01-01".
    layer.setSessionData("CreatedDate", "1970-01-01");
    
    layer.getSessionData("Username"); // returns "Admin"
    layer.getSessionData();           // returns {"Username":"Admin", "CreatedDate":"1970-01-01"}
    layer.getSessionData("FooBar");   // returns undefined
    
    

    Parameters:

    Name Type Description
    key string

    The key for which to get the data value.

    See:

    Throws:

    If the key argument is null or otherwise not a string.

    Type
    Error

    Returns:

    • If a key argument was provided, it returns the associated value.
    • If a key argument was provided, but a value has not been associated with the key, then it returns undefined.
    • If a key was not provided, it returns a hash object containing all key-value pairs.
    Type
    string | object

    getSessionDataKeys() → {Array.<string>}

    Gets an array of data keys known to this MarkupLayer. Unlike PCCViewer.MarkupLayer#getDataKeys, this data is not saved with the annotation, it only lasts for the session.

    This method is defined on all MarkupLayer objects.

    Example

    // Returns an empty array before key-value pairs are stored.
    layer.getSessionDataKeys(); // returns []
    
    // Returns a list of all keys.
    layer.setSessionData("Username", "Admin");
    layer.setSessionData("CreatedDate", "1970-01-01");
    layer.getSessionDataKeys(); // returns ["Username", "CreatedDate"]
    
    
    See:

    Returns:

    Returns an array of data keys known to this MarkupLayer. If no data is stored, then an empty array will be returned.

    Type
    Array.<string>

    getViewerControl() → {PCCViewer.ViewerControl}

    Gets the viewer control associated with this layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var viewerControl = markupLayer.getViewerControl();
    
    

    Returns:

    A viewer control object.

    Type
    PCCViewer.ViewerControl

    hasMark(markId) → {boolean}

    Used to query the layer to see if it contains a particular mark.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    var mark = viewerControl.getAllMarks()[0];
    var markExistsInLayer = markupLayer.hasMark(mark.getId());
    
    

    Parameters:

    Name Type Description
    markId string

    A mark's id.

    Returns:

    A true or false indication depending on whether the mark exists in the layer.

    Type
    boolean

    hide() → {PCCViewer.MarkupLayer}

    Hides all of the marks in the layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    markupLayer.hide(); // Hide the marks in the layer.
    
    

    Returns:

    The markup layer Object on which this method was called.called.

    Type
    PCCViewer.MarkupLayer

    off(eventType, handler) → {PCCViewer.MarkupLayer}

    Unsubscribe an event handler from a specified event type.

    Typically, an event is unsubscribed when you no longer want further notification of the event.

    Parameters:

    Name Type Description
    eventType string

    A string specifying the event type. See PCCViewer.MarkupLayer.EventType for a list and description of all supported events.

    handler PCCViewer.Event~eventHandler

    A function that was attached previously to the ViewerControl.

    Note: This must be the same function object previously passed to PCCViewer.MarkupLayer#on. It cannot be a different object that is functionally equivalent.

    See:

    Returns:

    The MarkupLayer object on which this method was called.

    Type
    PCCViewer.MarkupLayer

    on(eventType, handler) → {PCCViewer.MarkupLayer}

    Subscribe an event handler to an event of a specified type.

    Parameters:

    Name Type Description
    eventType string

    A string that specifies the event type. This value is case-insensitive. See PCCViewer.MarkupLayer.EventType for a list and description of all supported events.

    handler PCCViewer.Event~eventHandler

    A function that will be called whenever the event is triggered.

    See:

    Returns:

    The MarkupLayer object on which this method was called.

    Type
    PCCViewer.MarkupLayer

    removeMarks(marks) → {PCCViewer.MarkupLayer}

    Used to remove marks from the layer.

    Example

    var markupLayer = viewerControl.getActiveMarkupLayer(); // Get the active markup layer.
    var mark = viewerControl.addMark(1, 'HighlightAnnotation'); // Create a new mark
    markupLayer.removeMarks(mark); // remove the mark from the active layer
    
    

    Parameters:

    Name Type Description
    marks PCCViewer.Mark | Array.<PCCViewer.Mark>

    A PCCViewer.Mark object or an array of them.

    Returns:

    The markup layer Object.

    Type
    PCCViewer.MarkupLayer

    setData(key, value) → {PCCViewer.MarkupLayer}

    Sets the data value for the given key.

    This method is defined on all MarkupLayer objects.

    Notes:

    • Overwrites any data value already associated with the given key.
    • There is no artificial limit imposed on the number of key-value pairs that are stored.
    • If limits on the number of key-value pairs are required, they should be enforced by calling code.
    • Setting the value as undefined results in no information for the key being persisted to the server.
    • The returned data is not mutated or sanitized, which could lead to a security vulnerability if not sanitized properly before use.

    Example

    // Get data returns undefined before the key is set.
    layer.getData("Username"); // returns undefined
    
    // The key "Username" is set the value "Admin".
    layer.setData("Username", "Admin");
    layer.getData("Username"); // returns "Admin"
    
    // The key "Username" is overwritten with the value "Guest1".
    layer.setData("Username", "Guest1");
    layer.getData("Username"); // returns "Guest1"
    
    // The key "Username" is unset, by setting the value to undefined.
    layer.setData("Username", undefined);
    layer.getData("Username"); // returns undefined
    
    // The value can only be set to a string or undefined.
    // All other data types throw.
    layer.setData("FooBar", null); // throws
    layer.setData("FooBar", 1);    // throws
    layer.setData("FooBar", true); // throws
    layer.setData("FooBar", {});   // throws
    layer.setData("FooBar", []);   // throws
    
    

    Parameters:

    Name Type Description
    key string

    The key for which to set the data value.

    value string

    This is the value to set for the key.

    • This must be a string or undefined.
    • The maximum length of the string is not limited by this function.
    See:

    Returns:

    The MarkupLayer object on which the method was called.

    Type
    PCCViewer.MarkupLayer

    setInteractionMode(interactionMode) → {PCCViewer.MarkupLayer}

    Used to alter the interaction mode of all marks in a layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    markupLayer.setInteractionMode(PCCViewer.Mark.InteractionMode.SelectionDisabled);
    
    

    Parameters:

    Name Type Description
    interactionMode string

    A string value from the enumeration PCCViewer.Mark.InteractionMode,

    Returns:

    The markup layer Object on which this method was called

    Type
    PCCViewer.MarkupLayer

    setName(name) → {PCCViewer.MarkupLayer}

    Sets the layer's name.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    markupLayer.setName('Final Draft');
    
    

    Parameters:

    Name Type Description
    name string

    The name to apply to this layer.

    Returns:

    The markup layer Object on which this method was called.

    Type
    PCCViewer.MarkupLayer

    setOriginalXmlName(name) → {PCCViewer.MarkupLayer}

    Sets the name of the web tier XML record from which the marks of this layer were originally stored. If the layer is not associated with an XML file, the property should be set to an empty string.

    When the original XML name is set and a markup layer is saved, the original XML name is saved in the markup layer JSON. When the PCCViewer.ViewerControl#requestMarkupLayerNames method is called, the original XML name will be provided.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    markupLayer.setOriginalXmlName('my marks');
    ```
    

    Parameters:

    Name Type Description
    name string

    The name of the web tier XML record from which the marks of this layer were originally stored.

    Returns:

    The markup layer Object on which this method was called.

    Type
    PCCViewer.MarkupLayer

    setSessionData(key, value) → {PCCViewer.MarkupLayer}

    Sets the session data value for the given key. Unlike PCCViewer.MarkupLayer#setData, this data is not saved with the annotation, it only lasts for the session.

    This method is defined on all MarkupLayer objects.

    Example

    // Get data returns undefined before the key is set.
    layer.getSessionData("Username"); // returns undefined
    
    // The key "Username" is set the value "Admin".
    layer.setSessionData("Username", "Admin");
    layer.getSessionData("Username"); // returns "Admin"
    
    // The key "Username" is overwritten with the value "Guest1".
    layer.setSessionData("Username", "Guest1");
    layer.getSessionData("Username"); // returns "Guest1"
    
    // The key "Username" is unset, by setting the value to undefined.
    layer.setSessionData("Username", undefined);
    layer.getSessionData("Username"); // returns undefined
    
    // The value can only be set to a string or undefined.
    // All other data types throw.
    layer.setSessionData("FooBar", null); // throws
    layer.setSessionData("FooBar", 1);    // throws
    layer.setSessionData("FooBar", true); // throws
    layer.setSessionData("FooBar", {});   // throws
    layer.setSessionData("FooBar", []);   // throws
    
    

    Parameters:

    Name Type Description
    key string

    The key for which to set the data value.

    value string

    This is the value to set for the key.

    • This must be a string or undefined.
    • The maximum length of the string is not limited by this function.
    See:

    Returns:

    The MarkupLayer object on which the method was called.

    Type
    PCCViewer.MarkupLayer

    show() → {PCCViewer.MarkupLayer}

    Shows all of the marks in the layer.

    Example

    var markupLayer = viewerControl.getMarkupLayerCollection().getAll()[0]; // Get the first markup layer.
    markupLayer.show(); // Show the marks in the layer.
    
    

    Returns:

    The markup layer Object on which this method was called.

    Type
    PCCViewer.MarkupLayer

    Documentation generated by JSDoc 3.6.10 on Fri Dec 15 2023 17:21:57 GMT+0000 (Coordinated Universal Time)