360Works PDF Plugin 1.42 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.

Error Handling/Reporting

When something unexpected happens, the plug-in will pop up a dialog showing what the error message is. 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.

When you call this function, it is set for that plug-in for as long as FileMaker is running, so if you want to do all of your own error handling, you can just set it to true once in your startup script. However, we recommend only turning it on when your script is prepared to check for errors, and then turning it off after finishing that section.

Whether or not you suppress the error dialogs, a plugin function will return the word ERROR if something goes wrong. It's a good idea to put your plugin functions in an 'If' statement so that you don't execute a bunch of script steps after something has gone wrong. If you'd like for your script to get the error message, you can get that by calling the PDFLastError function.

Here is an example of basic error reporting:

Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]
If [ $result = "ERROR" ]
    Exit Script[ "Error occurred: " & PDFLastError ]
Else
    ... do more stuff here ...
End If

Chaining Multiple Functions Together

Since the string "ERROR" evaluates to false when evaluated by FileMaker, and most plugin functions return a 1 when successful, you can chain multiple dependent plugin operations together using the "and" operator. However, in this case the result will be a 1 or a 0, not "ERROR". For example:

// chain multiple calls together
// if any of the functions fail, the calculation will
// short-circuit with a result of false,
// and none of the subsequent function calls will be evaluated.
Set Variable [ $success =
    FirstPluginFunction("x") and
    SecondPluginFunction("y") and
    ThirdPluginFunction("z")
]
If [not $success]
    Show Custom Dialog [ "An error occurred: " & PDFLastError ]
End If

Note: the above only works for plugin functions which return 1 on success! Check the documentation for each function used in this manner.

Additional Error Checking - Plugin not installed

If a plugin is not installed correctly, calls to a plugin function will return "?". As part of your startup script, you should check for this occurrence and display a warning accordingly that the plugin needs to be installed. Note: when treated as a boolean true/false value, FileMaker will treat ? as true.

Installation

Requirements

FileMaker version 11 or higher.

Java Virtual Machine (JVM) version 1.6 or later (32-bit). If you are running a JVM earlier than 1.6, you should upgrade. Download a JVM from http://www.java.com/en/download/. Apple has a 32-bit version of Java 1.6 here http://support.apple.com/kb/DL1572. If you are not sure what version of Java you have installed, you can do java -version on the command line in Windows or OS X.

Windows, or Mac OS X version 10.6 or higher.

Note to intel Mac users: running this plugin under Rosetta is not supported. Upgrade to FileMaker 8.5 to run our plugin in native Intel mode.

Install Steps for FileMaker Pro

Drag the plugin from the MAC or WIN folder into your FileMaker extensions, and restart FileMaker.

If the plugin does not load correctly, double-check that you meet the system requirements.

Install steps for Instant Web Publishing

You do not need to do this step unless you plan on using the plugin with Instant Web Publishing with FileMaker Server Advanced. You will need an Enterprise license to use this feature.

For installing into the Web Publishing Engine with FileMaker Server or FileMaker Server Advanced, drag the plugin from the MAC (.fmplugin file) or WIN (.fmx file) folder into the FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins folder. If there is no Plugins folder inside the wpc folder, then create it manually. Restart FileMaker Web Publishing, and now the plugins should be ready to go.

The easiest way to test whether the plugin is working is to have a calculation which calls the version function of the plugin, and display that on an IWP layout. If it shows "?", then the plugin is not working. If it shows a number, then the plugin has been installed successfully.

Install steps for Custom Web Publishing

If you are using FileMaker Server 12.0v1 or earlier, you can follow the same procedure as detailed above for custom web publishing. However, in FileMaker Server 12.0v2 and later, the custom web publishing now runs as a 64-bit application, and requires a slightly different location. You will need an Enterprise license to use this feature.

For Mac, the single plug-in file in the MAC directory contains both 32-bit and 64-bit versions. For Windows, look for the plug-in that has the extension .fmx64 and use it in exclusively in custom web publishing.

To install 64-bit plug-ins, install either the .fmx64 or the .fmplugin to the following directory:

FileMaker Server / Web Publishing / publishing-engine / cwpc / Plugins

If it does not exist, create the Plugin folder manually. Restart FileMaker Web Publishing, and then you can then test a script that contains a plug-in and see if it returns the correct values.

Please note that plug-ins do not work with the web publishing engine of the Mac version of FileMaker Server 8.0v4.

Install steps for server scheduled scripts

You do not need to do this step unless you plan on using the plugin with scheduled script triggering. You will need an Enterprise license to use this feature.

  1. Drag the plugin from the MAC (.fmplugin file) or WIN (.fmx file) folder into the FileMaker Server extensions folder. On Mac OS X, this is located at /Library/FileMaker Server/Database Server/Extensions folder. On Windows, this is at C:\Program Files\FileMaker\FileMaker Server\Database Server\Extensions.
  2. In the Server Admin application, restart FileMaker Server by stopping and starting it.
  3. Go to Configuration -> Database Server->Server Plug-ins and check the box that says 'Enable FileMaker Server to use plug-ins', and then check the 'enabled' box for this plugin. Click the 'save' button and wait a few seconds to make sure that the 'enabled' check box stays checked. If it does not, then there was an error loading the plugin and you should contact us for help troubleshooting. You should now be able to write schedules that trigger scripts which use the plugin.

Auto Update

360Works has created an AutoUpdate helper database which makes setting up Auto Update much easier. This file includes pre-configured plugin files which you can place on your server, and an auto-update script for each of our plugins which you can paste into your own solution.

You can get the AutoUpdate360Works file at fmp7://autoupdate.360works.com/AutoUpdate360Works or fmp://autoupdate12.360works.com/AutoUpdate360Works. Follow the instructions included in the file to either host your own Auto Update server or pull the files from ours.

Uninstalling the plugin

Uninstall the plugin by quitting FileMaker Pro or stopping FileMaker Server and removing the plugin file from your Extensions directory.

Demo mode and Registering the plugin

Plugins will run in demo mode until they are registered. While running in Demo mode, the product will run for 2 hours every time you launch FileMaker / FileMaker Server / FileMaker Web Publishing Engine. The 2 hour time limit will reset every time you relaunch FileMaker. There is no expiration date when Demo mode stops working. There are no feature differences between the Demo version and the licensed version.

Once you have purchased the plugin, you can register it with the license key. Once a valid license key is entered, the product will run for as long as FileMaker is running. After FileMaker starts up with the plugin installed, open FileMaker preferences, click on the Plug-ins tab, select the plugin from the list, and click the Configure button. Enter your license key and company name in this dialog. You will only need to do this once on a given machine. Alternately, you can use the registration function to register the plugin during a startup script.

Note that if you are running the plugin with FileMaker Server / FileMaker Web Publishing Engine, you must use the registration function to register the plugin, since there is no preferences dialog on FileMaker Server to enter the license key and company name.

Feedback

We love to hear your suggestions for improving our products! If you are experiencing problems with this plugin, or have a feature request, or are happy with it, we'd appreciate hearing about it. Send us a message on our website, or email us!

Function Summary

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>
		    <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: 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 ; ... } )

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 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>
		    <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 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.