PDF

The PDF component is used to manipulate existing PDF documents or create new ones.

This functionality is only available to Boxlang+/++ subscribers only but can be installed in conjunction with the bx-plus Module with a limited trial.

Component Signature

<bx:PDF action=[string]
ascending=[boolean]
type=[string]
ddxfile=[string]
destination=[string]
directory=[string]
encrypt=[string]
flatten=[boolean]
image=[any]
filter=[string]
info=[struct]
inputfiles=[struct]
keepbookmark=[boolean]
name=[string]
opacity=[double]
order=[string]
outputfiles=[struct]
overwrite=[boolean]
pages=[string]
newOwnerPassword=[string]
newUserPassword=[string]
password=[string]
permissions=[string]
saveoption=[string]
showonprint=[boolean]
source=[any]
stoponerror=[boolean]
version=[double]
text=[string]
numberformat=[string]
align=[string]
leftmargin=[numeric]
rightmargin=[numeric]
topmargin=[numeric]
bottommargin=[numeric]
format=[string]
imageprefix=[string]
resolution=[string]
transparent=[boolean]
overridepage=[boolean]
hires=[boolean]
scale=[double]
position=[double]
rotation=[double]
hscale=[double]
vscale=[double]
foreground=[boolean]
isbase64=[boolean]
copyfrom=[any]
exportTo=[string]
importFrom=[string]
encodeall=[boolean] />

Attributes

Atrribute	Type	Required	Description	Default
action	string	false	String - The action to perform on the PDF document. Supported values: addheader, addfooter, addwatermark, deletepages, export, extracttext, extractimage, getinfo, import, merge, protect, read, removepassword, removewatermark, removeheaderfooter, sanitize, setinfo, sign, thumbnail, transform, unsign, validatesignature, write. NOTE: Some actions are not yet implemented and will throw a NOT_IMPLEMENTED error.	open
ascending	boolean	false	Boolean - Sort order for operations. Default: true.	true
type	string	false	String - The type of operation or format. Used with export/import actions to specify the data format (e.g., "fdf", "xfdf").
ddxfile	string	false	String - DDX file path for processddx operations. NOTE: processddx action is not yet implemented.
destination	string	false	String - The destination file path for output operations. Used with actions like extracttext, write, and export.
directory	string	false	String - The directory path for operations that create multiple files, such as thumbnail generation or image extraction.
encrypt	string	false	String - Encryption settings for PDF operations.
flatten	boolean	false	Boolean - Whether to flatten form fields. Default: false.	false
image	any	false	Any - Image data or file path for watermark operations.
filter	string	false	String - Filter criteria for extraction operations.
info	struct	false	Struct - Document information structure for setinfo operations.
inputfiles	struct	false	Struct - Input file mappings for batch operations.
keepbookmark	boolean	false	Boolean - Whether to preserve bookmarks during operations.
name	string	false	String - The name of the variable to store the result in. Alternative to destination for storing output in memory.
opacity	double	false	Double - Opacity level for watermarks (0.0 to 1.0). Default: 0.5.	0.5
order	string	false	String - Ordering specification for merge operations.
outputfiles	struct	false	Struct - Output file mappings for batch operations.
overwrite	boolean	false	Boolean - Whether to overwrite existing files. Default: false.	false
pages	string	false	String - Specifies which pages to operate on. Can be page ranges like "1-5", individual pages like "1,3,5", or "*" for all pages. Required for addheader, addfooter, and deletepages actions.
newOwnerPassword	string	false	String - The new owner password when protecting a PDF. Required for the protect action.
newUserPassword	string	false	String - The new user password when protecting a PDF.
password	string	false	String - The password for encrypted PDF documents.
permissions	string	false	String - The permissions to set when protecting a PDF document.
saveoption	string	false	String - Save options for write operations.
showonprint	boolean	false	Boolean - Whether watermark shows when printing.
source	any	false	Any - The source PDF document(s) to operate on. Can be a file path, binary data, or PDF document variable.
stoponerror	boolean	false	Boolean - Whether to stop processing on first error.
version	double	false	Double - PDF version to use for output documents.
text	string	false	String - Text content for header/footer operations.
numberformat	string	false	String - Number format for page numbering in headers/footers. Valid values: "numeric", "lowercaseroman", "uppercaseroman". Default: "numeric".	numeric
align	string	false	String - Text alignment for header/footer text. Valid values: "left", "right", "center". Default: "left".	left
leftmargin	numeric	false	Numeric - Left margin in points for header/footer positioning.
rightmargin	numeric	false	Numeric - Right margin in points for header/footer positioning.
topmargin	numeric	false	Numeric - Top margin in points for header positioning.
bottommargin	numeric	false	Numeric - Bottom margin in points for footer positioning.
format	string	false	String - Output format for thumbnail generation. Default: "jpeg".	jpeg
imageprefix	string	false	String - Prefix for generated image filenames. Default: "".
resolution	string	false	String - Resolution quality for thumbnails. Valid values: "low", "medium", "high". Default: "high".	high
transparent	boolean	false	Boolean - Whether thumbnail background is transparent. Default: false.	false
overridepage	boolean	false	Boolean - Whether to override existing pages. Default: false.	false
hires	boolean	false	Boolean - High resolution mode for operations. NOTE: This attribute is not yet implemented.
scale	double	false	Double - Scale factor for thumbnails and watermarks. Default: 100.0.	100.0
position	double	false	Double - Position for watermark or signature placement.
rotation	double	false	Double - Rotation angle in degrees for watermarks or signatures.
hscale	double	false	Double - Horizontal scale factor for watermarks. Default: 1.0.	1.0
vscale	double	false	Double - Vertical scale factor for watermarks. Default: 1.0.	1.0
foreground	boolean	false	Boolean - Whether watermark appears in foreground. Default: false.	false
isbase64	boolean	false	Boolean - Whether input data is base64 encoded. Default: false.	false
copyfrom	any	false	Any - Source document to copy pages from.
exportTo	string	false	String - Target file path for export operations.
importFrom	string	false	String - Source file path for import operations.
encodeall	boolean	false	Boolean - Whether to encode all content. NOTE: This attribute is not yet implemented.

Examples

Reading PDF Information

<bx:pdf action="getinfo" source="report.pdf" name="pdfInfo" />

<bx:output>
PDF Title: #pdfInfo.Title#<br>
Author: #pdfInfo.Author#<br>
Pages: #pdfInfo.TotalPages#<br>
Created: #pdfInfo.Created#
</bx:output>

Merging Multiple PDFs

<bx:pdf action="merge" destination="combined-report.pdf" overwrite="true">
    <bx:pdfparam source="section1.pdf" />
    <bx:pdfparam source="section2.pdf" />
    <bx:pdfparam source="appendix.pdf" />
</bx:pdf>

Extracting Text Content

<bx:pdf action="extracttext" 
        source="document.pdf" 
        name="extractedText" 
        pages="1-5" />

<bx:output>
Extracted text: #extractedText#
</bx:output>

Adding Watermarks

<bx:pdf action="addwatermark" 
        source="original.pdf" 
        destination="watermarked.pdf"
        image="watermark.png"
        pages="*"
        opacity="0.3"
        position="5"
        overwrite="true" />

Adding Headers and Footers

<bx:pdf action="addheader" 
        source="document.pdf" 
        destination="document-with-header.pdf"
        text="Company Confidential"
        align="center"
        pages="*"
        overwrite="true" />

<bx:pdf action="addfooter" 
        source="document-with-header.pdf" 
        destination="final-document.pdf"
        text="Page _PAGENUMBER of _LASTPAGENUMBER"
        align="center"
        pages="*"
        numberformat="numeric"
        overwrite="true" />

Protecting PDF with Password

<bx:pdf action="protect" 
        source="sensitive-data.pdf" 
        destination="protected-data.pdf"
        newOwnerPassword="admin123"
        newUserPassword="user456"
        permissions="AllowPrinting,AllowCopy"
        overwrite="true" />

Removing Password Protection

<bx:pdf action="removepassword" 
        source="protected-document.pdf" 
        destination="unlocked-document.pdf"
        password="user456"
        overwrite="true" />

Generating Thumbnails

<bx:pdf action="thumbnail" 
        source="presentation.pdf" 
        destination="thumbnails/"
        pages="1,3,5"
        format="png"
        resolution="high"
        scale="150"
        imageprefix="slide_" />

Deleting Specific Pages

<bx:pdf action="deletepages" 
        source="full-report.pdf" 
        destination="trimmed-report.pdf"
        pages="2,4-6,10"
        overwrite="true" />

Setting Document Information

<bx:set docInfo = {
    "Title": "Annual Financial Report",
    "Author": "Finance Department",
    "Subject": "2024 Financial Analysis",
    "Keywords": "finance, annual, report, 2024"
} />

<bx:pdf action="setinfo" 
        source="report.pdf" 
        destination="report-with-metadata.pdf"
        info="#docInfo#"
        overwrite="true" />

Using PDF Variables

<!-- Read PDF into memory -->
<bx:pdf action="read" source="input.pdf" name="pdfData" />

<!-- Process the PDF data -->
<bx:pdf action="addwatermark" 
        source="#pdfData#" 
        name="watermarkedPdf"
        text="DRAFT"
        opacity="0.5" />

<!-- Write to file -->
<bx:pdf action="write" 
        source="#watermarkedPdf#" 
        destination="output.pdf"
        overwrite="true" />

Complex Multi-Action Example

<bx:try>
    <!-- Step 1: Read and get info -->
    <bx:pdf action="getinfo" source="original.pdf" name="info" />
    
    <!-- Step 2: Add header and footer -->
    <bx:pdf action="addheader" 
            source="original.pdf" 
            name="withHeader"
            text="Document #info.Title#"
            align="center"
            pages="*" />
    
    <bx:pdf action="addfooter" 
            source="#withHeader#" 
            name="withFooter"
            text="Page _PAGENUMBER of _LASTPAGENUMBER | Confidential"
            align="center"
            pages="*" />
    
    <!-- Step 3: Add watermark -->
    <bx:pdf action="addwatermark" 
            source="#withFooter#" 
            name="finalPdf"
            text="INTERNAL USE ONLY"
            opacity="0.2"
            pages="*" />
    
    <!-- Step 4: Write final document -->
    <bx:pdf action="write" 
            source="#finalPdf#" 
            destination="processed-document.pdf"
            overwrite="true" />
    
    <p>PDF processing completed successfully!</p>
    
<bx:catch type="any">
    <p>Error processing PDF: #cfcatch.message#</p>
</bx:catch>
</bx:try>

Supported Actions

• addheader - Add headers to PDF pages

• addfooter - Add footers to PDF pages

• addwatermark - Add text or image watermarks

• deletepages - Remove specific pages

• extracttext - Extract text content

• getinfo - Get document metadata

• merge - Combine multiple PDFs

• protect - Add password protection

• read - Load PDF into memory

• removepassword - Remove password protection

• setinfo - Set document metadata

• thumbnail - Generate page thumbnails

• write - Save PDF to file

Related Components

• PDFParam - Specify parameters for PDF operations

• PDFForm - Manipulate PDF form fields