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
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
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.
getCreationTime() → {Date}
Gets the date and time when the comment was created.
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. |
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.
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.
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:
-
- PCCViewer.Data#getSessionData
- PCCViewer.Comment#setSessionData
- PCCViewer.Comment#getSessionDataKeys
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:
-
- PCCViewer.Data#getSessionDataKeys
- PCCViewer.Comment#getSessionData
- PCCViewer.Comment#setSessionData
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.
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 |
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.
|
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.
|
- See:
-
- PCCViewer.Data#setSessionData
- PCCViewer.Comment#getSessionData
- PCCViewer.Comment#getSessionDataKeys
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. |
Returns:
The comment Object.
- Type
- PCCViewer.Comment