API Documentation for Document
- API Documentation for Document
- NoPoDoFo Document
- Properties
- Methods
- setPassword
- getPageCount
- getPage
- hideToolbar
- hideMenubar
- hideWindowUI
- fitWindow
- centerWindow
- displayDocTitle
- useFullScreen
- attachFile
- insertExistingPage
- insertPage
- append
- isLinearized
- getWriteMode
- isAllowed
- createFont
- createFontSubset
- getObject
- getNames
- getOutlines
- createXObject
- createPage
- createPages
- getAttachment
- load
- splicePages
- insertPages
- write
- hasSignatures
- getSignatures
- gc
NoPoDoFo Document
The NoPoDoFo Document class is a wrapper around PoDoFo::PdfMemDocument. This is the core class for reading and manipulating pdf documents. This class was designed to allow easy access to the pdf object structure and should be used whenever you want to change the structure of the pdf document. If you are only creating a pdf file use the StreamDocument class.
Document utilizes PoDoFo's load on demand policy. When a PDF is loaded through Document
.load, document objects are read into memory
at their first point of access. If an object is never used, it will never be loaded into memory, allowing for the ingestion and modification
of large documents with a small memory footprint.
abstract class Base {
readonly form: Form
readonly body: Object[]
readonly version: NPDFVersion
pageMode: NPDFPageMode
pageLayout: NPDFPageLayout
printingScale: string
baseUri: string
language: string
readonly info: NPDFInfo
getPageCount(): number
getPage(n: number): Page
hideToolbar(): void
hideMenubar(): void
hideWindowUI(): void
fitWindow(): void
centerWindow(): void
displayDocTitle(): void
useFullScreen(): void
attachFile(file: string): void
insertPage(rect: Rect, index: number): Page
isLinearized(): boolean
getWriteMode(): NPDFWriteMode
isAllowed(perm: ProtectionOption): boolean
createFont(opts: NPDFCreateFontOpts): Font
createFontSubset(opts: NPDFCreateFontOpts): Font
/**
* Get an existing outline or create a new outline and new root node
* @param {boolean} [create] - Create a new outline if one does not already exist
* @param {string} [root] - Create a Root node with the provided name
*/
getOutlines(create?: boolean, root?: string): null | Outline
getObject(ref: Ref): Object
getNames(create: boolean): Object | null
createXObject(rect: Rect): XObject
createPage(rect: Rect): Page
createPages(rects: Rect[]): number
getAttachment(fileName: string): FileSpec
addNamedDestination(page: Page, destination: NPDFDestinationFit, name: string): void
}
class Document extends Base {
constructor()
encrypt: Encrypt
readonly trailer: Object
readonly catalog: Object
setPassword(pwd:string): void
load(file: string | Buffer,
opts: {
forUpdate?: boolean,
password?: string
},
cb: Callback<void>): void
load(file: string | Buffer, cb: Callback<void>): void
splicePages(startIndex: number, count: number): void
insertPages(fromDoc: Document, startIndex: number, count: number): number
write(destination: Callback<Buffer> | string, cb?: Callback<string>): void
getFont(name: string): Font
listFonts(): { id: string, name: string }[]
gc(file: string, pwd: string, output: string, cb: Callback<string | Buffer>): void
hasSignatures(): boolean
getSignatures(): SignatureField[]
insertExistingPage(memDoc: Document, index: number, insertIndex: number): number
append(doc: Document|Document[]): void
}
export class StreamDocument extends Base {
constructor(file?: string, opts?: { version: NPDFVersion, writer: NPDFWriteMode, encrypt?: Encrypt })
/**
* Closing a stream document will prevent any further writes to the document.
* If the object was instantiated with a file path, close will write to this file.
* If "new" was called without any args, the document is written to a nodejs buffer, close
* will return the buffer.
*/
close(): string | Buffer
}
Properties
catalog
Readonly property returning an Object. The catalog is the root of the documents object tree; every object in a document is reachable from the catalog.
trailer
Readonly property returning an Object. The trailer resides at the end of the document, containing document level information necessary to parse the document.
encrypt
If the document is encrypted an Encrypt object is returned otherwise null.
info
Readonly NPDFInfo.
language
Set the Document viewer preference. Set the language of the Document.
printingScale
The page scaling option displayed in the print dialog, valid values are: 'None', and 'AppDefault'
pageLayout
Specifies the page layout as NPDFPageLayout when the document is opened.
pageMode
Specifies the page mode as NPDFPageMode when the document is opened.
version
Pdf specification version as NPDFVersion.
body
The Document body (readonly) is an array of all Objects accessible from the Document catalog(#catalog).
form
Form is a readonly property that will either return Form or null if the Document does not have an AcroForm dictionary.
Methods
setPassword
Set the password for the document.
getPageCount
getPageCount(): number
Get the number of pages in the Document. A Document must have at least one page.
getPage
getPage(n: number): IPage
Get the Page. If n is < 0 or greater than page count a RangeError will be thrown.
hideToolbar
hideToolbar(): void
Toggle view option hideToolbar.
hideMenubar
hideMenubar(): void
Toggle view option hideMenubar.
hideWindowUI
hideWindowUI(): void
Toggle view option hideWindowUI.
fitWindow
fitWindow(): void
Toggle view option fitWindow.
centerWindow
centerWindow(): void
Toggle view option centerWindow.
displayDocTitle
displayDocTitle(): void
Toggle view option displayDocTitle.
useFullScreen
useFullScreen(): void
Toggle view option useFullScreen.
attachFile
attachFile(file: string): void
Attach a file, as a FileSpec to the Document. Files are by default embedded into instances of Document
,
StreamDocument
by default does not embed file attachments.
insertExistingPage
insertExistingPage(memDoc: Document, index: number, insertIndex: number): number
Insert the page of one Document into another. The document accepting the new page may be a Document or StreamDocument. However the Document that the page originates from must be a Document.
insertPage
insertPage(rect: Rect, index: number): Page
Insert a new page into the Document pages tree. Returns the new page. Note pages are 0-based index. If the index is < 0 the page will be insert at index 0, or as the first page in the document. If the index is greater than the current page count a RangeError is thrown.
append
append(doc: Document): void
Append a Document to another Document. The Document to be appended to must be a Document, StreamDocument's are not supported for this operation.
isLinearized
isLinearized(): boolean
Check if the Document is linearized, returns a boolean.
getWriteMode
getWriteMode(): NPDFWriteMode
Get the write mode as NPDFWriteMode for the Document.
isAllowed
isAllowed(perm: ProtectionOption): boolean
Check if a PDF protection permission ProtectionOption is allowed, returns a boolean.
createFont
createFont(opts: NPDFCreateFontOpts): Font
Create / Get a PDF Font object. If the build you have does not include fontconfig (Windows users) you must include the fontFile (path to font file on disk) in NPDFCreateFontOpts.
createFontSubset
createFontSubset(opts: NPDFCreateFontOpts): Font
Create a new PDF Font object. This font class will write only the characters used during painting operations. You can check if the Font instance is a subset by invoking Font.isSubsetting
getObject
getObject(ref: Ref): Obj
Get an object by Ref (indirect object reference). NoPoDoFo will always try to resolve a reference, some methods may however return a Ref instead of an nopodofo.Obj, this happens when the Obj in question is not available by the parent object, or parent vector. This is primarily seen in a nested array structure.
Example
const ar: nopodofo.Array = someObject.getArray()
if(ar.at(0) instanceof nopodofo.Object) {
// do something with the object
} else {
let ref = ar.at(0)
let obj = doc.getObject(ref)
// do something with the object
}
getNames
getNames(create: boolean): nopodofo.Object|null
Get the document names tree, if a names tree does not exist null is returned.
getOutlines
getOutlines(create?:boolean, root?:string): Outline
Get a Document
Outlines tree root object if one exists. To create an Outline
use the create and root parameters with values true
and a name for the new root node. An Outline
is typically used in conjunction with Destination and Action objects to
create Bookmarks
on a document. For a complete example see the Bookmark Cookbook
createXObject
createXObject(rect: Rect): XObject
Creates a new XObject, returns the newly created XObject.
createPage
createPage(rect: Rect): Page
Create a new PDF Page, returns the newly created page.
createPages
createPages(rects: Rect[]): number
Creates as many pages as rects provided, returns the new page count of the document.
getAttachment
getAttachment(filename: string): FileSpec
Get an embedded file as an instance of FileSpec. File lookup is done off the embedded file object's
UF
key. The UF
key value is the name of the file in utf-8. If no file is found with the filename provided, null
is returned.
load
load(file: string | Buffer,
opts: {
forUpdate?: boolean,
password?: string
},
cb: Callback<void>): void
load(file: string | Buffer, cb: Callback<void>): void
Load a PDF document into memory, remember Document loads objects on demand. This method accepts document in the form of
a buffer or as a file path. If the document requires a password, the password may be provided in the opts object. If the
document is password protected and a password is not provided a Password Required
error will be thrown. If forUpdate is
set to true, updates to the document will be written as an incremental update. An incremental update appends the changes
to the end of the document instead of re-writing the document.
Examples
Loading a document from disk
import {npdf} from 'nopodofo'
const doc = new npdf.Document()
doc.load('/file/path.pdf', e => {
if(e) {
// Load password on error
if(e.message.includes('Password required')) {
// handle error or set password if password is known
doc.password = 'secret'
}
}
// do something with the document
})
Loading a document from Buffer
import {npdf} from 'nopodofo'
import {S3} from 'aws-sdk'
const doc = new npdf.Document()
// getting a document from S3
const {Body: buffer} = await new S3().getObject({Bucket, Key}).promise()
doc.load(buffer, e => {
if(e) {/* handle error */}
// do something with document
})
splicePages
splicePages(startIndex: number, count: number): void
Deletes one or more pages from the document by removing the pages reference from the pages tree. This does NOT remove the page object as the page object may be used by other objects in the document. Parameter startIndex is the index of the page to start at, pages are 0-based indexed, and parameter count is the number of pages from the startIndex to delete.
insertPages
insertPages(fromDoc: Document, startIndex: number, count: number): number
Copies one or more pages from another pdf to this document. This function copies the entire document to the target document and then deletes pages that are not of interest. This is a much faster process, but without object garbage collection the document may result in a much larger than necessary document.
write
write(destination: Callback<Buffer> | string, cb?: Callback<string>): void
Write the file and any modifications made to the file to disk or a nodejs buffer. If destination is a string (file path), write will write the document to this path, if destination is not provided a buffer will be returned in the callback.
hasSignatures
hasSignatures(): boolean
Iterate each page of the document for signature fields, returns true if signature field is found.
getSignatures
getSignatures(): ISignatureField[]
Iterates each page of the document for signature fields and returns an array of all signature fields found.
See ISignatureField
gc
gc(file: string, pwd: string, output: string, cb: Callback<string|Buffer>): void
gc is a static method on the Document class. This method reads the document into memory, and re-writes the document
in NPDFWriteMode Compact
removing any objects that are not touched from the document catalog.
Parameters file is required, if the document is password protected you may pass the password as the second parameter, otherwise null. If an output
is provided the new document will be written to the output location, otherwise a nodejs buffer will be returned in the callback.