360Works PDF Plugin/Documentation

360Works PDF Plugin User Guide

Plugin for filling out form data in a PDF.

Usage Summary / Quick Start

Use PDFLoad to load a file. This also returns a list of all fields, or "ERROR" if an error occurs.

Use PDFLastError to check for any errors during loading of the PDF File

Use PDFGetFieldValue ( fieldName ) to query for existing field values

Use PDFSetFieldValue ( fieldName ; fieldValue ) to set values

Finally, use PDFSave ( path ) to save the PDF to the hard drive, applying any new PDF form values. Path is optional. This returns the path to the newly saved PDF.

360Works Plugin Setup Guides

See Plugins_101 for Error reporting, installation, registration, and more.

Function Summary

• PDFAddBookmarks ( pdfFile ; bookmarks { ; key1=value1 ; key2=value2 ; ...} ) — Add bookmarks to a PDF.
• PDFCreate ( { key1=value1 ; key2=value2 ; ... } ) — Create an empty PDF.
• PDFGetFieldValue ( field ) — Returns the value of a named field in the PDF form.
• PDFInfo ( pdfFile ) — Returns a list:

name
page count
file size

• PDFInsertPages ( origianlPdf ; pdfToInsert ; insertPageNumber { ; key1=value1 ; key2=value2 ; ...} ) — Inserts one PDF into another at the specified page.
• PDFLastError ( ) — Returns the last PDF-related error which occurred.
• PDFLicenseInfo ( ) — Returns information about the license used.
• PDFListFields ( sourcePDF ) — Returns a list of field names in the PDF.
• PDFListValues ( sourcePDF ) — Returns a list of field values in the PDF.
• PDFLoad ( pdfFile { key1=value1 ; key2=value2 ; ... } ) — Extracts all the form data from a PDF, returns a list of fields.
• PDFMerge ( pdf1 ; pdf2 { ; password1=x ; password2=y ; filename=out.pdf ; binaryResult=true ; ... } ) — Merges two PDFs into a single PDF file.
• PDFModifyBookmarks ( pdfFile { ; bookmarksToAdd ; bookmarksToRemove } ) — Extracts list of bookmarks from a PDF, allowing addition and removal of bookmarks.
• PDFPopulateForm ( sourcePDF ; keys ; values ) — Populates a PDF form with data.
• PDFRegister ( licenseKey ; registeredTo ) — Registers the plugin.
• PDFRemovePages ( origianlPdf ; pageRangeToDelete { ; key1=value1 ; key2=value2 ; ...} ) — Removes a specified page range from the pdf.
• PDFReplacePages ( origianlPdf ; replacementPdf ; pageRangeToReplace { ; key1=value1 ; key2=value2 ; ...} ) — Replace a specified page range with a PDF, default behavior removes any bookmarks that point to pages in the range to replace.
• PDFSave ( { path } ) — Creates a new PDF, using any form values set via the {@link #PDFSetFieldValue} function as data.
• PDFSetErrorCapture ( errorCapture ) — Toggles error dialogs on or off.
• PDFSetFieldValue ( field ; value ) — Set the value of a field in the PDF.
• PDFSplice ( pdf ; pageNumbers { ; key1=value1 ; key2=value2 ; ...} ) — Extract some pages from a PDF document into a new PDF.
• PDFVersion ( ) — Returns the version of the plugin which is installed.

Function Detail

PDFAddBookmarks ( pdfFile ; bookmarks { ; key1=value1 ; key2=value2 ; ...} )

Add bookmarks to a PDF. This function assumes that the PDF does not have bookmarks, existing bookmarks will be overwritten.

Example:

Set Variable [$addBookmark; PDFAddBookmarks( "http://host.com/file.pdf" ; "XML bookmark text" ; "filepath=" & Get(DesktopPath) )]

Optional Parameters

filepath

destination folder/path for the resulting file

Parameters:

pdfFile

the original PDF

bookmarks

XML representation of bookmarks

keyValuePairs

optional parameters, see specification above.

Returns: PDF with specified bookmarks.

PDFCreate ( { key1=value1 ; key2=value2 ; ... } )

Create an empty PDF.

Parameters:

args

optional parameters

See also: PDFLoad

Returns: 1 on successful PDF creation, "ERROR" if there was an error

PDFGetFieldValue ( field )

Returns the value of a named field in the PDF form.

Parameters:

field

the name of a field in the form

See also: PDFSetFieldValue

Returns: the field value, or ERROR if there was no such field in the form.

PDFInfo ( pdfFile )

Returns a list:

name
page count
file size

Parameters:

pdfFile

PDF file

Returns: return separated list

PDFInsertPages ( origianlPdf ; pdfToInsert ; insertPageNumber { ; key1=value1 ; key2=value2 ; ...} )

Inserts one PDF into another at the specified page. To append specify a page 1 higher than the last page of the original PDF. Bookmarks from the PDF to insert will be added as a block to the bookmarks of the original PDF before the first occurence of a bookmark to the page succeeding insertPageNumber, otherwise a custom structure can be specified with the bookmarks parameter.

Example:

Set Variable [$pdfInsert; PDFInsertPages( "http://host.com/file.pdf" ; "http://host.com/fileToInsert.pdf" ; 2 ; "filename=result.pdf" ; "filepath=" & Get(DesktopPath) )]

Optional Parameters

filename

name of the resulting file, otherwise a random name is assigned

filepath

destination folder/path for the resulting file

bookmarks

XML representation of bookmarks for the output PDF

<?xml version="1.0" encoding="ISO8859-1"?>
<Bookmark>
		    <Title Action="GoTo" Page="1 Fit" Style="italic">page 1</Title&gt
		    <Title Action="GoTo" Page="2 Fit" Style="italic">page 2
			        <Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title&gt
		    </Title>
		    <Title Action="GoTo" Page="4 Fit" Style="italic"&gtpage 4</Title>
</Bookmark>

Parameters:

originalPdf

The original PDF

pdfToInsert

PDF to be inserted

insertPageNumber

page number where insertion begins, to append specify a page 1 higher than the last page of the original PDF.

keyValuePairs

optional parameters, see specification above.

Returns: newly created PDF which contains the inserted PDF and specified bookmarks.

PDFLastError ( )

Returns the last PDF-related error which occurred. This should be called any time that a plugin function returns "ERROR" to get a user-readable description of the error.

If there are data fields specified which don't match any field in the PDF, PDFLastError will return a list of fields which could not be set.

Returns: Error text, or "" if there was no error.

PDFLicenseInfo ( )

Returns information about the license used.

Returns: version and registered to info, or "ERROR" on failure.

PDFListFields ( sourcePDF )

Returns a list of field names in the PDF.

Parameters:

sourcePDF

the PDF

See also: PDFListFields

Returns: return-separated list of values in the PDF form, or "ERROR" if something goes wrong.

PDFListValues ( sourcePDF )

Returns a list of field values in the PDF.

Parameters:

sourcePDF

the PDF

See also: PDFListFields

Returns: return-separated list of values in the PDF form, or "ERROR" if something goes wrong.

PDFLoad ( pdfFile { key1=value1 ; key2=value2 ; ... } )

Extracts all the form data from a PDF, returns a list of fields.

Parameters:

pdfFile

PDF container or URL

args

See also: PDFCreate

Returns: return-separated list of all fields in the PDF

PDFMerge ( pdf1 ; pdf2 { ; password1=x ; password2=y ; filename=out.pdf ; binaryResult=true ; ... } )

Merges two PDFs into a single PDF file.

Parameters:

pdf1

The first PDF.

pdf2

The second PDF.

args

optional arguments such as password1, password2, binaryResult.

Returns: path to the resulting PDF file in the temp directory, or "ERROR" if an error occurs.

PDFModifyBookmarks ( pdfFile { ; bookmarksToAdd ; bookmarksToRemove } )

Extracts list of bookmarks from a PDF, allowing addition and removal of bookmarks.

<?xml version="1.0" encoding="ISO8859-1"?>
<Bookmark>
		    <Title Action="GoTo" Page="1 Fit" Style="italic">page 1</Title&gt
		    <Title Action="GoTo" Page="2 Fit" Style="italic">page 2
			        <Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title&gt
		    </Title>
		    <Title Action="GoTo" Page="4 Fit" Style="italic"&gtpage 4</Title>
</Bookmark>

Parameters:

pdfFile

The original PDF

bookmarksToAdd

bookmarks to add

bookmarksToRemove

bookmarks to remove

Returns: XML representation of bookmarks

PDFPopulateForm ( sourcePDF ; keys ; values )

Populates a PDF form with data.

Error Handling

If there are data fields specified which don't match any field in the PDF, they will be logged as an error. Call PDFLastError to get a list of fields which could not be set.

If the source PDF cannot be read, or some other critical error occurs, "ERROR" is returned. Call PDFLastError for more info on this.

Parameters:

sourcePDF

the container/path/url where the PDF to fill out is located

keys

return-separated list of form field names to fill out

keys

return-separate list of form field values to enter into the form. There must be the same number of keys and values.

Returns: a newly created PDF with the data applied, or "ERROR" if the operation could not be completed.

PDFRegister ( licenseKey ; registeredTo )

Registers the plugin.

Parameters:

licenseKey

a valid license key

registeredTo

the company the plugin is registered to

Returns: 1 on success, or "ERROR" on failure.

PDFRemovePages ( origianlPdf ; pageRangeToDelete { ; key1=value1 ; key2=value2 ; ...} )

Removes a specified page range from the pdf.

Example:

Set Variable [$removePages; PDFRemovePages( "http://host.com/file.pdf" ; "2-3" ; "filename=result.pdf" ; "filepath=" & Get(DesktopPath) )]

The pageRangeToDelete parameter should be either a single page number, or a range specified as: 3...5

Optional Parameters

filename

name of the resulting file, otherwise a random name is assigned

filepath

destination folder/path for the resulting file

bookmarks

XML representation of bookmarks for the output PDF

<?xml version="1.0" encoding="ISO8859-1"?>
<Bookmark>
		    <Title Action="GoTo" Page="1 Fit" Style="italic">page 1</Title&gt
		    <Title Action="GoTo" Page="2 Fit" Style="italic">page 2
			        <Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title&gt
		    </Title>
		    <Title Action="GoTo" Page="4 Fit" Style="italic"&gtpage 4</Title>
</Bookmark>

Parameters:

originalPdf

The original PDF

pageRangeToDelete

range of pages to remove

keyValuePairs

optional parameters, see specification above.

Returns: newly created PDF with specified pages removed and specified bookmarks.

PDFReplacePages ( origianlPdf ; replacementPdf ; pageRangeToReplace { ; key1=value1 ; key2=value2 ; ...} )

Replace a specified page range with a PDF, default behavior removes any bookmarks that point to pages in the range to replace.

Example:

Set Field [Table::Container; PDFReplacePages( "http://host.com/file.pdf" ; "http://host.com/file2.pdf" ; "1-2" ; "filename=result.pdf" )]

The replacementPageRange parameter should be either a single page number, or a range specified as: 3-5

Optional Parameters

filename

name of the resulting file, otherwise a random name is assigned

filepath

destination folder/path for the resulting file

bookmarks

XML representation of bookmarks for the output PDF

keepBookmakrs

to preserve the bookmarks in the original PDF pass in keepBookmakrs=true, this is useful for bookmarks that point to sections of the PDF.

<?xml version="1.0" encoding="ISO8859-1"?>
<Bookmark>
		    <Title Action="GoTo" Page="1 Fit" Style="italic">page 1</Title&gt
		    <Title Action="GoTo" Page="2 Fit" Style="italic">page 2
			        <Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title&gt
		    </Title>
		    <Title Action="GoTo" Page="4 Fit" Style="italic"&gtpage 4</Title>
</Bookmark>

Parameters:

originalPdf

The original PDF

replacementPdf

replacement PDF

replacementPageRange

page range to replace

keyValuePairs

optional parameters, see specification above.

Returns: newly created PDF which contains the replacement PDF in place of replaced pages, and specified bookmarks.

PDFSave ( { path } )

Creates a new PDF, using any form values set via the PDFSetFieldValue function as data. If no path is specified, the PDF is written to a temporary file.

The default behavior of this function is to return a container

Parameters:

path

The full path of the file or directory where the new PDF is to be written.

Returns: a file path pointing to the location of the new PDF

PDFSetErrorCapture ( errorCapture )

Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call PDFSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.

Parameters:

errorCapture

set to true to suppress the default popups.

PDFSetFieldValue ( field ; value )

Set the value of a field in the PDF.

Parameters:

field

the name of a field in the PDF form

value

the value to assign to the field when the PDF is saved

See also: PDFSave

Returns: 1 if the field was successfully set, or ERROR if there was no such field in the form

PDFSplice ( pdf ; pageNumbers { ; key1=value1 ; key2=value2 ; ...} )

Extract some pages from a PDF document into a new PDF. Pass this function a source PDF and some page numbers to extract and use in the new PDF.

The pageNumbers parameter should be a comma-separated list of page numbers or page number ranges.

Optional Parameters

filename

The name given to the resulting PDF file

filepath

destination folder/path for the resulting file

ownerPassword

The password used to encrypt the PDF file

Set Variable [ $newPDF ; PDFSplice (
    myTable::myContainer ; // sourcePDF
    "1, 10, 20-30" ;  // pageNumbers
    "filename=SplicedResult.pdf" // optional filename parameter
) ]

Parameters:

sourcePDF

The original PDF

pageNumbers

The page numbers to take from the original PDF when assembling the new PDF.

args

optional parameters

Returns: newly created PDF which contains the specified pageNumbers from the sourcePDF.

PDFVersion ( )

Returns the version of the plugin which is installed.

Returns: version, or "ERROR" on failure.