Namespace: PSPDFKit

PSPDFKit

The main PSPDFKit namespace is exported in the global PSPDFKit.

Classes

Namespaces

Members

Methods

Type Definitions



Members

(static, readonly) AutoSaveMode

When working with annotations and form field values, there are multiple options when the data can get saved. The AutoSaveMode controls this behavior.

Properties:
Name Type Description
IMMEDIATE PSPDFKit.AutoSaveMode

Saves immediately whenever an attribute of the annotation changed, or whenever a form field value got updated.
INTELLIGENT PSPDFKit.AutoSaveMode

Saves annotations automatically, when the user finishes editing an annotation. For form fields, this behaves like PSPDFKit.AutoSaveMode.IMMEDIATE.
DISABLED PSPDFKit.AutoSaveMode

Never saves annotations or form field values automatically. Annotations and form field values can still be saved via PSPDFKit.Instance#saveAnnotations or PSPDFKit.Instance#saveFormFieldValues

(static, readonly) defaultAnnotationPresets: Object.<PSPDFKit.AnnotationPreset>

Returns a deep copy of an object containing the default annotation presets. Used by toolbar buttons like arrow.

  1. arrow
  2. highlighter
  3. line
  4. rectangle
  5. ellipse
  6. polygon
  7. polyline
  8. ink
  9. note
  10. text
  11. stamp
  12. image
  13. widget
  14. strikeout
  15. underline
  16. squiggle
  17. highlight
Type:

(static, readonly) defaultStampAnnotationTemplates: Array.<(PSPDFKit.Annotations.StampAnnotation|PSPDFKit.Annotations.ImageAnnotation)>

Returns a deep copy of an array containing the default stamp and image annotation templates, which are stamp annotation instances. However, image annotation templates can also be added to this Array using PSPDFKit.setStampAnnotationTemplates. Used by the stamp picker UI. Initially it contains only the following stamp annotations:

  1. Approved
  2. NotApproved
  3. Draft
  4. Final
  5. Completed
  6. Confidential
  7. ForPublicRelease
  8. NotForPublicRelease
  9. ForComment
  10. Void
  11. PreliminaryResults
  12. InformationOnly
  13. Rejected
  14. Accepted
  15. InitialHere
  16. SignHere
  17. Witness
  18. AsIs
  19. Departmental
  20. Experimental
  21. Expired
  22. Sold
  23. TopSecret
  24. Revised
Type:

(static, readonly) defaultToolbarItems: Array.<PSPDFKit.ToolbarItem>

Returns a deep copy of an array containing the default toolbar items ordered by PSPDFKit.ToolbarItem#type in the following way:

  1. sidebar-thumbnails
  2. sidebar-document-outline
  3. sidebar-annotations
  4. sidebar-bookmarks
  5. pager
  6. pan
  7. zoom-out
  8. zoom-in
  9. zoom-mode
  10. spacer
  11. annotate
  12. ink
  13. highlighter
  14. ink-signature
  15. image
  16. stamp
  17. note
  18. text
  19. line
  20. arrow
  21. rectangle
  22. ellipse
  23. polygon
  24. polyline
  25. print
  26. search
  27. debug

Please keep in mind that under some circumstances some items may be removed from the final list.

Items hidden for touch devices:

  • pan

Items hidden for touch devices when the media query (max-width: 992px) for medium devices matches:

  • zoom-out
  • zoom-in
  • zoom-mode

Please keep in mind that the media query is only added for touch devices. You can change this behavior by defining your own mediaQueries and replacing the original item. To learn more about how to do so please refer to our guide.

Items hidden for small screens (max-width: 992px)

  • text
  • ink
  • highlighter
  • line
  • arrow
  • rectangle
  • ellipse
  • polygon
  • polyline
  • ink-signature
  • image
  • stamp
  • note

Items shown on small screens (max-width: 992px)

  • annotate

Items hidden when in read-only mode:

  • text
  • ink
  • highlighter
  • line
  • arrow
  • rectangle
  • ellipse
  • polygon
  • polyline
  • ink-signature
  • image
  • stamp
  • note

Hidden when not in debug mode:

  • debug

Hidden by default and only available when explicitly set via the API:

  • layout-config
Type:

(static, readonly) InteractionMode

Controls the current interaction mode in the viewer.

Properties:
Name Type Description
INK PSPDFKit.InteractionMode

When this mode is activated, the creation of new ink annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
INK_SIGNATURE PSPDFKit.InteractionMode

When this mode is activated, the creation of new ink signatures will be enabled. This this shows a dialog where it is possible to select an existing ink signature or create a new one and store it.
STAMP_PICKER PSPDFKit.InteractionMode

When this mode is activated, the stamp annotation templates picker modal UI will be shown. Once a template is selected, the new annotation is configured and created\ in the document.
STAMP_CUSTOM PSPDFKit.InteractionMode

When this mode is activated, the custom stamp annotation template editor modal UI will be shown. Once a the custom template is edited, the new custom stamp annotation will be created in the document.
SHAPE_LINE PSPDFKit.InteractionMode

When this mode is activated, the creation of new line annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it.
SHAPE_RECTANGLE PSPDFKit.InteractionMode

When this mode is activated, the creation of new rectangle annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it.
SHAPE_ELLIPSE PSPDFKit.InteractionMode

When this mode is activated, the creation of new ellipse annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
SHAPE_POLYGON PSPDFKit.InteractionMode

When this mode is activated, the creation of new polygon annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
SHAPE_POLYLINE PSPDFKit.InteractionMode

When this mode is activated, the creation of new polyline annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
NOTE PSPDFKit.InteractionMode

When this mode is activated, the creation of new note annotations will be enabled. This transforms the page to a clickable area where the annotation will be created at the position of the click.
TEXT PSPDFKit.InteractionMode

When this mode is activated, the creation of new text annotations will be enabled. This transforms the page to a clickable area where the annotation will be created at the position of the click.
PAN PSPDFKit.InteractionMode

This enables the pan tool to allow the user to navigate on a desktop browser using mouse dragging. This will disable text selection.

On a touch device, this will have no effect since panning is already the default technique for scrolling on websites.
SEARCH PSPDFKit.InteractionMode

Enables the search mode and focuses the search input field.

(static, readonly) LayoutMode

Describes how the pages will be laid out in the document view.

Properties:
Name Type Description
SINGLE PSPDFKit.LayoutMode

Pages will always be displayed in the single page mode.

This is the default mode.
DOUBLE PSPDFKit.LayoutMode

Pages will always be displayed in groups of two.
AUTO PSPDFKit.LayoutMode

Automatically sets the layout mode to PSPDFKit.LayoutMode.SINGLE or PSPDFKit.LayoutMode.DOUBLE depending on the available space.

Specifically PSPDFKit.LayoutMode.DOUBLE is chosen when the PSPDFKit container is in landscape mode and its size is greater than 992px.

This mode is a perfect fit for tablets in particular since it will automatically update the layout mode then device orientation changes.

When the dimensions of the viewport change (i.e. the browser window is resized), the view will be restored to make the current page visible.

(static, readonly) NoteIcon

Available icons for Note Annotations.

Properties:
Name Type Description
COMMENT
RIGHT_POINTER
RIGHT_ARROW
CHECK
CIRCLE
CROSS
INSERT
NEW_PARAGRAPH
NOTE
PARAGRAPH
HELP
STAR
KEY

(static, readonly) PrintMode

Describes mode used to print a PDF document.

Properties:
Name Type Description
DOM PSPDFKit.PrintMode

This method will render all pages of the PDF document in advance before it sends the results to the printer. This works in all major browsers and will not give your users access to the source PDF file. However, this method is CPU-bound and memory usage scales with PDF size.

Because of its reliability and cross browsers support this method is the default.

Some caveats when using this method:

  • To achieve cross-browser support, we render the resulting images into the main window. We try to hide already existing HTML by applying display: none !important. If the printed page still contains other HTML elements, make sure to apply an appropriate print stylesheet to your web app.
  • This method will produce incorrect results, when pages of the document have different sizes. Unfortunately, there's no way to work around this issue since it's a CSS limitation.
EXPORT_PDF PSPDFKit.PrintMode

This method is built to be resource efficient and to avoid having to render all pages in advance, which might balloon memory usage to multi-GB on PDFs with 100+ pages.

It supports all common browsers, however some fall back to opening the PDF file in a new tab, which might give your users unwanted access to the source files.

Google Chrome and Microsoft Internet Explorer provide the APIs required to use the native renderer, as a fallback on other browser we generate and open a PDF in a new tab. This allows users to print the PDF in a native PDF reader which can, as opposed to browser-built implementations, talk directly to the connected printer.

When using this print mode, we can not call the PSPDFKit.RenderPageCallback when printing pages.

Note: If the PDF is password-protected, we always fall back to opening the PDF in a new tab.

(static, readonly) ScrollMode

Describes mode of page scrolling in the document view - either continuous or per spread (paginated).

Properties:
Name Type Description
CONTINUOUS PSPDFKit.ScrollMode

Render all pages as a list and allow smooth scrolling.

This is the default mode.
PER_SPREAD PSPDFKit.ScrollMode

Makes scrolling only possible within a spread. Whenever this mode is activated, or pages are changed when this mode is active, the zoom mode will be reset to PSPDFKit.ZoomMode.FIT_TO_VIEWPORT.

(static, readonly) SidebarMode

Controls the current sidebar mode in the viewer.

Properties:
Name Type Description
ANNOTATIONS PSPDFKit.SidebarMode

Annotations sidebar.
BOOKMARKS PSPDFKit.SidebarMode

Bookmarks.
DOCUMENT_OUTLINE PSPDFKit.SidebarMode

Document Outline (table of contents).
THUMBNAILS PSPDFKit.SidebarMode

Thumbnails preview.

(static, readonly) version

Returns the framework version (e.g. "2018.6.0").

(static, readonly) ZoomMode

A specific zoom mode that will always be applied whenever the viewport is resized.

Properties:
Name Type Description
AUTO PSPDFKit.ZoomMode

Generates a zoomLevel that will automatically align the page for the best viewing experience.
FIT_TO_WIDTH PSPDFKit.ZoomMode

Uses a zoomLevel that will fit the width of the broadest page into the viewport. The height might overflow.
FIT_TO_VIEWPORT PSPDFKit.ZoomMode

Uses a zoomLevel that will fit the current page into the viewport completely.

Methods

(static) load(configuration) → {Promise.<PSPDFKit.Instance, PSPDFKit.Error>}

Creates a new PSPDFKit instance.

Returns a Promise resolving to a new PSPDFKit.Instance, or rejecting with a PSPDFKit.Error.

It requires a configuration object. When the configuration is invalid, the promise will be rejected with a PSPDFKit.Error.

Parameters:
Name Type Description
configuration PSPDFKit.Configuration

A configuration Object
Returns:

Promise that resolves in an PSPDFKit.Instance

Type
Promise.<PSPDFKit.Instance, PSPDFKit.Error>
Examples

Load PSPDFKit for Web Server

PSPDFKit.load({
  authPayload: { jwt: "xxx.xxx.xxx" },
  container: ".foo",
  documentId: "85203",
  instant: true,
}).then((instance) => {
  console.log("Successfully mounted PSPDFKit", instance);
}).catch((error) => {
  console.error(error.message);
})

Load PSPDFKit for Web Standalone

PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
  licenseKey: "YOUR_LICENSE_KEY",
}).then((instance) => {
  console.log("Successfully mounted PSPDFKit", instance);
}).catch((error) => {
  console.error(error.message);
})

(static) unload(target) → {boolean}

Unloads an existing PSPDFKit instance.

It requires an target parameter that is a CSS selector, an HTMLElement or the reference to a PSPDFKit.Instance returned by PSPDFKit.load.

Parameters:
Name Type Description
target HTMLElement | string | PSPDFKit.Instance

A target to unload
Throws:

Will throw an error when the target is invalid but will work when it does not have a mounted PSPDFKit for Web instance.

Type
PSPDFKit.Error
Returns:

When true, an instance of PSPDFKit for Web was unmounted.

Type
boolean
Examples

Unload PSPDFKit for Web using an instance

let instance = null;
PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
}).then((i) => {
  instance = i
})
.then(() => {
  // Unload the given instance
  PSPDFKit.unload(instance)
}).catch((error) => {
  console.error(error.message);
})

Unload PSPDFKit for Web using a CSS selector

PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
})
.then(() => {
  // Unload the given instance
  PSPDFKit.unload(".foo")
})

Unload PSPDFKit for Web using an HTMLElement

PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
})
.then(() => {
  // Unload the given instance
  PSPDFKit.unload(document.querySelector(".foo"))
})

(static) viewStateFromOpenParameters() → {PSPDFKit.ViewState}

Merges the properties extracted from the location.hash into the PSPDFKit.ViewState.

Properties will be extracted following the PDF Open Parameters spec.

Currently, we only support the page parameter.

Parameters:
Type Description
PSPDFKit.ViewState
Returns:
Type
PSPDFKit.ViewState

Type Definitions

RenderPageCallback(canvas, pageIndex, size)

This callback is called whenever a page is rendered or printed (only for PSPDFKit.PrintMode.DOM). You can use it to render watermarks on the page.

Make sure that the rendering commands are as efficient as possible as they might be invoked multiple times per page (once per tile).

For more information, see PSPDFKit.Configuration#renderPageCallback.

Parameters:
Name Type Description
canvas CanvasRenderingContext2D

A 2D <canvas/> rendering context.
pageIndex number

The current page index, starting with 0 for the first page.
size PSPDFKit.Geometry.Size

The size of the page that you're drawing at. The canvas is already scaled accordingly.
Example

Register a RenderPageCallback handler at configuration time.

PSPDFKit.load({
  renderPageCallback: function(ctx, pageIndex, pageSize) {
    ctx.beginPath();
    ctx.moveTo(0, 0);
    ctx.lineTo(pageSize.width, pageSize.height);
    ctx.stroke();

    ctx.font = "30px Comic Sans MS";
    ctx.fillStyle = "red";
    ctx.textAlign = "center";
    ctx.fillText(
      `This is page ${pageIndex + 1}`,
      pageSize.width / 2,
      pageSize.height / 2
    );
  }
  // ...
});