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

PCCViewer.Comment

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

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

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

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:

PCCViewer.Data#setSessionData
PCCViewer.Conversation#getSessionData
PCCViewer.Conversation#getSessionDataKeys

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