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

    PCCViewer. Conversation

    new Conversation(mark)

    A collection of comments associated with a specific PCCViewer.Mark Object.

    A Conversation Object is already available on each PCCViewer.Mark, and should not be created directly through this constructor.

    Parameters:

    Name Type Description
    mark PCCViewer.Mark

    The Mark to which the conversation is attached.

    Throws:

    If mark is not a PCCViewer.Mark Object.

    Type
    Error

    Example

    // assume we already have some marks on the document
    var firstMark = viewerControl.getAllMarks()[0];
    
    var conversation = firstMark.getConversation();
    

    Methods

    addComment(commentText) → {PCCViewer.Comment}

    Adds a comment to the Conversation.

    Parameters:

    Name Type Description
    commentText string

    The text content of the comment being added.

    See:

    Throws:

    If commentText is not a string.

    Type
    Error

    Returns:

    The newly created comment.

    Type
    PCCViewer.Comment

    deleteComments(comments) → {PCCViewer.Conversation}

    Deletes the specified comment or comments from the Conversation.

    Parameters:

    Name Type Description
    comments PCCViewer.Comment | Array.<PCCViewer.Comment>

    A comment or array of comments to be deleted.

    Returns:

    The conversation Object.

    Type
    PCCViewer.Conversation

    getComments() → {Array.<PCCViewer.Comment>}

    Gets an array of all comments in the Conversation. The comments are ordered by the creation date and time.

    Returns:

    An array of Comments.

    Type
    Array.<PCCViewer.Comment>

    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 Conversation.

    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 conversation = myMark.getConversation();
    
    // The key "Resolved" is set the value "false".
    conversation.setData("Resolved", "false");
    
    // The key "Severity" is set the value "Critical".
    conversation.setData("Severity", "Critical");
    
    conversation.getData("Resolved"); // returns "false"
    conversation.getData();           // returns {"Resolved":"false", "Severity":"Critical"}
    conversation.getData("FooBar");   // returns undefined
    

    getDataKeys() → {Array.<string>}

    Gets an array of data keys known to this Conversation.

    See:

    Returns:

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

    Type
    Array.<string>

    Example

    var conversation = myMark.getConversation();
    
    // Returns an empty array before key-value pairs are stored.
    conversation.getDataKeys(); // returns []
    
    // Returns a list of all keys.
    conversation.setData("Resolved", "false");
    conversation.setData("Severity", "Critical");
    conversation.getDataKeys(); // returns ["Resolved", "Severity"]
    

    getMark() → {PCCViewer.Mark}

    Gets the PCCViewer.Mark to which the conversation is attached.

    Returns:

    The Mark to which the conversation is attached.

    Type
    PCCViewer.Mark

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

    This method is defined on all Conversation 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 conversation = myMark.getConversation();
    
    // The key "Author" is set the value "Mark".
    conversation.setSessionData("Author", "Mark");
    
    // The key "Note" is set the value "This is not going to be saved!".
    conversation.setSessionData("Note", "This is not going to be saved!");
    
    conversation.getSessionData("Author"); // returns "Mark"
    conversation.getSessionData();         // returns {"Author":"Mark", "Note":"This is not going to be saved!"}
    conversation.getSessionData("FooBar"); // returns undefined
    

    getSessionDataKeys() → {Array.<string>}

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

    This method is defined on all Conversation objects.

    See:

    Returns:

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

    Type
    Array.<string>

    Example

    var conversation = myMark.getConversation();
    
    // Returns an empty array before key-value pairs are stored.
    conversation.getSessionDataKeys(); // returns []
    
    // Returns a list of all keys.
    conversation.setSessionData("Author", "Mark");
    conversation.setSessionData("Note", "This is not going to be saved!");
    conversation.getSessionDataKeys(); // returns ["Author", "Note"]
    

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

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

    Type
    PCCViewer.Conversation

    Example

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

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

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

    This method is defined on all Conversation 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 Conversation object on which the method was called.

    Type
    PCCViewer.Conversation

    Example

    var conversation = myMark.getConversation();
    
    // Get data returns undefined before the key is set.
    conversation.getSessionData("Author"); // returns undefined
    
    // The key "Author" is set the value "Mark".
    conversation.setSessionData("Author", "Mark");
    conversation.getSessionData("Author"); // returns "Mark"
    
    // The key "Author" is overwritten with the value "Clark".
    conversation.setSessionData("Author", "Clark");
    conversation.getSessionData("Author"); // returns "Clark"
    
    // The key "Author" is unset, by setting the value to undefined.
    conversation.setSessionData("Author", undefined);
    conversation.getSessionData("Author"); // returns undefined
    
    // The value can only be set to a string or undefined.
    // All other data types throw.
    conversation.setSessionData("FooBar", null); // throws
    conversation.setSessionData("FooBar", 1);    // throws
    conversation.setSessionData("FooBar", true); // throws
    conversation.setSessionData("FooBar", {});   // throws
    conversation.setSessionData("FooBar", []);   // throws
    

    Documentation generated by JSDoc 3.3.3 on Fri Sep 10 2021 12:15:35 GMT-0400 (Eastern Daylight Time)