Parameter Parsing / Embedded Commands
Introduction
Parameters:
| Email sending | |
| SavePDF | Save to a file name |
| AppendPDF | append a PDF |
| InsertPDF | insert a PDF |
| OpenPass | Set the Open password |
| PermPass | Set the change permissions password |
| Stationery | Set the PDF stationery |
| DigSig | Apply the digital signature |
| Embed | Embed a file |
| InsertImage | Insert an image |
| SplitPDF | Split a large PDF into smaller PDF's |
| bm | Set a bookmark |
| Print PDF to another printer | |
| Examples |
Introduction
Parameters or "Embedded Commands" can be entered into the originating document to instruct pdfMachine on particular actions to take when generating the PDF.
e.g. If the text:
#_ savePDF C:\tmp\savedfile.pdf _#
appears in a Word document and it is printed to
pdfMachine with parameter parsing enabled the file will be automatically saved
to c:\tmp\savedfile.pdf and no
pdfMachine user interface will be displayed.
If parameter parsing is
enabled, pdfMachine will parse the PDF file for the specified parameters listed
above and described in detail below. These parameters control both the content of the generated PDF file (eg
inserting images, replacing keywords with text) and the way that pdfMachine
works (eg setting passwords, emailing the PDF, saving the PDF).
This is particularly useful for integration with legacy software to do "mail merge" type operations.
WARNING: Parameters in pdfMachine can be very powerful and complex.
Please test each configuration thoroughly before using in a production
environment.
How to use Parameter Parsing
1) Turn it on
Check the "Enabled" check box in the Parameter Parser tab of the pdfMachine Options dialog to turn parameter parsing on. Enabling parameters will slow processing of pdfMachine down a little, so don't do it unless you need them.
After parsing the parameters pdfMachine will either remove from or leave in the parameters from the resultant PDF file as selected by the radio buttons in this dialog.
The parameter parsing is done using the "Perl-Compatible Regular Expressions" library developed by Philip Hazel. A regular expression is a pattern that is matched against a subject string from left to right. For a detailed explanation of regular expressions, please read:
http://home.att.net/~robertdunn/Papers/RegExpSyntax.html
The default regular expression used is: #_ (\w+) (.+?)_#
We recommend this regular expression is not changed without a good
understanding of regular expressions. Should this accidentally be changed it can
be corrected using the default regular expression described on this page.
If you need to change the regular expression, it is stored under the following
registry entry:
HKCU\Software\pdfMachine\RegExp
The default regular expression will allow parameters to be entered into the
originating document in the following format:
#_ parameter argument(s) _#
Note: A parameter and an argument list for that parameter must both be specified, even if the arguments are not used, at least 1 argument must be present. For example:
A valid entry for setting a digital signature in the PDF file is : #_ digsig 1 _#
An invalid entry for setting a digital signatures is : #_ digsig _#
2) Create the originating document with appropriate parameters
The parameters are not case sensitive. Choose from the parameters listed below:
Sending an email with the PDF Attachment
The following parameters can be used to cause pdfMachine to email the resultant PDF. See example.
| Parameter | Description |
|---|---|
| Arguments: Comma separated list of email addresses to send to. e.g. #_ email dave@broadgun.com _# |
|
| EmailCC | Arguments: Comma separated list of email addresses to cc to. e.g. #_ emailCC dave@broadgun.com _# |
| EmailBCC | Arguments: Comma separated list of email addresses to bcc to. e.g. #_ emailBCC dave@broadgun.com _# |
| EmailSubject | Argument: Subject of email e.g. #_ emailSubject Your invoice is attached _# |
| Emailbody | Argument: Text body of email. May span across multiple lines. e.g. #_ emailBody Hi, Please find attached a very useful PDF file. Best Regards, The Boss. _# |
| EmailAttachmentName | Argument: Name to use for attached PDF file e.g. #_ emailAttachmentName invoice.pdf _# |
| MergeField |
Arguments: fieldname value
The MergeField parameter allows the contents of the Email to be customized to a finer detail. That is, the subject, body and attachment name can be set in the pdfMachine options screens. The {} characters can be used to define field names within these and then the MergeField parameter used to set these field names. See example. MergeField can only be used when the Email parameter is set. Takes a fieldname to replace, and the value to replace that fieldname with. The mergeField is applied to the EmailSubject, EmailBody and EmailAttachment name settings. e.g. #_ MergeField first_name Fred _# This will replace all occurrences of {first_name} in the subject, body or attachment name settings, with the word Fred. |
Save the PDF File
The following parameter causes pdfMachine to automatically save the resultant PDF file to the specified location.
| Parameter | Description |
|---|---|
| SavePdf | Argument: Path to the location to save the PDF file e.g. #_ SavePdf C:\savedFileHere.pdf _# |
Inserting or Appending PDF Files
The following parameters insert or append files into the resultant PDF file .
| Parameter | Description |
|---|---|
| AppendPdf | Argument: Path to the PDF file that is to be appended. e.g. #_ AppendPDF c:\somefile.pdf _# Multiple appendPdf parameters can appear in the file which will result in multiple PDF's being appended. See example |
| InsertPdf | Argument: Page number after which to insert ( 0 to insert at the start of file), path to the
PDF file to
insert.
See example. |
Encryption
The following parameters cause pdfMachine to enable encryption and to set the appropriate passwords in the resultant PDF file.
| Parameter | Description |
|---|---|
| OpenPass |
Argument: Password required to open the
document (a.k.a. user password). e.g. #_ OpenPass mysecret _# NOTE : Set the other encryption parameters in the pdfMachine options screens. |
| PermPass | Argument:
Permissions password (a.k.a. owner
password).
e.g. #_ PermPass mysecret _# NOTE : Set the other encryption parameters in the pdfMachine options screens. |
Stationery
| Parameter | Description | ||||||
|---|---|---|---|---|---|---|---|
| Stationery | Arguments: pages drawn path
e.g. #_ Stationery all above c:\stationery.pdf _# |
Digital Signature
The following parameter causes pdfMachine to Inserts the selected digital signature at the current place in the file.
| Parameter | Description | ||||
|---|---|---|---|---|---|
| DigSig | Argument: visible enabled
e.g. #_ DigSig noshow _# NOTE : the DigSig parameter *must* be followed by at least one other piece of text so that the regular expression can find it. Anything other that the parameters shown above are ignored, so it is fine to just put something simple like '1'. e.g. #_ DigSig 1 _# NOTE : Set up the other signature details in the pdfMachine options. |
Files Attached / Embedded within the PDF
The following parameter causes pdfMachine to attach file(s) to the resultant PDF file. The attached files can be seen in the attached files list in Acrobat Reader 6 and 7.
| Parameter | Description |
|---|---|
| embed | Argument: Path of the file to be embedded. e.g. #_ embed C:\afile.pdf _# #_ embed C:\somefile.pdf _# Call embed multiple times to embed multiple files. See example. |
Insert Image
The following parameter causes pdfMachine to insert images into the resultant PDF file.
| Parameter | Description | ||||||
|---|---|---|---|---|---|---|---|
| InsertImage | Arguments: width height path e.g. #_ InsertImage 100 100 C:\somefile.jpg _#
Note: 1 point = 1/72th inch InsertImage can be called more than once per page. |
Split Document
| Parameter | Description |
|---|---|
| SplitPDF | Argument: dummy argument to help regular expression parsing e.g. #_ SplitPDF 1 _# Note the SplitPDF parameter must be followed by some other text, which is '1' in this case. Splits document at the end of the current page. This should be used with extreme caution, as it may result in multiple emails being sent for a single print job. Please be sure you do adequate testing to ensure the emails are as you wish. see example Make sure that there is no more that one SplitPDF command on a single page. This can be useful for integrating with a legacy application that creates one big print job with each customer statement on a new page. e.g. An accounting application may print out a number customer invoices, one after the other in one big print job. Normally this would generated 1 large PDF. However, using a combination of "SplitPDF" and "email" parameters each customer would be emailed a unique invoice belonging to them. |
bookmark
| Parameter | Description |
|---|---|
| bm | Argument: bookmark name\sub bookmark name A back slash separated list of heading names, forming a table of contents or bookmark hierarchy. Bookmarks provide a table of contents and usually represent the chapters and sections in a document. Bookmarks appear in the navigation pane of adobe reader. When a bookmark is clicked, the reader will be presented with the section where the "bm" command was placed. e.g #_ bm This is a top level bookmark _# #_ bm This is a top level bookmark\sub section 1 _# #_ bm This is a top level bookmark\sub section 2\more news _# Produces PDF with a bookmarks window in Adobe Reader: 
|
| Parameter | Description |
|---|---|
| Argument: printer name Used to print to a secondary printer. This could be useful if a hardcopy is desired as well as the PDF. If the word "default" is used for the printer name the default printer is used. e.g 1 - Print to a specific printer name #_ print HP Office Jet v49 _# e.g 2 - Print to the default printer #_ print default _# |
|
Examples
Sending an email
Print the following text to pdfMachine to send an email to user@broadgun.com, with the
attachment called "mypdf.pdf" and the subject "pdfMachine is
great" and the body "Hi, Please have a look at the attachment." (spread over
2 lines).
|
#_ email user@broadgun.com _#
#_ emailsubject pdfMachine is great _# #_ EmailAttachmentName mypdf.pdf _# #_ Emailbody Hi, Please have a look at the attachment. _# This is the attachment text, it will appear in the PDF. |
Sending an email with the PDF Attachment using the MergeField parameter
Set the pdfMachine options to have the email configuration as below:
Print the following text to pdfMachine to send an email to john@yourserver.com, with the attachment called "subscription.pdf" and the subject "Subscription expires on 1st March 2006" and the body "Dear John Your subscription to our magazine will expire on 1st March 2006" (spread over 2 lines).
#_ email john@yourserver.com _# |
Appending PDF file
Print the following text to pdfMachine to append the contents of the file 'one.PDF' and 'two.pdf' into the resultant PDF.
|
#_ appendPdf c:\one.pdf _# #_ appendPdf c:\two.pdf _# Put any text here , this forms the main pdf. |
Inserting PDF file
Print the following text to pdfMachine to append the contents of the file otherPDF.PDF into the resultant PDF at the start of the file.
|
#_ insertPDF 0 My Documents\otherPDF.pdf _# Put any text here - this will appear after the contents of the file otherPDF.pdf |
Attaching/Embeding files
Print the following text to pdfMachine to embed files in the resultant PDF.
|
#_ embed c:\somefile.txt _# #_ embed c:\anotherfile.txt _# Put any text here - this will appear as the contents of the PDF file. The PDF file will have an "attachments" window containing the two text files. |
Splitting single print job into multiple emailed documents - SplitPDF
Print the following text to pdfMachine to send two emails.
|
#_ email john@yourserver.com _#
Customer Name: John .. #_ email dave@yourserver.com _#
Customer Name: Dave
|