# Class: Document

## CoreControls. Document

Represents a document with individual pages (canvases) that can be displayed on screen and printed.

#### new Document(id, type)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `id` | string | Unique string id for the document
  `type` | string | The type of document that should be instantiated. Values are 'xod' for XOD documents, 'pdf' for PDF, JPG or PNG documents, 'office' for MS Office documents and 'blackbox' for WebViewer Server documents

  ##### Examples

      // 5.1 and after
      WebViewer(...)
        .then(function(instance) {
          var docViewer = instance.docViewer;
          var doc = docViewer.getDocument();
          // doc.someAPI();
        });

      // 4.0 ~ 5.0
      var viewer = new PDFTron.WebViewer({ ... }, viewerElement);
      viewerElement.addEventListener('ready', function() {
        var instance = viewer.getInstance();
        var docViewer = instance.docViewer;
        var doc = docViewer.getDocument();
        // doc.someAPI();
      });

### Methods

#### <static> registerDocumentType(type, source)

  Register new document type with Document class

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `type` | String | Name of the new document type
  `source` | Class | Class of the new document

  ##### Returns:

  Type
    Boolean

#### <static> unregisterDocumentType(type)

  Unregister existing document type form Document class

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `type` | String | Name of registered document type

  ##### Returns:

  Type
    Boolean

#### cancelLoadCanvas(id)

  Cancels the loadCanvasAsync call corresponding to the passed in id

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `id` | number | The id returned from the loadCanvasAsync call that will be cancelled.

#### cancelLoadThumbnail(requestId)

  Cancels the request made for thumbnail with the specified request Id

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `requestId` | number | The id returned from loadThumbnailAsync

#### cancelOfflineModeDownload()

  Cancels a download for offline mode in progress. If there is no current download then this does nothing.

#### cropPages(pageArray, topMargin, botMargin, leftMargin, rightMargin)

  [PDF Document only] Crop the given pages by the given margins. Note that this method will need to wait for the entire file to be downloaded before the change is applied.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageArray` | Array.<number> | an array of page numbers to crop
  `topMargin` | number | how much to crop from the top
  `botMargin` | number | how much to crop from the bottom
  `leftMargin` | number | how much to crop from the left
  `rightMargin` | number | how much to crop from the right

  ##### Returns:

  a promise that resolves to an object describing the updated state of the pages in the document

  Type
    Promise

#### documentCompletePromise()

  ##### Returns:

  A promise that resolves when all of the page information is available for the document

  Type
    Promise

#### enableColorSeparations(enabled)

  [PDF Document only] Enables or disables the color separations feature for rendering.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `enabled` | boolean | Whether to enable or disable color separations rendering.

#### enableSeparation(name, enabled)

  [PDF Document only] Enables or disables the rendering of a particular color separation.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `name` | string | The name of the separation
  `enabled` | boolean | Whether to enable or disable the separation

#### extractPages(pageArray, xfdfString)

  [PDF Document only] Extract the given pages from the document. Note that this method will need to wait for the entire file to be downloaded before the change is applied.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageArray` | Array.<number> | an array of the page numbers to extract
  `xfdfString` | string | an XFDF string to merge into the document before extracting

  ##### Returns:

  a promise that resolves on completion

  Type
    Promise

#### extractPDFNetLayersContext(layers)

  [PDF Document only][PDFNetJS full only] Get the updated context of a document as a PDFNet object.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `layers` |  | layers

  ##### Returns:

  a promise that resolves to a PDFNet Context object representing the current layers/OCG state.

  Type
    Promise

#### extractXFDF(pages)

  Gets the XFDF data for the document's internal annotations.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pages` | array | An array of page numbers to get the XFDF data for the document. Note: Only one page is supported by XOD documents.

  ##### Returns:

  a promise the resolves to an object with an xfdfString and pages property where pages is the array of including the extracted annotation information.

  Type
    Promise

#### getBookmarks()

  Returns an array containing the bookmarks in the document.

  ##### Returns:

  A promise resolving to an array containing the bookmarks in the current document.

  Type
    Promise.<Array.<CoreControls.Bookmark>>

#### getColorSeparations()

  [PDF Document only] Gets the color separations available on this document.

  ##### Returns:

  The color separations of the document

  Type
    array

#### getDownloadLink( [options])

  [PDFTron Server only] Provides a URL to a the PDF with annotations and watermarks merged.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `options` | Object | <optional> | An optional object containing download options and parameters. ###### Properties
  Name | Type | Argument | Description
  --- | --- | --- | ---
  `filename` | string | <optional> | The preferred name for the downloaded file on the client side. This has no effect on the backend target of the returned link, only the filename used by the browser when the link is accessed.

  ##### Returns:

  Will be null if not supported. Otherwise a promise that resolves to an object with a `url` property pointing to the printable PDF.

  Type
    Promise

#### getFileData( [options])

  [PDF/Office Document only] Asynchronously saves the document and provides the result as an ArrayBuffer. See PDFReaderControl.js for an example of typical usage.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `options` | Object | <optional> | An optional object containing save options and parameters. ###### Properties
  Name | Type | Argument | Description
  --- | --- | --- | ---
  `xfdfString` | string | <optional> | An xfdf string containing annotation data to be used when saving. This will usually be retrieved by calling exportAnnotations on a CoreControls.AnnotationManager object.
  `finishedWithDocument` | boolean | <optional> | A flag specifying that the document data may be discarded by the worker after use. Only use this when completely finished with document processing. When handling larger documents this can be useful to avoid memory exhaustion as only one copy of the document needs to be kept.
  `printDocument` | boolean | <optional> | If true the saved document data will have an open action specifying that it should be printed. This is mostly only used to trigger print actions in the browser's PDF Viewer.
  `downloadType` | string | <optional> | The type to download the file as, by default this is "pdf". PDF and image files can only be downloaded as PDFs, but office files can be downloaded as "pdf" or as "office" if you want to get the original file without annotations.
  `flags` | number | <optional> | The flags with which to save the document. Possible values include CoreControls.SaveOptions.REMOVE_UNUSED (remove unused objects during save) and CoreControls.SaveOptions.LINEARIZED (optimize the document for fast web view and remove unused objects). The default value is CoreControls.SaveOptions.REMOVE_UNUSED.

  ##### Returns:

  a promise that resolves to an array buffer containing PDF document bytes.

  Type
    Promise

#### getLayersArray()

  [PDF Document only] Get an array describing the layers/OCG structure in the document. Each entry in the array is a layer entry the form {obj: string, visible: boolean, name: titleString, children: [layerEntry1, layerEntry2...]}. The children entry contains an array which may contain additional layer entries. Both the obj and visible are optional. See the layers sample for an example of how to use getLayersArray and setLayersArray.

  ##### Returns:

  A promise that resolves to an array representing the layers in the PDF document

#### getLinks(pageIndex)

  Returns an array containing the links on the specified page of the document.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, that the links are on.

  ##### Returns:

  An array containing the links on the specified page of the document.

  Type
    array

#### getMetadata()

  Returns an object with metadata associated with the document.

  ##### Returns:

  An object with document metadata

  Type
    object

#### getOfflineModeEnabled()

  Returns whether offline mode is currently enabled or not.

#### getPageCount()

  Returns the number of pages in a document.

  ##### Returns:

  The number of the pages in the current document.

  Type
    number

#### getPageInfo(pageIndex)

  Returns an object containing the width and height of a page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, of the requested page.

  ##### Returns:

  An object representing the page info. Contains the properties "width" and "height".

  Type
    object

#### getPageMatrix(pageIndex)

  Returns an object representing the transformation matrix for the page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, of the requested page.

  ##### Returns:

  An object representing the page matrix.

  Type
    object

#### getPDFCoordinates(pageIndex, x, y)

  Returns an object with the original x and y coordinates converted to PDF coordinates for the page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, that the coordinates are on
  `x` | number | The x coordinate
  `y` | number | The y coordinate

  ##### Returns:

  An object with the x and y PDF coordinates

  Type
    object

#### getPDFDoc()

  Returns the PDFNet.PDFDoc object associated with the document. Note that the full API is required to be enabled and WebViewer Server cannot be enabled.

  ##### Returns:

  A promise that resolves to the PDFDoc object.

  Type
    Promise.<PDFNet.PDFDoc>

#### getTextPosition(pageIndex, textStartIndex, textEndIndex, onComplete(quads))

  Gets quads for each of the characters from start to end index.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, that the text is on.
  `textStartIndex` | number | The position where to start getting character quads from.
  `textEndIndex` | number | The position (up to, but not including) where to finish getting characters.
  `onComplete(quads)` | function | The callback to call when the text positions are ready. quads is an array of objects with (x1,y1,x2,y2,x3,y3,x4,y4)

#### getType()

  Gets the type of the document.

  ##### Returns:

  The type of the document (xod, pdf, office, blackbox)

  Type
    string

#### getViewerCoordinates(pageIndex, x, y)

  Returns an object with the original x and y PDF coordinates converted to Viewer coordinates for the page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, that the coordinates are on
  `x` | number | The x coordinate
  `y` | number | The y coordinate

  ##### Returns:

  An object with the x and y Viewer coordinates

  Type
    object

#### getXODCoordinates(pageIndex, x, y)

  Returns an object with the original x and y PDF coordinates converted to XOD coordinates for the page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, that the coordinates are on
  `x` | number | The x coordinate
  `y` | number | The y coordinate

  ##### Returns:

  An object with the x and y XOD coordinates

  Type
    object

#### includesThumbnails()

  Used to know if a document contains thumbnails.

  ##### Returns:

  True if the document contains thumbnails.

  Type
    boolean

#### initOfflineDB(onComplete)

  [XOD Document only] Initializes the offline database for use. Must be called before any other offline mode functions are used.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `onComplete` | function | The function that's called when the offline database is ready for use.

#### insertBlankPages(insertBeforeThesePages [, width] [, height])

  [PDF Document only] Inserts blank pages before the given list of pages. Both width and height are in units of PDF points. You will need to pass "useDownloader: false" to your WebViewer constructor to use this method.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `insertBeforeThesePages` | Array.<number> |  | array of page numbers before which to insert blanks
  `width` | number | <optional> | width of the blank pages to insert. By default the width is 612 PDF points.
  `height` | number | <optional> | height of the blank pages to insert. By default the height is 792 PDF points.

  ##### Returns:

  a promise that resolves to an object with info for any pages inserted

  Type
    Promise

#### insertPages(sourceDocument, pageArray, insertBeforeThisPage)

  [PDF Document only] Inserts a set of pages from the provided Document before a given page number. Note that this method will need to wait for the entire file to be downloaded before the change is applied. You will need to pass "useDownloader: false" to your WebViewer constructor to use this method.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sourceDocument` | Document | other document from which to take pages (cannot be the same document)
  `pageArray` | Array.<number> | array of page numbers to extract from the given document
  `insertBeforeThisPage` | number | page number before which to insert the pages

  ##### Returns:

  a promise that resolves to an object describing the updated state of the pages in the document

  Type
    Promise

#### isDownloaded()

  [XOD Document only] Whether the document has already been downloaded for offline mode or not.

#### isLinearized()

  [PDF Document only] Returns whether the document is linearized or not. Note that this only works for documents that are loaded by URL.

  ##### Returns:

  Whether the document is linearized or not

  Type
    boolean

#### isWebViewerServerDocument()

  Gets whether the document will be interacted with as a WebViewer Server document This will return false if the document was loaded from WebViewer Server but forceClientSideInit is set to true

  ##### Returns:

  Returns whether the document will be interacted with as a WebViewer Server document.

  Type
    boolean

#### loadAsync(partRetriever, callback(error), options)

  Initialize a Document so that it can be used to load page canvases.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `partRetriever` | CoreControls.PartRetrievers.PartRetriever | An instance of PartRetriever.
  `callback(error)` | function | The callback to call when the Document has been initialized. If there is an error then the error parameter will be defined.
  `options` |  | an object that can contain the following optional parameters ###### Properties
  Name | Type | Argument | Description
  --- | --- | --- | ---
  `workerTransportPromise` | Promise | <optional> | Required for PDF viewing. A promise that will be resolved when a worker transport has been initialized. This can be created by calling CoreControls.initializeWorkerTransport
  `getPassword` | function | <optional> | An method of the form function(callback) where callback is of the form function(password). getPassword will be called when a password is required to load a PDF document and should call the callback with the retrieved password.
  `extension` | string | <optional> | An field used to specify the type of file being read. This is only relevant for PDF viewing and at the moment only works for certain image formats and .pdf

#### loadCanvasAsync(options)

  Loads a canvas for a particular page index.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `options` | Object | An object specifying the options for loading the canvas. The following parameters should be properties on this object. The only non-optional parameter is pageIndex. ###### Properties
  Name | Type | Argument | Description
  --- | --- | --- | ---
  `pageIndex` | number |  | The page number, zero-indexed, of the requested canvas.
  `zoom` | number | <optional> | The zoom value to render the page at.
  `getZoom` | function | <optional> | A function that returns the zoom value to render the page at. Use this instead of "zoom" if the value might change in the process of setting up the canvas.
  `pageRotation` | CoreControls.PageRotation | <optional> | The rotation of the page. Valid values are CoreControls.PageRotation.e_0, CoreControls.PageRotation.e_90, CoreControls.PageRotation.e_180, CoreControls.PageRotation.e_270.
  `getPageRotation` | function | <optional> | A function that returns the rotation of the page. Use this instead of "pageRotation" if the value might change in the process of setting up the canvas.
  `finishedLoading` | function | <optional> | A callback called after the list of page resources is retrieved. Return true if rendering should continue, false otherwise.
  `acquireResources` | function | <optional> | A function that returns whether resources need to be acquired or not, defaults to true.
  `resourcesLoaded` | function | <optional> | A callback called after the page's resources have been loaded. Return true if rendering should continue, false otherwise.
  `getPageTransform` | function | <optional> | A function that returns the x and y values of the page's translation.
  `drawComplete` | function | <optional> | The callback to call when the canvas has been completely rendered.
  `drawProgressive` | function | <optional> | The callback to call when the canvas has been partially rendered.
  `renderRect` | object | <optional> | An object with x1, y1, x2, y2 properties which is the partial rectangle to render of the entire page. The top left of the page is (0, 0).
  `useProgress` | boolean | <optional> | Whether progressive rendering should be used or not.

  ##### Returns:

  An id that can be passed to the corresponding Pause, Resume or Cancel functions

  Type
    number

#### loadPageText(pageIndex, onComplete(text))

  Gets all the text on the requested page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | number | The page number, zero-indexed, that the text is on.
  `onComplete(text)` | function | The callback to call when the text is ready

#### loadThumbnailAsync(pageIndex, onLoadThumbnail(HTMLImageElement|HTMLCanvasElement))

  Loads a thumbnail image for a particular page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageIndex` | string | The page index of the requested thumbnail (0-indexed).
  `onLoadThumbnail(HTMLImageElement|HTMLCanvasElement)` | function | The callback to call when the thumbnail has been retrieved.

  ##### Returns:

  The id of the request that can later be used for cancelling the request It is passed an image element if the .xod file contains thumbnails and a canvas element otherwise.

  Type
    number

#### movePages(pageArray, insertBeforeThisPage)

  [PDF Document only] Moves the pages given in an array so they appear in sequence before a given page number. Note that this method will need to wait for the entire file to be downloaded before the change is applied.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageArray` | Array.<number> | the page numbers to move
  `insertBeforeThisPage` | number | page number before which to insert the other pages

  ##### Returns:

  a promise that resolves to an object describing the updated state of the pages in the document

  Type
    Promise

#### pauseLoadCanvas(id)

  Pauses the loadCanvasAsync call corresponding to the passed in id

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `id` | number | The id returned from the loadCanvasAsync call that will be paused.

#### refreshTextData()

  Refresh the text data stored by the viewer. Useful if the text content of the document has changed, e.g. after a redaction.

#### removePages(pageArray)

  [PDF Document only] Removes the given page numbers. Note that this method will need to wait for the entire file to be downloaded before the change is applied.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageArray` | Array.<number> | the page numbers to remove

  ##### Returns:

  a promise that resolves to an object describing the updated state of the pages in the document

  Type
    Promise

#### resumeLoadCanvas(id)

  Resumes the loadCanvasAsync call corresponding to the passed in id

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `id` | number | The id returned from the loadCanvasAsync call that will be resumed.

#### rotatePages(pageArray, rotation)

  [PDF Document only] Adds the given rotation to the given pages. Note that this method will need to wait for the entire file to be downloaded before the change is applied.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pageArray` | Array.<number> | an array of the numbers of pages to rotate
  `rotation` | CoreControls.PageRotation | the page rotation to add

  ##### Returns:

  a promise that resolves to an object describing the updated state of the pages in the document

  Type
    Promise

#### setLayersArray(layerContext)

  [PDF Document only] Update the array describing the layers/OCG structure in order to adjust which layers should be enabled or disabled.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `layerContext` |  |

  See:
    - getLayersArray

#### setOfflineModeEnabled(enabled)

  [XOD Document only] Sets whether offline mode is enabled or not.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `enabled` | boolean | The new value for whether offline mode is enabled or not.

#### setOverprintPreviewMode(mode)

  [PDF Document only] Set the overprint preview mode to be used when rendering this document.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `mode` |  | The mode to use. Possible values are CoreControls.OverprintPreviewMode.OFF, CoreControls.OverprintPreviewMode.ON and CoreControls.OverprintPreviewMode.PDFX_ON

#### setWatermark(options)

  Sets watermark to be added to the document

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `options` | object | Object that contains style/content of the watermark

  ##### Example

      doc.setWatermark({ <br/>
        diagonal: { <br/>
          fontSize: (number), <br/>
          fontFamily: (string), <br/>
          color: (string), <br/>
          opacity: (number), <br/>
          text: (string) <br/>
        }, <br/>
        header: { <br/>
          fontSize: (number), <br/>
          fontFamily: (string), <br/>
          color: (string), <br/>
          opacity: (number), <br/>
          left: (string), <br/>
          center: (string), <br/>
          right: (string) <br/>
        }, <br/>
        footer: { <br/>
          fontSize: (number), <br/>
          fontFamily: (string), <br/>
          color: (string), <br/>
          opacity: (number), <br/>
          left: (string), <br/>
          center: (string), <br/>
          right: (string) <br/>
        } <br/>
        custom: (function(ctx, pageIndex, pageWidth, pageHeight))
      });

#### storeOffline(onComplete, onProgress)

  [XOD Document only] Downloads the document for offline viewing.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `onComplete` | function | The function that's called when the document has finished being downloaded or the download has been cancelled
  `onProgress` | function | The function that's called on each update in progress of the download. The fraction downloaded is passed as a parameter. (eg 50% downloaded passes 0.5)

#### unloadCanvasResources(id)

  Unloads resources for the page associated with the loadCanvasAsync call corresponding to the passed in id. So if the loadCanvasAsync call had requested page 2 then page 2's resources will be cleaned up (as long as nothing else requires those resources). Note that the canvas element itself is not touched.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `id` | number | The id returned from the loadCanvasAsync call that will have it's page resources unloaded

#### unloadResources()

  Cleans up the resources associated with the document.

### Events

#### colorSeparationAdded

  Triggered when a color separation is loaded and available on the document.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `evt` | object | jQuery's event object
  `colorData` | object | An object with properties of the color separation ###### Properties
  Name | Type | Description
  --- | --- | ---
  `name` | string | The name of the color separation
  `rgb` | array | An array containing the R, G and B values for the separation

#### Search results