PrizmDoc v12.4 - Updated
Class: Conversation

Class: Conversation

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

 

 

©2017. Accusoft Corporation. All Rights Reserved.

Send Feedback