PrizmDoc Viewer v13.15 Release - Updated
API Reference / Viewer Control / Namespace: PCCViewer / Class: Comment
In This Topic
    Class: Comment
    In This Topic

    PCCViewer. Comment

    new Comment(comment, conversation)

    The constructor for a Comment Object. This describes the comments that belong to a mark PCCViewer.Conversation.

    It will not be necessary to create comments directly with this constructor. Rather, simply use PCCViewer.Conversation#addComment.

    Note: Comment text is not sanitized in any way by the API, and will exist as the same string value assigned to it. To ensure security of the web application, text data may need to be sanitized and safely inserted into the DOM when it is used.

    Parameters:

    Name Type Description
    comment string

    The text content of the comment.

    conversation PCCViewer.Conversation

    The PCCViewer.Conversation Object that this comment belongs to.

    Throws:

    • If commentText is not a string.

      Type
      Error

    • If conversation is not a PCCViewer.Conversation Object.

      Type
      Error

    Example

    // assume we already have a PCCViewer.Mark object created
var conversation = mark.getConversation();

var comment = conversation.addComment('This is the best comment ever.');

    Members

    creationTime :string

    Gets and sets the date and time when the comment was created.

    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.

    Type:

    • string
    See:

    text :string

    Gets and sets the text content of the Comment.

    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.

    Type:

    • string
    See:

    Methods

    getConversation() → {PCCViewer.Conversation}

    Gets the conversation that this comment is (or was) a part of.

    Returns:

    The Comment's Conversation.

    If a comment is deleted from a conversation, this still returns the Conversation object.

    Type
    PCCViewer.Conversation

    getCreationTime() → {Date}

    Gets the date and time when the comment was created.

    See:

    Returns:

    A JavaScript Date Object representing the creation time of the comment.

    Type
    Date

    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.

    Note: If a hash is returned, this will be a new object each time it is called. Adding new properties to the returned hash will not add data to the Comment.

    Note: The returned data is not mutated or sanitized, which could lead to a security vulnerability if not sanitized properly before use.

    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

    Example

    var comment = myConversation.addComment("Hello world.");

// The key "Author" is set the value "Mark".
comment.setData("Author", "Mark");

// The key "Severity" is set the value "Critical".
comment.setData("Severity", "Critical");

comment.getData("Author"); // returns "Mark"
comment.getData();         // returns {"Author":"Mark", "Severity":"Critical"}
comment.getData("FooBar"); // returns undefined

    getDataKeys() → {Array.<string>}

    Gets an array of data keys known to this Comment.

    See:

    Returns:

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

    Type
    Array.<string>

    Example

    var comment = myConversation.addComment("Hello world.");

// Returns an empty array before key-value pairs are stored.
comment.getDataKeys(); // returns []

// Returns a list of all keys.
comment.setData("Author", "Mark");
comment.setData("Severity", "Critical");
comment.getDataKeys(); // returns ["Author", "Severity"]

    getMarkupLayer() → {PCCViewer.MarkupLayer}

    Gets the markup layer that this comment is (or was) a part of.

    Returns:

    The comment's markup layer.

    If a comment is removed from a markup layer, this still returns the markup layer object.

    Type
    PCCViewer.MarkupLayer

    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.Comment#getData, this data is not saved with the annotation, it only lasts for the session.

    This method is defined on all Comment objects.

    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

    Example

    var comment = myConversation.addComment("Hello world.");

// The key "Author" is set the value "Mark".
comment.setSessionData("Author", "Mark");

// The key "Note" is set the value "This is not going to be saved!".
comment.setSessionData("Note", "This is not going to be saved!");

comment.getSessionData("Author"); // returns "Mark"
comment.getSessionData();         // returns {"Author":"Mark", "Note":"This is not going to be saved!"}
comment.getSessionData("FooBar"); // returns undefined

    getSessionDataKeys() → {Array.<string>}

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

    This method is defined on all Comment objects.

    See:

    Returns:

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

    Type
    Array.<string>

    Example

    var comment = myConversation.addComment("Hello world.");

// Returns an empty array before key-value pairs are stored.
comment.getSessionDataKeys(); // returns []

// Returns a list of all keys.
comment.setSessionData("Author", "Mark");
comment.setSessionData("Note", "This is not going to be saved!");
comment.getSessionDataKeys(); // returns ["Author", "Note"]

    getText() → {string}

    Gets the text content of the Comment.

    Note: This content will be a plain text string which is not sanitized in any way. It may be necessary to sanitize and safely use the string when inserting it into the DOM.

    See:

    Returns:

    The Comment content.

    Type
    string

    setCreationTime(time) → {PCCViewer.Comment}

    Sets the date and time when the comment was created.

    Parameters:

    Name Type Description
    time Date | string

    A JavaScript Date Object or a string in the ISO 8601 format.

    See:

    Throws:

    • If the value is not a string or a Date object.

      Type
      Error

    • If a string value is used that is not an ISO 8601 date format.

      Type
      Error

    Returns:

    The comment Object.

    Type
    PCCViewer.Comment

    Example

    // assume we already have a Comment
var now = Date.now();
comment.setCreationTime(now);

var janFirst1970 = "1970-01-01T00:00:00.000Z";
comment.setCreationTime(janFirst1970);

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

    Sets the data value for the given key.

    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.

    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:

    Returns the Comment object on which the method was called.

    Type
    PCCViewer.Comment

    Example

    var comment = myConversation.addComment("Hello world.");

// Get data returns undefined before the key is set.
comment.getData("Author"); // returns undefined

// The key "Author" is set the value "Mark".
comment.setData("Author", "Mark");
comment.getData("Author"); // returns "Mark"

// The key "Author" is overwritten with the value "Clark".
comment.setData("Author", "Clark");
comment.getData("Author"); // returns "Clark"

// The key "Author" is unset, by setting the value to undefined.
comment.setData("Author", undefined);
comment.getData("Author"); // returns undefined

// The value can only be set to a string or undefined.
// All other data types throw.
comment.setData("FooBar", null); // throws
comment.setData("FooBar", 1);    // throws
comment.setData("FooBar", true); // throws
comment.setData("FooBar", {});   // throws
comment.setData("FooBar", []);   // throws

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

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

    This method is defined on all Comment objects.

    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 Comment object on which the method was called.

    Type
    PCCViewer.Comment

    Example

    var comment = myConversation.addComment("Hello world.");

// Get data returns undefined before the key is set.
comment.getSessionData("Author"); // returns undefined

// The key "Author" is set the value "Mark".
comment.setSessionData("Author", "Mark");
comment.getSessionData("Author"); // returns "Mark"

// The key "Author" is overwritten with the value "Clark".
comment.setSessionData("Author", "Clark");
comment.getSessionData("Author"); // returns "Clark"

// The key "Author" is unset, by setting the value to undefined.
comment.setSessionData("Author", undefined);
comment.getSessionData("Author"); // returns undefined

// The value can only be set to a string or undefined.
// All other data types throw.
comment.setSessionData("FooBar", null); // throws
comment.setSessionData("FooBar", 1);    // throws
comment.setSessionData("FooBar", true); // throws
comment.setSessionData("FooBar", {});   // throws
comment.setSessionData("FooBar", []);   // throws

    setText(text) → {PCCViewer.Comment}

    Sets the text content of the Comment.

    Parameters:

    Name Type Description
    text string

    The text content being set.

    See:

    Returns:

    The comment Object.

    Type
    PCCViewer.Comment

    Documentation generated by JSDoc 3.3.3 on Tue Nov 10 2020 05:27:30 GMT-0500 (Eastern Standard Time)

     

     

    ©2021 Accusoft Corporation. All Rights Reserved.

    Send Documentation Feedback  |  Get Product Support