PDFProvider module

Author: William Leemans
Copyright: William Leemans 2024

• PDFProvider
  • .pdfProvider ⇐ baseProvider
    • new exports.pdfProvider(actor)
    • .convertHexColorToRgb(hex, [defaultRGB]) ⇒ Array.<number>
    • .createFile()
    • .defaultFont(font, size, [lineHeight])
    • .defaultFontColor(color)
    • .embedImage(imageData)
    • .embedFont(fontName) ⇒ CustomFontEmbedder
    • .embedTextBox(textBoxData)
    • .field(file, name, value, options)
    • .fieldExists(file, name) ⇒ boolean
    • .getField(file, name) ⇒ Object | undefined
    • .getFieldValue(file, name, defaultValue) ⇒ string | boolean
    • .getFieldOptions(file, name, optionName) ⇒ Object | string | boolean | number
    • .image(file, page, x, y, path, [maxWidth], [maxHeight], [options])
    • .updateFile()
    • .saveFile()
    • .textBox(reference, file, page, x, y, width, height, text, [options])

A class to manipulate PDF files.

You should use:

• pdfProvider.field to add form field text
• pdfProvider.image to add images
• pdfProvider.textBox to add text boxes

Kind: static class of PDFProvider
Extends: baseProvider
Requires: module:pdf-lib, module:fontkit, module:pako

• .pdfProvider ⇐ baseProvider
  • new exports.pdfProvider(actor)
  • .convertHexColorToRgb(hex, [defaultRGB]) ⇒ Array.<number>
  • .createFile()
  • .defaultFont(font, size, [lineHeight])
  • .defaultFontColor(color)
  • .embedImage(imageData)
  • .embedFont(fontName) ⇒ CustomFontEmbedder
  • .embedTextBox(textBoxData)
  • .field(file, name, value, options)
  • .fieldExists(file, name) ⇒ boolean
  • .getField(file, name) ⇒ Object | undefined
  • .getFieldValue(file, name, defaultValue) ⇒ string | boolean
  • .getFieldOptions(file, name, optionName) ⇒ Object | string | boolean | number
  • .image(file, page, x, y, path, [maxWidth], [maxHeight], [options])
  • .updateFile()
  • .saveFile()
  • .textBox(reference, file, page, x, y, width, height, text, [options])

Param	Type	Description
actor	Object	The Foundry VTT actor object.

Convert Hexadecimal color (HTML) to RGB

Kind: instance method of pdfProvider
Returns: Array.<number> - the RGB color code in % for each of the main colors, or the color code for black

Param	Type	Default	Description
hex	string		The hexadecimal value (html color) representing a color
[defaultRGB]	Array.<number>	[0, 0, 0]	The default color to return if @param hex is invalid

Create a file when no file is associated with the provider sheet

Kind: instance method of pdfProvider

Set the default font, size and lineheight for text boxes

Kind: instance method of pdfProvider

Param	Type	Default	Description
font	string		The name of the font file
size	number		The size of the font
[lineHeight]	number	size	The lineheight of the font

Set the default font color for text boxes

Kind: instance method of pdfProvider

Param	Type	Description
color	string | rgb	an HTML or fontkit rgb color. import rgb from './pdf-lib.esm.js'; const black = rgb(0,0,0);

Embed an image to the given PDF Object

Kind: instance method of pdfProvider

Param	Type	Description
imageData	Object	an Object containing path, (x,y) coordinates, scaling information, etc...
imageData.page	number	the page to embed the image in. Pages start at 0
imageData.x	number	the x coordinate to embed the image at
imageData.y	number	the y coordinate to embed the image at
imageData.path	string	the url to the image to embed
imageData.maxWidth	number	the maximum width of the image
imageData.maxHeight	number	the maximum height of the image

Embed a font into the given PDF

Kind: instance method of pdfProvider
Returns: CustomFontEmbedder - The resulted embedded font

Param	Type	Description
fontName	string	the case insensitive name of the standard font (pdf-lib.StandardFonts) or font filename. Current StandardFonts are: Courier, CourierBold, CourierOblique, CourierBoldOblique, Helvetica, HelveticaBold, HelveticaOblique, HelveticaBoldOblique, TimesRoman, TimesRomanBold, TimesRomanItalic, TimesRomanBoldItalic, Symbol, ZapfDingbats

Embed a Text Box to the given PDF Object

Kind: instance method of pdfProvider

Param	Type	Description
textBoxData	Object	an Object containing path, (x,y) coordinates, scaling information, etc...
textBoxData.reference	string	a reference to the field (for debugging purposes)
textBoxData.file	string	the name pf the pdf file to embed the text in to
textBoxData.page	number	the page to embed the text on. Pages start at 0
textBoxData.x	number	the x coordinate to start the textbox at.
textBoxData.y	number	the y coordinate to start the textbox at.
textBoxData.width	number	the width of the textbox
textBoxData.height	number	the height of the textbox
textBoxData.text	string	the text to be printer
textBoxData.options	Object	the options for the text to be printed
textBoxData.options.lineHeight	Number	textbox line height
textBoxData.options.overflow	Boolean	allow textbox to overflow the boundaries
textBoxData.options.overrideFont	Boolean	allow the font to be overridden by the override font
textBoxData.options.prefix	String	A prefix to be added before the text
textBoxData.options.size	Number	size of the font
textBoxData.options.sizeParser	function	provide a function to calculate fontsize based on the result of the Promised text value
textBoxData.options.suffix	function	A suffix to be added to the text
textBoxData.options.color	function	hexadecimal color for the text
textBoxData.options.width	function	maximum width of the textbox
textBoxData.options.height	function	maximum height of the textbox

Store form field information, text for text fields, booleans for checkboxes

Kind: instance method of pdfProvider

Param	Type	Description
file	string	the pdf filename to apply the image to ('all' means all PDFs)
name	string	The name of the field to reference
value	string | boolean | Promise	The value to be applied to the field
options	Object	Optional data, functions for the field
options.parseValue	function	function to parse the value after resolving the value Promise

Check if a value for a form field is defined

Kind: instance method of pdfProvider
Returns: boolean - whether the field is defined

Param	Type	Description
file	string	The name of the PDF file a field belongs to
name	string	The name of the field to return the value from

Return a PDF field object definition

Kind: instance method of pdfProvider
Returns: Object | undefined - the requested field data

Param	Type	Description
file	string	The name of the PDF file a field belongs to
name	string	The name of the field to return the value from

Return a PDF form field value

Kind: instance method of pdfProvider
Returns: string | boolean - - the requested field

Param	Type	Description
file	string	The name of the PDF file a field belongs to
name	string	The name of the field to return the value from
defaultValue	string | boolean	The value to return if the field cannot be found

Get the options associated to a form field

Kind: instance method of pdfProvider
Returns: Object | string | boolean | number - the requested field option(s)

Param	Type	Description
file	string	The name of the PDF file a field belongs to
name	string	The name of the field to return the value from
optionName	string	Optional name of a field to return

Store image information

Kind: instance method of pdfProvider

Param	Type	Description
file	string | Array.<string>	the pdf filename(s) to apply the image to ('all' means all PDFs)
page	number | Array.<number>	The page(s) to add the image to
x	number	The x coordinate for the image
y	number	The y coordinate for the image
path	string	The url to the image to add
[maxWidth]	number	The maximum width of the Image
[maxHeight]	number	The maximum height of the Image
[options]	object	Additional options

Parses the provided filedata, fills out pdf form fields, adds images and saves the blob

Kind: instance method of pdfProvider

Save the generated PDF to disk

Kind: instance method of pdfProvider

Store pdf text box information

Kind: instance method of pdfProvider

Param	Type	Default	Description
reference	string		a reference for the textBox added (for debugging purposes)
file	string | Array.<string>		the pdf filename(s) to apply the text box to ('all' means all PDFs)
page	number | Array.<number>		The page(s) to add the text box to
x	number		The x coordinate for the text box
y	number		The y coordinate for the text box
width	number		The width of the text box to add
height	number		The height of the text box to add
text	string | Promise		The text to display in the text box
[options]	object	{}	Additional options
[options.color]	string | Array.<number>		either a hexadecimal (html) color, or array of rgb values (in %)
[options.font]	string		The name or filename of the font to be used
[options.halign]	'left' | 'center' | 'right'	'left'	how to align the text horizontally
[options.lineHeight]	number		The lineheight of the text
[options.multiline]	boolean	true	treat this text as multiline
[options.overflow]	boolean	false	allow the text to overflow the boundaries. The text will be suffixed with three dots if it is too long
[options.prefix]	string		a text to add at the beginning of @param text
[options.size]	number		The font size
[options.suffix]	string		a text to add at the end of @param text, after any overflow characters.
[options.valign]	'top' | 'center' | 'bottom'	'bottom'	how to align the text vertically
[options.valueParser]	function		function to parse the value after resolving the value Promise