new WebViewer(options, element)
Creates a WebViewer instance and embeds it on the HTML page.
Parameters:
Name | Type | Description |
---|---|---|
options |
PDFTron.WebViewer#Options | Options passed to the specific WebViewer. |
element |
DOMElement | The html element that will contain the web viewer (e.g. the element that will be parent of the WebViewer). This can be obtained through document.getElementById() or similar functions. |
Returns:
The instance of the WebViewer class.
- Type
- PDFTron.WebViewer
Example
var viewerElement = document.getElementById('viewer'); var viewer = new PDFTron.WebViewer({ path: 'path/to/lib', l: 'YOUR_LICENSE_KEY', initialDoc : 'path/to/doc.pdf' }, viewerElement);
Classes
Members
-
FitMode
-
Contains all posible modes for fitting/zooming pages to the viewer. The behavior may vary depending on the LayoutMode.
Properties:
Name Type Description FitPage
string A fit mode where the zoom level is fixed to the width or height of the page, whichever is smaller.
FitWidth
string A fit mode where the zoom level is fixed to the width of the page.
Zoom
string A fit mode where the zoom level is not fixed.
-
LayoutMode
-
Contains string enums for all layouts for WebViewer. They are used to dictate how pages are placed within the viewer. Used by setLayoutMode and getLayoutMode.
Properties:
Name Type Description Continuous
string All pages are visible in one column.
FacingCoverContinuous
string All pages visible, with an even numbered page rendered first. (i.e. The first page of the document is rendered by itself on the right side of the viewer to simulate a book cover.)
Facing
string Up to two pages will be visible.
FacingContinuous
string All pages visible in two columns.
FacingCover
string All pages visible in two columns, with an even numbered page rendered first. (i.e. The first page of the document is rendered by itself on the right side of the viewer to simulate a book cover.)
Single
string Only the current page will be visible.
-
Options
-
Options object for WebViewer on creation. Used when constructing a new PDFTron.WebViewer instance.
Properties:
Name Type Argument Default Description initialDoc
string The URL path to a xod document to load on startup.
annotationAdmin
boolean <optional>
A boolean indicating this user has permission to modify all annotations, even if the annotationUser and author does not match.
annotationUser
string <optional>
A user identifier for annotations. All annotations created will have this as the author. It is used for permission checking: user only permitted to modify annotations where annotationUser and author matches.
assetPath
string <optional>
An alternate path to JavaScript and CSS files. Can be located on another domain.
autoCreate
boolean <optional>
true A boolean to control whether the viewer should be created after instantiating a new PDFTron.WebViewer. When set to false, invoke the create() method explicity.
azureWorkaround
boolean <optional>
false Whether or not to workaround the issue of Azure not accepting range requests of a certain type. Enabling the workaround will add an extra HTTP request of overhead but will still allow documents to be loaded from other locations.
backendType
string <optional>
Override the automatically selected backend type when viewing PDF documents directly. Defaults to 'auto' but can be set to 'pnacl' (Chrome only) or 'ems' to use those backends.
backgroundColor
string <optional>
A string to set the background color of the inner page to (desktop only).
css
string <optional>
A URL path to a custom CSS file that holds style customizations.
config
string <optional>
A URL path to a JavaScript configuration file that holds UI customizations.
custom
string <optional>
A string of custom data that can be retrieved by the ReaderControl. In a config file you can access using window.ControlUtils.getCustomData().
documentId
string <optional>
An identifier for the document to be used with annotations. (required for full annotation support).
documentType
string <optional>
The type of document the viewer will be used with. Valid values are "xod", "pdf", "office" and "all". When loading images directly the "pdf" type should be used. If you will be loading both office and pdf in the same session then use "all". (default is "xod").
enableAnnotations
boolean <optional>
true A boolean to enable annotations.
disabledElements
array <optional>
An array containing elements that will be disabled by default.
enableOfflineMode
boolean <optional>
false A boolean to enable offline mode. By default this will add buttons to the UI to allow for saving the document to an offline database. (XOD only)
enableReadOnlyMode
boolean <optional>
false A boolean to enable annotations read-only mode.
enableRedaction
boolean <optional>
false A boolean to enable redaction tools (creating and applying)
enableMeasurement
boolean <optional>
false A boolean to enable measurement tools
encryption
object <optional>
An object containing encryption properties. Expects the object to have type: "aes" and p: "your_document_password" (XOD only).
externalPath
string <optional>
The path to a xod document folder generated using the external parts option.
hideAnnotationPanel
boolean <optional>
false Whether to hide the annotation panel or not.
html5MobileOptions
Options <optional>
An Options object that overrides the existing options when the Mobile viewer is loaded.
html5MobilePath
string <optional>
html5/MobileReaderControl.html An alternative path to the Mobile WebViewer, relative to the "path" option.
html5Options
Options <optional>
An Options object that overrides the existing options when the viewer is loaded.
html5Path
string <optional>
html5/ReaderControl.html An alternative path to the WebViewer, relative to the "path" option.
l
string <optional>
The license key for viewing PDF or Office files (PDF/Office only).
mobileRedirect
boolean <optional>
true A boolean indicating whether the mobile viewer should redirect to a new window or not. By default this is true because mobile browsers have had issues with iframes in the past. (mobile only).
path
string <optional>
An alternative path to the WebViewer root folder.
pdfBackend
string <optional>
A string to control PDF engine ["auto", "ems", "pnacl"] (PDF/Office only, default "auto" chooses the best option availible)
fullAPI
boolean <optional>
false A boolean to enable the use of PDFNet.js library functions (PDF only).
preloadPDFWorker
boolean <optional>
true A boolean to enable the preloading of the PDF worker files (PDF only).
pdftronServer
string <optional>
A URL to the WebViewer server drop-in backend https://www.pdftron.com/documentation/web/guides/deployment-options/webviewer-server
showLocalFilePicker
boolean <optional>
false A boolean to show/hide the local file picker (PDF/Office only).
showPageHistoryButtons
boolean <optional>
true A boolean to show/hide the page history buttons.
showToolbarControl
boolean <optional>
A boolean to show/hide the default toolbar control.
startOffline
boolean <optional>
false Whether to start loading the document in offline mode or not. This can be set to true if the document had previously been saved to an offline database using WebViewer APIs. You'll need to use this option to load from a completely offline state.
streaming
boolean <optional>
false A boolean indicating whether to use http or streaming PartRetriever, it is recommended to keep streaming false for better performance.
subzero
boolean <optional>
Enable or disable using PNaCl subzero compiler. With subzero enabled the first load and execution is significantly faster at the expense of slightly slower execution (about 10%) for subsequent usage. Note that subzero is only consistently available on Chrome 51 or above so this flag will be ignored on earlier Chrome versions. (PDF only, default true)
type
string <optional>
html5,html5Mobile The type of WebViewer to load. Values must be comma-separated in order of preferred WebViewer (possibe values: html5, html5Mobile).
useDownloader
boolean <optional>
true Enable or disable using Downloader on urls (PDF only).
workerTransportPromise
boolean <optional>
An object with keys 'pdf' and/or 'office' that are promises that will resolve to a PDF or Office worker, used if you already create a worker on the outer page and want to share it with the viewer. (PDF/Office only)
xdomainProxyUrl
string <optional>
A URL to the proxy HTML file on the remote server when using the xdomain CORS workaround. Can also be an object to specify multiple URLs.
ui
string <optional>
Enables old viewer if set to 'legacy'.
-
ToolMode
-
Contains string enums for all default tools for WebViewer. They range from panning, text selection to annotation creation. Used by setToolMode and getToolMode.
Properties:
Name Type Description AnnotationCreateArrow
string Draw an arrow.
AnnotationCreateCallout
string Draw a callout text box.
AnnotationCreateEllipse
string Draw an ellipse.
AnnotationCreateFreeHand
string Draw a freehand line.
AnnotationCreateFreeText
string Draw a text box.
AnnotationCreateLine
string Draw a straight line.
AnnotationCreatePolygon
string Draw a polygon.
AnnotationCreatePolygonCloud
string Draw a cloud.
AnnotationCreatePolyline
string Draw a series of connected straight lines.
AnnotationCreateRectangle
string Draw a rectangle.
AnnotationCreateSignature
string Add a signature.
AnnotationCreateStamp
string Add an image.
AnnotationCreateSticky
string Add a sticky note.
AnnotationCreateTextHighlight
string Highlight texts.
AnnotationCreateTextSquiggly
string Undeline texts squiggly.
AnnotationCreateTextStrikeout
string Strike out texts.
AnnotationCreateTextUnderline
string Undeline texts.
AnnotationEdit
string Select/edit annotations (default).
Methods
-
downloadXodDocument()
-
Opens the XOD document through the browser to be downloaded.
- Since:
-
- Version 1.7
-
endPrintJob()
-
Cleans up the resources that were used for printing. (Desktop only)
-
fitHeight()
-
Controls if the document's Zoom property will be adjusted so that the height of the current page or panel will exactly fit into the available space. Not supported for mobile viewer.
- Deprecated:
-
- Since version 1.7. Use setFitMode instead.
-
fitPage()
-
Controls if the document's Zoom property will be adjusted so that the width and height of the current page or panel will fit into the available space. Not supported for mobile viewer.
- Deprecated:
-
- Since version 1.7. Use setFitMode instead.
-
fitWidth()
-
Controls if the document's Zoom property will be adjusted so that the width of the current page or panel will exactly fit into the available space. Not supported for mobile viewer.
- Deprecated:
-
- Since version 1.7. Use setFitMode instead.
-
getCurrentPageNumber()
-
Gets the current page number of the document loaded in the WebViewer.
Returns:
The current page number of the document.
- Type
- number
-
getFitMode()
-
Gets the current fit mode of the viewer.
- Since:
-
- Version 1.7
Returns:
The current fit mode of the viewer.
- Type
- PDFTron.WebViewer.FitMode
-
getInstance()
-
Gets the instance of the ReaderControl object loaded by WebViewer.
Returns:
A ReaderControl instance.
- Type
- CoreControls.ReaderControl
-
getLayoutMode()
-
Gets the layout mode of the document in the WebViewer. Not supported for mobile viewer.
Returns:
The layout mode of the document.
-
getPageCount()
-
Gets the total number of pages of the loaded document.
Returns:
The total number of pages of the loaded document.
- Type
- number
-
getShowSideWindow()
-
Gets the value whether the side window is visible or not. Not supported for mobile viewer.
- Deprecated:
-
- Since version 1.7. Replaced by getSideWindowVisibility.
Returns:
true
if the side window is shown.- Type
- boolean
-
getSideWindowVisibility()
-
Gets the visibility of the default side window. Not supported for mobile viewer.
Returns:
true
if the side window is visible.- Type
- boolean
-
getToolbarVisibility()
-
Gets the visibilty of the default toolbar control.
Returns:
true
if the toolbar is visible.- Type
- boolean
-
getToolMode()
-
Gets the current tool mode of the WebViewer.
Returns:
The current tool mode of the WebViewer.
- Type
- PDFTron.WebViewer.ToolMode
-
getViewerType()
-
Gets the currently loaded viewer type. This is only valid after the documentLoaded event.
Returns:
The viewer type: "html5" or "html5Mobile".
- Type
- string
-
getZoomLevel()
-
Gets the zoom level of the document.
Returns:
The zoom level of the document.
- Type
- number
-
goToFirstPage()
-
Goes to the first page of the document. Makes the document viewer display the first page of the document.
-
goToLastPage()
-
Goes to the last page of the document. Makes the document viewer display the last page of the document.
-
goToNextPage()
-
Goes to the next page of the document. Makes the document viewer display the next page of the document.
-
goToPrevPage()
-
Goes to the previous page of the document. Makes the document viewer display the previous page of the document.
-
isMobileDevice()
-
Detects if the current browser is on a mobile device.
Returns:
true
if this page is loaded on a mobile device.- Type
- boolean
-
isSameOrigin(url)
-
Detects if the give url string is in the same origin as the current page
Parameters:
Name Type Description url
type The URL to test against
Returns:
true
if the provided URL is in the same origin as the current page- Type
- boolean
-
loadDocument(url, loadOptions)
-
Loads a document to the WebViewer.
Parameters:
Name Type Description url
string The URL of the document to be loaded.
loadOptions
object Options for loading a new document.
Properties
Name Type Description documentId
A unique identifer for the document. When an annotation server is specified, this ID will be sent to the server.
filename
The filename of the document.
customHeaders
An object custom HTTP headers to use when retrieving the document from the specified url. For example: {'Authorization' : 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='}
-
rotateClockwise()
-
Rotates the document in the WebViewer clockwise. Not supported for mobile viewer.
-
rotateCounterClockwise()
-
Rotates the document in the WebViewer counter-clockwise. Not supported for mobile viewer.
-
runInIframe(func)
-
Runs the specified function, passing in the iframe window object.
Parameters:
Name Type Description func
function The function to run. The function will be passed the iframe window, readerControl (aka WebViewer instance) and jQuery of the iframe window as parameters.
-
searchText(pattern, searchMode)
-
Searches the loaded document finding for the matching pattern. Search mode includes:
- None
- CaseSensitive
- WholeWord
- SearchUp
- PageStop
- ProvideQuads
- AmbientString
Parameters:
Name Type Description pattern
string The pattern to look for.
searchMode
string Must one or a combination of the above search modes. To combine search modes, simply pass them as comma separated values in one string. i.e. "CaseSensitive,WholeWord"
-
setAdminUser(isAdminUser)
-
Sets the administrative permissions for the current annotation user.
Parameters:
Name Type Description isAdminUser
boolean true
if admin. -
setAnnotationUser(username)
-
Sets the annotation author.
Parameters:
Name Type Description username
string Author of the annotation.
-
setCurrentPageNumber(pageNumber)
-
Sets the current page number of the document loaded in the WebViewer.
Parameters:
Name Type Description pageNumber
number The page number of the document to set.
-
setFitMode(fitMode)
-
Sets the fit mode of the viewer. This is equivalent to calling the methods: fitWidth, fitHeight, fitPage, zoom.
Parameters:
Name Type Description fitMode
PDFTron.WebViewer.FitMode The fit mode to set.
- Since:
-
- Version 1.7
-
setLayoutMode(layoutMode)
-
Sets the layout mode of the document in the WebViewer. Not supported for mobile viewer.
Parameters:
Name Type Description layoutMode
PDFTron.WebViewer#LayoutMode The layout mode to set.
-
setReadOnly(isReadOnly)
-
Sets the viewer's annotation read-only state. When read-only, users will be allowed to view annotations and its popup text contents, but will not be able to edit or create new annotations.
Parameters:
Name Type Description isReadOnly
boolean true
if setting it read-only. -
setShowSideWindow(value)
-
Sets the value whether the side window is visible or not. Not supported for mobile viewer.
Parameters:
Name Type Description value
boolean pass
true
to show the side window.- Deprecated:
-
- Since version 1.7. Replaced by setShowSideWindow.
-
setSideWindowVisibility(value)
-
Gets the visibility of the default side window. Not supported for mobile viewer.
Parameters:
Name Type Description value
boolean true
to show the side window. -
setToolbarVisibility(isVisible)
-
Sets the visibilty of the default toolbar control.
Parameters:
Name Type Description isVisible
boolean true
if the toolbar is visible. -
setToolMode(toolMode)
-
Sets the tool mode of the WebViewer.
Parameters:
Name Type Description toolMode
PDFTron.WebViewer.ToolMode Must be one of the ToolMode.
-
setZoomLevel(zoomLevel)
-
Sets the zoom level of the document.
Parameters:
Name Type Description zoomLevel
number The new zoom level to set.
-
startPrintJob(pages)
-
Starts a printing job for the passed in pages. (Desktop only)
Parameters:
Name Type Description pages
string The pages that should be printed. Multiple pages can be separated by commas and ranges can be specified by a dash (e.g. 1,3-5).
-
zoom()
-
Controls if the document's Zoom property will be freely adjusted and not constrained with the width and height of the current page or panel. Not supported for mobile viewer.
- Deprecated:
-
- Since version 1.7. Use setFitMode instead.
Events
-
documentLoaded
-
An event bound on the element, triggered when a document has been loaded in the viewer.
- Since:
-
- Version 4.0
Example
viewerElement.addEventListener('documentLoaded', function(e) { console.log('document loaded', myWebViewer.getInstance()); });
-
fitModeChanged
-
An event bound on the element, triggered when the tool mode has changed.
- Since:
-
- Version 4.0
Example
viewerElement.addEventListener('fitModeChanged', function(e) { const [ fitMode ] = e.detail; const { Zoom, FitWidth, FitPage } = viewerElement.getInstance().docViewer.FitMode; console.log(fitMode === FitPage); });
-
layoutModeChanged
-
An event bound on the element, triggered when the layout mode has changed.
- Since:
-
- Version 4.0
Example
viewerElement.addEventListener('layoutModeChanged', function(e) { const [ layoutMode ] = e.detail; console.log(layoutMode); });
-
pageChanged
-
An event bound on the element, triggered when the page number has changed.
- Since:
-
- Version 4.0
Example
viewerElement.addEventListener('pageChanged', function(e) { const [ pageNumber ] = e.detail; console.log(pageNumber); });
-
ready
-
An event bound on the element, triggered when the viewer is ready, before a document is loaded.
- Since:
-
- Version 4.0
Example
viewerElement.addEventListener('ready', function(e) { console.log('viewer ready', myWebViewer.getInstance()); });
-
toolModeChanged
-
An event bound on the element, triggered when the tool mode has changed.
- Since:
-
- Version 4.0
Example
viewerElement.addEventListener('toolModeChanged', function(e) { const [ newTool, oldTool ] = e.detail; console.log(newTool, oldTool); });
-
zoomChanged
-
An event bound on the element, triggered when the zoom level has changed.
- Since:
-
- Version 4.0
Example
viewerElement.addEventListener('zoomChanged', function(e) { const [ zoom ] = e.detail; console.log(zoom); });