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.
- PDFAddObject ( objectName { ; key1=value1 ; key2=value2 ; ... } ) —
- 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 ; ... } ) — 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
pdfFile
- the original PDF
bookmarks
- XML representation of bookmarks
keyValuePairs
- optional parameters, see specification above.
args
- optional parameters
field
- the name of a field in the form
pdfFile
- PDF file
- 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>
<Title Action="GoTo" Page="2 Fit" Style="italic">page 2
<Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title>
</Title>
<Title Action="GoTo" Page="4 Fit" Style="italic">page 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: PDFListFieldsReturns: 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: PDFListFieldsReturns: 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: PDFCreateReturns: return-separated list of all fields in the PDFPDFMerge ( pdf1 ; pdf2 { ; password1=x ; password2=y ; filename=out.pdf ; ... } )
Merges two PDFs into a single PDF file.
Parameters:pdf1
- The first PDF.
pdf2
- The second PDF.
args
- optional arguments such as password1, password2.
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> <Title Action="GoTo" Page="2 Fit" Style="italic">page 2 <Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title> </Title> <Title Action="GoTo" Page="4 Fit" Style="italic">page 4</Title> </Bookmark>
Parameters:pdfFile
- The original PDF
bookmarksToAdd
- bookmarks to add
bookmarksToRemove
- bookmarks to remove
Returns: XML representation of bookmarksPDFPopulateForm ( 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
andvalues
.
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>
<Title Action="GoTo" Page="2 Fit" Style="italic">page 2
<Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title>
</Title>
<Title Action="GoTo" Page="4 Fit" Style="italic">page 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> <Title Action="GoTo" Page="2 Fit" Style="italic">page 2 <Title Action="GoTo" Page="3 Fit" Style="italic">page 3</Title> </Title> <Title Action="GoTo" Page="4 Fit" Style="italic">page 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 PDFPDFSetErrorCapture ( 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: PDFSaveReturns: 1 if the field was successfully set, or ERROR if there was no such field in the formPDFSplice ( 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 specifiedpageNumbers
from thesourcePDF
.PDFVersion ( )
Returns the version of the plugin which is installed.
Returns: version, or"ERROR"
on failure.
Parameters:Returns: PDF with specified bookmarks.PDFAddObject ( objectName { ; key1=value1 ; key2=value2 ; ... } )
Parameters:
PDFCreate ( { key1=value1 ; key2=value2 ; ... } )
Create an empty PDF.
Parameters:See also: PDFLoadReturns: 1 on successful PDF creation, "ERROR" if there was an errorPDFGetFieldValue ( field )
Returns the value of a named field in the PDF form.
Parameters:See also: PDFSetFieldValueReturns: 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:Returns: return separated listPDFInsertPages ( 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 thebookmarks
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