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
markis 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
commentTextis not a string. -
- Type
- Error
Returns:
The newly created comment.
- Type
- PCCViewer.Comment
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
commentTextis 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.
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.
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>
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. |
Throws:
-
If the
keyargument 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
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. |
Throws:
-
If the
keyargument 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.
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 KVPs are stored.
conversation.getDataKeys(); // returns []
// Returns a list of all keys.
conversation.setData("Resolved", "false");
conversation.setData("Severity", "Critical");
conversation.getDataKeys(); // returns ["Resolved", "Severity"]
getDataKeys() → {Array.<string>}
Gets an array of data keys known to this Conversation.
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 KVPs 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
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:
-
- PCCViewer.Data#getSessionData
- PCCViewer.Conversation#setSessionData
- PCCViewer.Conversation#getSessionDataKeys
Throws:
-
If the
keyargument 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
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:
-
- PCCViewer.Data#getSessionData
- PCCViewer.Conversation#setSessionData
- PCCViewer.Conversation#getSessionDataKeys
Throws:
-
If the
keyargument 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:
-
- PCCViewer.Data#getSessionDataKeys
- PCCViewer.Conversation#getSessionData
- PCCViewer.Conversation#setSessionData
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 KVPs 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"]
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:
-
- PCCViewer.Data#getSessionDataKeys
- PCCViewer.Conversation#getSessionData
- PCCViewer.Conversation#setSessionData
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 KVPs 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 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 Conversation object on which the method was called.
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
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 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 Conversation object on which the method was called.
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.
|
- See:
-
- PCCViewer.Data#setSessionData
- PCCViewer.Conversation#getSessionData
- PCCViewer.Conversation#getSessionDataKeys
Returns:
The Conversation object on which the method was called.
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
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.
|
- See:
-
- PCCViewer.Data#setSessionData
- PCCViewer.Conversation#getSessionData
- PCCViewer.Conversation#getSessionDataKeys
Returns:
The Conversation object on which the method was called.
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