PrizmDoc v13.0 - Updated
Class: Comment

Class: Comment

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 KVPs 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 KVPs 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 KVPs 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