PrizmDoc v13.3 - Updated
Namespace: fn
API Reference > PrizmDoc Viewer API > Namespace: fn

Namespace: fn

jQuery. fn

The jQuery Plugin namespace.

Methods

pccViewer(optionsopt) → {PCCViewer.Viewer}

Creates and embeds a new viewer in the first element of the set of matched elements.

Each call to this method will create and return a unique ViewerControl object. This will call PCCViewer.Viewer#destroy on any existing viewer embedded in the selected element.

If plugin options are provided, then a new viewer is created in the selected element and a PCCViewer.Viewer object is returned. This will call PCCViewer.Viewer#destroy on any viewer that already existed in the selected element.

If plugin options are not provided, then a viewer is not created. Instead, the PCCViewer.Viewer object associated with an existing viewer is returned.

Parameters:
Name Type Attributes Description
options external:jQuery.fn~Options <optional>

Plugin options.

Returns:
Type
PCCViewer.Viewer
Example
//Note: these are already included in the PrizmDoc Samples
var pluginOptions = {
    documentID: viewingSessionId,       // documentID is a required property
    language: languageItems             // language is a required property
};

$(document).ready(function () {
    // Creates a new viewer in the div with id="viewer1"
    var viewer = $("#viewer1").pccViewer(pluginOptions);

    // Can also access the returned object through the plugin.
    var viewerA = $("#viewer1").pccViewer();  // Does not create a new viewer.
    viewerA === viewer;                       // true
});

Type Definitions

DateFormat

The format to use when displaying a date. The table below outlines the supported date format tokens and provides example output.

Token Output
Month M 1 2 ... 11 12
MM 01 02 ... 11 12
Day D 1 2 ... 30 31
DD 01 02 ... 30 31
Year YY 70 71 ... 29 30
YYYY 1970 1971 ... 2029 2030
Hour H 0 1 ... 22 23
HH 00 01 ... 22 23
h 1 2 ... 11 12
hh 01 02 ... 11 12
Minute m 0 1 ... 58 59
mm 00 01 ... 58 59
AM/PM A AM PM
a am pm
Type:
  • String

LanguageOptions

This object is the contents of the language.json file present in all of the HTML5 viewer samples. This file is generally read server-side and passed into the jQuery plugin. It is strongly encouraged to keep a copy of the original file before doing any edits or translations. This object is required by the viewer UI.

For more information on this language file or localization, please consult the help section titled "Localizing the Viewer".

Type:
  • Object

Options

The options object used for the HTML5 viewer jQuery Plugin, external:jQuery.fn#pccViewer. This object is a superset of the main ViewerControl options, PCCViewer.ViewerControl~ViewerControlOptions. All available options for the ViewerControl are also valid here, and will be passed as-is to the ViewerControl during initialization. The following will only include options specific to the jQuery plugin and the Viewer UI functionality inside the viewer.js file.

Type:
  • Object
Properties:
Name Type Attributes Default Description
documentID string

The ID of the document to load. This option is a part of the PCCViewer.ViewerControl~ViewerControlOptions options object.

documentDisplayName string <optional>
"file"

A meaningful name for the document. This name will be used when downloading a signed or redacted document. See PCCViewer.ViewerControl#burnMarkup for more information.

Example: "sample.doc"

imageHandlerUrl string <optional>
"../pcc.ashx"

The end point of the web tier services that support the viewer. Unless specified, viewer.js will assume it is running in the default .NET sample. This option is a part of the PCCViewer.ViewerControl~ViewerControlOptions options object.

language external:jQuery.fn~LanguageOptions

Specifies the language to use for the text in the ViewerControl. Use this option to localize the viewer.

icons string

Specifies the SVG for the icons in the viewer. If an SVG symbol element in this SVG has an id that matches a class name in the viewer HTML templates, then the SVG for that symbol will be added to the viewer element with the matching class name. Note that the id must begin with "pcc-icon-".

redactionReasons external:jQuery.fn~redactionReasons <optional>

A list of reasons to be used for the redaction reasons controls.

annotationsMode string <optional>
"LegacyAnnotations"

The annotationsMode specifies the mode in which the annotations will be handled in the viewer. When the annotationsMode is set to "LegacyAnnotations" (default), all annotations will be handled as in the releases prior to 10.3. The second option is "LayeredAnnotations". This option supports the new layered annotations feature available in the releases 10.3 and higher. A convenience enumeration for these two annotation mode types annotationsModeEnum is available in the viewer.js file and as a property of the Viewer object. This enumeration is not available in the API.

Deprecation Notice: In the future, the "LegacyAnnotations" option will be deprecated.

annotationID string <optional>

Specifies the annotation file to be used within the viewer.

This property is only observed when annotationsMode is set to "LegacyAnnotations".

autoLoadAnnotation boolean <optional>
false

If set to true, the specified annotation file will be loaded when the viewer launches.

This property is only observed when annotationsMode is set to "LegacyAnnotations".

autoLoadAllLayers boolean <optional>
false

When set to true, all available layers will be loaded into the document. This includes all layers returned by requestMarkupLayerNames and getSavedMarkupNames.

This property is only observed when annotationsMode is set to "LayeredAnnotations".

editableMarkupLayerSource string <optional>

When set to "LayerRecordId", the layer with the record ID specified by the editableMarkupLayerValue will be loaded from JSON into the document. When set to "XmlName", the layer with the name specified by the editableMarkupLayerValue viewer parameter will be loaded from XML into the document, unless the XML layer with that name has been saved to JSON, in which case the layer will be loaded from JSON. When set to "DefaultName", a new empty layer is loaded into the document but given the name specified by the editableMarkupLayerValue viewer parameter.

This property is only observed when annotationsMode is set to "LayeredAnnotations" and editableMarkupLayerValue is set to a valid value.

editableMarkupLayerValue string <optional>

When the editableMarkupLayerSource viewer parameter is set to "LayerRecordId", this specifies the record ID of the layer that will be loaded from JSON into the document. When the editableMarkupLayerSource viewer parameter is set to "XmlName", this specifies the name of the XML layer that will be loaded from XML into the document, unless the XML layer with that name has been saved to JSON, in which case the layer will be loaded from JSON. When the editableMarkupLayerSource viewer parameter is set to "DefaultName", this specifies name to give the new empty layer.

This property is only observed when annotationsMode is set to "LayeredAnnotations" and editableMarkupLayerSource is set to a valid value.

lockEditableMarkupLayer boolean <optional>
false

When set to true, the buttons that open the load annotations (for edit) dialog will be removed so that it is not possible to change the editable markup layer. The menu item that opens the edit layer name dialog will also be removed so it is not possible to rename the editable markup layer.

template Object

This objects holds the various templates that the viewer UI needs. The templates correspond to HTML files available in all samples -- the filenames use the same name as the template names here, appending "Template.html" to the end -- for example, the template fileName would correcpond to a fileNameTemplate.html file.

Properties
Name Type Description
viewer string

This is the main viewer template. It contains partial HTML, and is parsed using Underscore to complete template variables.

contextMenu string

This is the template for the floating menu used to edit annotations. It contains partial HTML, and is parsed using Underscore to complete template variables.

overwriteOverlay string

This is the template used for the overlay menu when the Viewer detects that the user is saving markup using a name that already exists. It contains partial HTML, and is parsed using Underscore to complete template variables.

unsavedChangesOverlay string

This is the template used for the overlay menu when the Viewer detects that the user is opening a markup file while having unsaved markup already loaded in the viewer. It contains partial HTML, and is parsed using Underscore to complete template variables.

printOverlay string

This is the template used for the overlay menu displayed when the user selects to print the document. It contains partial HTML, and is parsed using Underscore to complete template variables.

print string

This is the template used to enable the viewer to print. This template contains a full HTML page. Variables are parsed using curly brackets. This template is part of the main ViewerControl options, PCCViewer.ViewerControl~ViewerControlOptions.

downloadOverlay string

This is the template used for the overlay menu displayed when the user selects to download the document. It contains partial HTML, and is parsed using Underscore to complete template variables.

esignOverlay string

This is the template used for the overlay menu displayed when the user selects to manage e-signatures. It contains partial HTML, and is parsed using Underscore to complete template variables.

comment string

This is the template for comments displayed in the ViewerControl comments panel. It contains partial HTML, and is parsed using Underscore to complete template variables.

copyOverlay string

This is the template used for the clipboard overlay when a user attempts to copy document text using a touch device. It contains partial HTML, and is parsed using Underscore to complete template variables.

hyperlinkMenu string

This is the template used to render the menu that appears when a user creates or views a hyperlink annotation. It contains partial HTML, and is parsed using Underscore to complete template variables.

imageStampOverlay string

This is the template used for the image stamp picker for the image stamp annotations and redactions. It contains partial HTML, and is parsed using Underscore to complete template variables.

pageRedactionOverlay string

This is the template used for the full page redaction selection dialog. It contains partial HTML, and is parsed using Underscore to complete template variables.

uiElements Object <optional>

This object contains directives to easily hide or disable default UI elements in the viewer. This option is an alternative to removing the elements entirely from the viewerTemplate.html file, and enables having features that are conditionally available.

When the viewer removes various elements, it looks for a data-pcc-removable-id to be defined on the HTML element. This id will match to the key defined in the uiElements object. Setting the value of that key to true, or not including the key at all, results in the respective elements being visible and active in the viewer. Setting the key to false will cause the viewer to remove that element at runtime.

This feature is enabled for viewerTemplate.html and contextMenuTemplate.html. The following data-pcc-removable-id keys are already defined by default:

Properties
Name Type Attributes Default Description
annotateTab boolean <optional>
true

Show or hide the Annotate Tab.

redactTab boolean <optional>
true

Show or hide the Redact Tab.

searchTab boolean <optional>
true

Show or hide the Search Tab.

viewTab boolean <optional>
true

Show or hide the View Tab.

esignTab boolean <optional>
true

Show or hide the E-Sign Tab.

copyPaste boolean <optional>
true

Show or hide the Text Select Tool.

download boolean <optional>
true

Show or hide the Download Button.

printing boolean <optional>
true

Show or hide the Print Button.

advancedSearch boolean <optional>
false

Enables the advanced search features, including searching through marks and comments.

attachments boolean <optional>
true

If true, the viewer will automatically load attachments of the currently loaded document.

fullScreenOnInit boolean <optional>
false

Specifies whether the viewer will fill the browser window when initialized. If this is not defined or set to false the viewer will use the width and height set in viewer.css.

comparisonTools string <optional>
"availableIfRevisions"

Sets the mode of the comparison tools. The following options are available:

  • "notAvailable": No toggle button shown, panel is not able to be opened.
  • "available": Toggle button shown, panel must be opened by clicking the button.
  • "active": Toggle button shown, panel is displayed on initialization.
  • "availableIfRevisions": Toggle button shown if revisions exist, panel must be opened by clicking the button.
  • "activeIfRevisions": Toggle button shown if revisions exist, panel is displayed as soon as revisions are returned.
immediateActionMenuMode string <optional>
"off"

Sets the mode of the immediate action menu. The following options are available:

  • "on": The menu will appear after creating a mark or selecting text, close to the mouse cursor, allowing the user to take quick actions.
  • "hover": In supported browsers, an icon will appear after creating a mark or selecting test. When hovering over this icon, the full menu will appear. On mobile viewports and in IE8, this will be the same as "on".
  • "off": The menu will not appear.
immediateActionMenuActionsFilter object <optional>

When immediateActionMenuMode is set to "on" or "hover", this list will be used to define which actions are available in the menu.

Properties
Name Type Attributes Default Description
comment boolean <optional>
true

Show or hide the Add Comment Button.

select boolean <optional>
true

Show or hide the Select Button.

copy boolean <optional>
true

Show or hide the Copy Button.

highlight boolean <optional>
true

Show or hide the Highlight Button.

redact boolean <optional>
true

Show or hide the Redact Button.

hyperlink boolean <optional>
true

Show or hide the Hyperlink Button.

cancel boolean <optional>
true

Show or hide the Cancel Button.

commentsPanelMode string <optional>
"auto"

Sets the mode of the comments panel. The following options are available:

  • "full": The entire content of the comments are displayed in the sidebar of the document.
  • "skinny": An icon is placed in the sidebar of the document, representing each comment thread. WHen the icon is clicked, the comment thread is expanded to show the full content.
  • "auto": This mode will intelligently switch between the full and skinny mode, in order to optimize the space available for viewing the document.
stickyTools Object <optional>
"default"

Set the mode for the sticky tools behavior.

The following options are available:

  • "on": Sticky tools will always be on. The tool will remain active until the user switches it.
  • "off": Sticky tools will always be off. The tool will remain active for one use, where relevant.
  • "default": Clicking on a mouse tool button will toggle between sticky and non-sticky mode. The first click will trigger the tool in non-sticky mode, and every following click will toggle sticky mode on and off.

See the stickyToolsFilter option for more information.

stickyToolsFilter Object <optional>

When stickyTools is set to "on" or "default", this list will be used to define which tools will have the sticky behavior. By default, all drawing tools (such as EllipseAnnotation, RectangleRedaction, etc.) will have this enhanced behavior enabled. Tools that do not appear on this list (and are not part of the defaults), or tools set to false, will never exhibit the sticky behavior.

This object can have any of the values listed in PCCViewer.MouseTool.Type, using the same keys as that enumerable. The values for these keys are true for enabled, and false for disabled.

See the stickyTools option for more information.

Note that for some tools, like Magnifier or PanAndEdit, this mode is not relevant, as these tools always remain active until the user chooses a new tool. Keeping them on or off the list will not change that tool's behavior.

Example: { RectangleAnnotation: true, PlaceSignature: false }

signatureCategories string <optional>

Specifies the categories of eSignature to add to the UI. This is a comma separated string containing the types of signatures that the application expects. When no value is passed in, the UI to select categories will be disabled.

Example: "Full Signature,Initials,Name,Title"

commentDateFormat external:jQuery.fn~DateFormat <optional>
"MM/DD/YYYY h:mma"

Specifies the date format to use to display comment dates.

signatureDateFormat external:jQuery.fn~DateFormat <optional>
"MM/DD/YYYY"

Specifies the date format to use to display date signatures.

predefinedSearch Object <optional>

Specifies options so that the viewer can prepopulate the document with search terms. An example of this is defined in the predefinedSearch.json file available in all HTML5 viewer samples.

Properties
Name Type Attributes Default Description
highlightColor string <optional>

The default highlight color of the search terms. This is overridden by the term-level parameter. This must be in 6 digit hexadecimal format preceded by a #.

Example: "#ee3a8c"

searchOnInit boolean <optional>

Whether to run the search when the viewer is initialized. Only search terms that use selected: true will be searched for when this property is enabled.

fixed boolean <optional>
false

The default fixed value of the search terms. This is overridden by the term-level parameter. If set to true, the search terms are always included when performing a search.

globalOptions Object <optional>
terms Array.<external:jQuery.fn~predefinedSearchTerm> <optional>

An array of search terms to populate predefined search.

searchResultsPageLength number <optional>
250

The number of search results to show at a time in the search results panel. The user can use the search results navigation buttons to page through the search results. If a positive number is not specified, the default of 250 is used.

revisionsPageLength number <optional>
250

The number of revisions to show at a time in the revisions panel. The user can use the revisions navigation buttons to page through the revisions. If a positive number is not specified, the default of 250 is used.

predefinedSearchTerm

The following are options available for the Objects used in the predefinedSearch.terms Array. Any options not specified on the individual search term Object will use the defined property on the predefinedSearch Object, or a viewer default if one does not exist.

Type:
  • Object
Properties:
Name Type Attributes Default Description
searchTerm string

The term to use for search. If used along with userDefinedRegex, this becomes the name of the Regular Expression, while the Regular Expression is used to perform the search.

highlightColor string <optional>

The color to use when highlighting results from this particular search.

fixed boolean <optional>
false

Whether or not the search term is always included when performing a search. If set to true, the value of predefinedSearchTerm.selected is disregarded since the search term is always included.

options Object <optional>

This is the same options object, overriding the settings in globalOptions for this specific term.

userDefinedRegex string <optional>

A regular expression that will be searched in place of searchTerm. The first and last forward slashes, as well as the flags, are stripped from the string. For example, "/Pa(\w+)/ig" will become "Pa(\w+)".

When special characters (ex: backslash) are used in the "userDefinedRegex" field, they need to be properly escaped. For example, for searching words that begins with "Pa", the regular expression will be "Pa(\w+)", this regular expression should be properly escaped like this "Pa(\w+)".

All patterns use the Global (g) flag.

selected boolean <optional>
false

Whether or not this term is selected in the Patterns menu by default. This property must be set to true if you expect to use this search terms along with searchOnInit: true.

redactionReasons

An object defining the redaction reasons to use in the viewer. See the "Using Redaction Reasons" section of this help file for more information.

Type:
  • Object
Properties:
Name Type Attributes Default Description
enableRedactionReasonSelection boolean <optional>
true

When set to false, the reason selection UI will not be enabled.

reasons Array.<Object>

An array of redaction reason objects. Each object will have the following properties:

Properties
Name Type Attributes Default Description
reason string

The reason.

defaultReason boolean <optional>
false

Specifies that this is the default reason. Only one item in the array can be set to true.

autoApplyDefaultReason boolean <optional>
false

When set to true, the viewer will automatically apply the default reason to redactions.

enableFreeformRedactionReasons boolean <optional>
false

When set to true, users may type a redaction reason instead of selecting one from a list.

maxLengthFreeformRedactionReasons number <optional>
false

Sets the maximum length of a typed redaction reason.