Class: 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.

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:

PCCViewer.Comment#setCreationTime

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:

PCCViewer.Comment#setText

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:

PCCViewer.Comment#getCreationTime

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

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.

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

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.

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.