PrizmDoc® v14.1 Release - Updated
PrizmDoc / API Reference / Viewer Control / External: jQuery / Namespace: fn
In This Topic
    Namespace: fn
    In This Topic

    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.

    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
    });
    
    

    Parameters:

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

    Plugin options.

    Returns:

    Type
    PCCViewer.Viewer

    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 Attributes 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>
    Default: "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>
    Default: "../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>
    Default: "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".

    attachmentViewingMode : string <optional>
    Default: "NewWindow"

    The "attachmentViewingMode" specifies the mode in which the attachments will be opened in the viewer. The following options are available:

    • "NewWindow": (default) The attachment will be opened in the new browser window or tab with query parameter "?viewingSessionId={{ATTACHMENT_VIEWINGSESSIONID}}".
    • "ThisViewer": The document being viewed will change (along with its associated annotations). If your client-side code needs to account for this change, you can subscribe to the PCCViewer.EventType.ViewingSessionChanged event to know when this happens.
    autoLoadAnnotation : boolean <optional>
    Default: 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>
    Default: 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>
    Default: 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 correspond to a fileNameTemplate.html file.

    The print template must be a string containing a full HTML page with variables parsed using curly brackets. For all of the other templates, the string type is deprecated since v13.22. Use a templateFunction instead.

    Variables and JavaScript conditions can be used within the templates using ERB syntax. For more information, see the Underscore documentation at http://underscorejs.org/#template.

    As of v13.22, the viewer build compiles the HTML templates and outputs each as a function in the template property of the viewerCustomizations.js file, and the Viewer template option can be set to the value of that template property. The viewer build requires that all properties in the HTML templates are accessed via a data object (for example, data.myProperty instead of myProperty).

    Properties
    • viewer : string | external:jQuery.fn~templateFunction

      This is the main viewer template. The string type is deprecated since v13.22 (use a function instead, as described above).

    • contextMenu : string | external:jQuery.fn~templateFunction

      This is the template for the floating menu used to edit annotations. The string type is deprecated since v13.22 (use a function instead, as described above).

    • overwriteOverlay : string | external:jQuery.fn~templateFunction

      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. The string type is deprecated since v13.22 (use a function instead, as described above).

    • unsavedChangesOverlay : string | external:jQuery.fn~templateFunction

      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. The string type is deprecated since v13.22 (use a function instead, as described above).

    • printOverlay : string | external:jQuery.fn~templateFunction

      This is the template used for the overlay menu displayed when the user selects to print the document. The string type is deprecated since v13.22 (use a function instead, as described above).

    • 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 | external:jQuery.fn~templateFunction

      This is the template used for the overlay menu displayed when the user selects to download the document. The string type is deprecated since v13.22 (use a function instead, as described above).

    • esignOverlay : string | external:jQuery.fn~templateFunction

      This is the template used for the overlay menu displayed when the user selects to manage e-signatures. The string type is deprecated since v13.22 (use a function instead, as described above).

    • comment : string | external:jQuery.fn~templateFunction

      This is the template for comments displayed in the ViewerControl comments panel. The string type is deprecated since v13.22 (use a function instead, as described above).

    • copyOverlay : string | external:jQuery.fn~templateFunction

      This is the template used for the clipboard overlay when a user attempts to copy document text using a touch device. The string type is deprecated since v13.22 (use a function instead, as described above).

    • hyperlinkMenu : string | external:jQuery.fn~templateFunction

      This is the template used to render the menu that appears when a user creates or views a hyperlink annotation. The string type is deprecated since v13.22 (use a function instead, as described above).

    • imageStampOverlay : string | external:jQuery.fn~templateFunction

      This is the template used for the image stamp picker for the image stamp annotations and redactions. The string type is deprecated since v13.22 (use a function instead, as described above).

    • pageRedactionOverlay : string | external:jQuery.fn~templateFunction

      This is the template used for the full page redaction selection dialog. The string type is deprecated since v13.22 (use a function instead, as described above).

    • redactionReason : string | external:jQuery.fn~templateFunction

      This is the template used to render the menu that appears when a user enters a redaction reason from the immediate menu. The string type is deprecated since v13.22 (use a function instead, as described above).

    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
    • annotateTab : boolean <optional>
      Default: true

      Show or hide the Annotate Tab.

    • redactTab : boolean <optional>
      Default: true

      Show or hide the Redact Tab.

    • searchTab : boolean <optional>
      Default: true

      Show or hide the Search Tab.

    • viewTab : boolean <optional>
      Default: true

      Show or hide the View Tab.

    • esignTab : boolean <optional>
      Default: true

      Show or hide the E-Sign Tab.

    • copyPaste : boolean <optional>
      Default: true

      Show or hide the Text Select Tool.

    • download : boolean <optional>
      Default: true

      Show or hide the Download Button.

    • printing : boolean <optional>
      Default: true

      Show or hide the Print Button.

    • advancedSearch : boolean <optional>
      Default: false

      Enables the advanced search features, including searching through marks and comments. Note that this property provides the ability to search for text in comments, annotations, redactions and signatures (as well as the "Type" column in the search results panel that tells where the text was found). The "Filter" panel that allows to specify where to search - in document, in annotations, etc. And the "Quick actions" button that allows to redact all found items.

    • attachments : boolean <optional>
      Default: true

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

    • fullScreenOnInit : boolean <optional>
      Default: 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>
      Default: "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>
    Default: "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
    • comment : boolean <optional>
      Default: true

      Show or hide the Add Comment Button.

    • select : boolean <optional>
      Default: false

      Show or hide the Select Button.

    • copy : boolean <optional>
      Default: true

      Show or hide the Copy Button.

    • highlight : boolean <optional>
      Default: true

      Show or hide the Highlight Button.

    • redact : boolean <optional>
      Default: true

      Show or hide the Redact Button.

    • hyperlink : boolean <optional>
      Default: true

      Show or hide the Hyperlink Button.

    • cancel : boolean <optional>
      Default: false

      Show or hide the Cancel Button.

    commentsPanelMode : string <optional>
    Default: "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 : string <optional>
    Default: "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>
    Default: "MM/DD/YYYY h:mma"

    Specifies the date format to use to display comment dates.

    signatureDateFormat : external:jQuery.fn~DateFormat <optional>
    Default: "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
    • 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>
      Default: 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>
    Default: 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>
    Default: 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.

    piiDetection : Object <optional>

    Specifies options for PII detection.

    Properties
    • enablePiiDetection : boolean <optional>
      Default: false

      Determines whether the UI for detecting PII in a document is enabled.

    • piiEntitiesPageLength : number <optional>
      Default: 250

      The number of PII entities to show at a time in the PII entities panel. The user can use the PII entities navigation buttons to page through the PII entities. 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 Attributes 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>
    Default: 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.

    Lines of text in the Viewer typically end with a space followed by a \n character, so to include phrases that span multiple lines in your regular expression search results, you will need to provide a regular expression that accounts for words separated by either a space or a space followed by a \n character.

    selected : boolean <optional>
    Default: 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 Attributes Description
    enableRedactionReasonSelection : boolean <optional>
    Default: true

    Determines whether the UI for selecting redaction reasons is enabled. When false, the UI for selecting redaction reasons will not be available.

    reasons : Array.<Object>

    Array of objects defining the redaction reasons which the user may select from. Each item may contain:

    Properties
    • reason : string

      Reason text to apply to the redaction.

    • description : string

      Reason description to show in the reason selection UI.

    • defaultReason : boolean <optional>
      Default: false

      Determines whether this redaction should be selected by default. When enableMultipleRedactionReasons is true, can be set to true for multiple items in the reasons array. When enableMultipleRedactionReasons is false, can only be set to true for one item in the reasons array.

    autoApplyDefaultReason : boolean <optional>
    Default: false

    When true, default reason(s) will automatically be applied to new redactions.

    enableFreeformRedactionReasons : boolean <optional>
    Default: false

    When true, users are given the option to type a freeform redaction reason.

    maxLengthFreeformRedactionReasons : number <optional>
    Default: false

    Maximum length of a typed redaction reason.

    enableMultipleRedactionReasons : boolean <optional>
    Default: false

    Determines whether multiple redaction reasons can be applied to redactions. When false, only a single redaction reason can be applied to a redaction. When true, multiple redaction reasons can be applied to a redaction (requires annotationsMode be set to "LayeredAnnotations").

    templateFunction(data) → {string}

    A function that represents a precompiled HTML template.

    Parameters:

    Name Type Description
    data Object

    An object containing the properties required by the template.

    Returns:

    A string containing HTML elements based on the passed in data.

    Type
    string

    Documentation generated by JSDoc 3.6.10 on Mon Apr 22 2024 21:06:59 GMT+0000 (Coordinated Universal Time)