Technical Guide

Adding new document types to Adobe LiveCycle PDF Generator ®

®

A technical guide for using LiveCycle PDF Generator software Table of contents 2 Supported file types 2 Scripted architecture of PDF Generator 3 Component interactions 4 About the script and dialog XML files 5 Dialog box and window element terminology 5 Hierarchy 6 Script XML files 6 Dialog XML files 7 Adding or modifying support for a native file format 9 Adding a filetype entry in the native2pdfconfig.xml configuration file 10 Creating an environment variable to locate the native application 10 Locating and editing the script and dialog XML files 11 Creating or modifying a script XML file for a native application 11 Creating or modifying an additional dialog box XML file for a native application 12 Modifying the general dialog box file 12 Additional dialog XML file 12 Conclusion

Adobe LiveCycle PDF Generator (PDFg) uses a combination of native C++ libraries and well-known desktop applications such as Microsoft Word and Adobe Acrobat® to execute the conversion to PDF from virtually any format. As a general rule, if Acrobat can convert a file format to PDF, then PDFg can do so as well. The ability to do a conversion does not translate into supported conversion, however. If a file format is not listed in Figure 1, then PDFg will need to be customized to add the support to meet the needs of a given implementation. PDFg uses a straightforward method for controlling conversions. It associates a file type, such as .doc, with a given converter through the PDFg administrator console. The goal of the conversion process is to render the highest quality PDF in the most efficient manner. Different methods are used to achieve this and it’s useful to understand these different methods to understand extending PDFg. For the purposes of this document, files that require a desktop editing application or native application in order to convert them to PDF will be called native file types. Examples of native applications are Word, AutoCAD, Excel, and Adobe PhotoShop®. Not all file formats are considered native file types, however. Non-native file types include PostScript, EPS, HTML, all image formats (.tiff, .jpg, and so on), because there are C++ or pure Java libraries used to convert them to PDF. Generally speaking, new native file types can be added to PDF Generator using the techniques described in this paper, while non-native file types cannot. Native file types are converted by opening the file in the native application and printing to PDF through the PDF print driver installed with Adobe Acrobat. In these cases, a script for the native application controls the UI during the file handling. These scripts are the key to adding or modifying the actions of PDFg with a given application or file type. In most cases, associating a file type is for converting it to PDF, but PDF Generator can be customized in different ways as well. Using the same techniques, you can modify the way PDF Generator interacts with Acrobat or you can add new file types for conversion/ processing. For example, you could use this method to optimize a PDF file (a modification) or to convert an .msg or a .PSD file to PDF (adding new file types). One caveat to this extensibility is Microsoft Office conversions. To optimize PDFg for Microsoft Office, these scripts have been replaced with calls to the Office and Acrobat COM APIs, which eliminates any customization for Office conversions. Any new file type added to PDFg will be associated with the GeneratePDF service. Only the processes for file types associated with the GeneratePDF service can be modified.

This technical guide defines the supported file types, discusses the PDF Generator architecture, and describes how to add new file types to the PDF Generator service with links to the Adobe LiveCycle SDK references that you’ll need to understand the XML grammars. Supported file types The native files can be problematic if they are generated by an older version of the native application. To avoid rendering issues or bugs in the conversion process, PDFg has a rigorous testing process using thousands of files. PDFg is configured to communicate with a single installed instance of the native applications. For each of the supported file formats, this is the latest commercially available version at the time LiveCycle ships. Use the release notes for specific instructions on which application to install to achieve the file support needed. The following chart describes the file extensions that are supported, the version of the native application to install, and the different version of the applications tested with each file type. Category

File extensions

Version to install

Application version of files tested

MS Office file formats

DOC, DOCX, RTF, XLS, XLSX, PPT, PPTX, PRJ, VSD

MS Office 2007

MS Office 95 MS Office 97 MS Office XP MS Office 2000 MS Office 2003 MS Office 2007

Open Office file formats

ODT, ODP, ODS, ODG, ODF, SXW, SXI, SXC, SXD

OpenOffice 2.3.1 OpenOffice 2.4 (available 03/08)

OpenOffice v2.2 OpenOffice v2.3 OpenOffice v2.4

PostScript file formats

Adobe PostScript, Encapsulated PostScript

Not applicable

Not applicable

Image file formats

BMP, GIF, JPEG, JPG, TIF, TIFF, PNG

Not applicable

Not applicable

AutoCAD file formats

DWF, DXW, DWG

AutoCAD 2007

AutoCAD 2005 AutoCAD 2006 AutoCAD 2007 AutoCAD 2008

Adobe file formats

PMD, PM6, P65, PM

Adobe PageMaker 7.0.1

Adobe PageMaker 7.0.1

PSD, PDD, and several other file extensions

Adobe Photoshop CS2

Adobe Photoshop CS2

FM

Adobe FrameMaker 7.2

Adobe FrameMaker 7.2

WordPerfect formats

WPD

Corel WordPerfect 11

Corel WordPerfect 10 Corel WordPerfect 11

PDF format

PDF

Acrobat 9 Pro Extended

Adobe Acrobat Professional 8.1

HTML file formats

HTM, HTML

Not applicable

None

Figure 1. File type support

Scripted architecture of PDF Generator This section provides an overview of the key elements of PDF Generator: 1. The interactions between the GeneratePDF service and the native applications used to convert native file formats into PDF 2. The steps for modifying the response that GeneratePDF provides to the native applications to change existing functionality 3. The interactions between the GeneratePDF service, the PDF Generator ES Application Monitor (AppMon) component, and native applications such as Microsoft Word 4. The role that XML grammars play in these interactions After completing this section, the reader should be able to understand the different roles each component plays in converting files to PDF and how to find the scripts used in PDF Generator’s operation.

2

PDF Generator uses the combination of administrative settings, such as Job Option settings on the desktop, in conjunction with scripts that manage GeneratePDF, AppMon, and the native applications to create a PDF file. The administrative settings are the global settings for PDFg but they can be overwritten by the commands in the scripts. Figure 2 contains a list of the information that PDF Generator uses and identifies whether it can be modified to create new functionality. Function

Description

Use for native file conversion

Administrative settings

This includes PDF settings, security settings, and file type settings. File type settings associate file name extensions with the corresponding native applications. File type settings also specify native application settings used to print native files.

This is used by the administrator to create settings available for all PDFg users. To change settings for an already supported native application, the system administrator sets the File Type Settings in the LiveCycle Administration Console. To add support for a new native file format, you must manually edit the file as described in “Adding or modifying support for a native file format.”

Script

This specifies interactions between PDF Generator ES and a native application. Such interactions usually direct the application to print a file to the Adobe PDF driver. The script contains discrete instructions that direct the native application to open specific dialog boxes and that supply specific responses to fields and buttons in those dialog boxes.

Generic dialog box instructions (AppMon script)

This references dialogs that might be common to several applications (or that might not be associated with an application in particular, such as a “Low Virtual Memory” dialog popped by Windows OS) file.appmon.global.en_US.xml.

This is used by PDF Generator to script application interaction. It might sometimes be necessary to add more dialog entries to this file but this is usually done by Adobe engineering.

Application-specific dialog box instructions (AppMon script)

This specifies how to respond to applicationspecific dialog boxes. The file that contains this information is appmon.[appname].dialog.[locale].xml (for example, appmon.word.en_US.xml).

Do not modify this file. To add dialog box instructions for a new native application, create an appmon.[appname].addition.[locale].xml file for it (see the following).

Additional application-specific dialog box instructions (AppMon script)

This specifies overrides and additions to application-specific dialog box instructions. The section presents an example of such information. The file that contains this information is appmon.[appname].addition.[locale].xml (for example, appmon.addition.en_US.xml).

PDF Generator ES includes script files for all supported native applications. You can modify these files using an XML editing application. To add support for a new native application, you must create a new script file, as described in “Creating or modifying an additional dialog box XML file for a native application.”

Files of this type can be created and modified using an XML editing application, as described in “Creating or modifying an additional dialog box XML file for a native application.” Important: You must create additional application-specific dialog box instructions for each native application your server will support.

Figure 2. Types of information used by PDF Generator

Component interactions This document uses the term native application to indicate the application used to produce a file format, such as Microsoft Word or Visio. PDF Generator ES converts each native file format by invoking the application associated with it and interacting with the application to print the document using the default printer. The default printer must have been set up as the Adobe PDF printer. The following illustration shows the components and drivers involved with native application support. It also mentions the XML grammars that influence the interactions. These grammars are described in “Types of information used in printing native file formats.”

3

Adobe LiveCycle Generator PDF Native Application Monitor, a LiveCycle Generate PDF component

AppMon Native Application (e.g.; Microsoft Word)

LiveCycle Generate PDF Service Native applications

Adobe PDF (a driver)

config XML, script XML, and dialog XML

PDF file

Administrative settings

(native2pdfconfig.xml) Association between file name extension and native application

Adobe PDF settings Security settings

Figure 3. Component interactions for native file conversion

AppMon is a server component that interacts with a native application in the same way a user would navigate through the dialog boxes presented by that application. For example, the XML grammars used by AppMon to instruct a native application such as to open and print a file would involve the following sequential tasks: 1. Opening the file by selecting File > Open 2. Making sure the Open dialog box appears; if not, handling the error 3. Providing the file name in the File Name field and then clicking the Open button 4. Making sure the file actually opens 5. Opening the Print dialog box by selecting File > Print 6. Making sure the Print dialog box appears The scripts that AppMon uses are the only vehicles available to control applications on the server without using a .COM API or other programmatic means. Use of AppMon is not limited to PDF generation and can be generalized for any use—though scripting for other uses in the PDF Generator context would have negative effects on PDF Generation. Because the applications are running on a server in the same way they would interact on the desktop, each new version needs to be validated to ensure the old script continues to perform. Dialog boxes for registration and updates should be disabled so that they don’t interfere with the AppMon scripts. About the script and dialog XML files PDF Generator and AppMon use several different script files to manage all of the interactions between the OS and the different applications involved with PDF generation. The Script XML files are the instructions used to generate a PDF from a specific application and are unique to each. They are created to mimic the way a user would navigate through the application dialog boxes for any given task. The script directs PDF Generator to respond to dialog boxes by performing actions such as pressing buttons, selecting or deselecting check boxes, or selecting menu items. The specific responses to known dialogs are specified in the appmon.global.[locale]. xml or the appmon.[appname].[locale].xml dialog XML files. These files are created by Adobe engineering to respond to the known conditions in the application and operating system.

4

There are some application interactions that can’t be scripted or are outside the standard feature set of PDF Generator. An example would be trying to access a floating menubar through AppMon. Another example would be some dialogs whose contents cannot be retrieved using standard Win32 APIs. These dialogs cannot be identified just by looking at them; you need to analyze them using third-party tools (such as Microsoft Spy++ or similar). Sometimes an unexpected dialog will appear when a file is opened or saved, and these interactions can’t be handled efficiently through a single script. The Dialog XML file manages these types of interactions so the application won’t hang while waiting for a response. Any subsequent call to the application that is hung will also fail, causing a cascade of failures that is caused by a single file error. Though rare, this is the key weakness to the PDFg Architecture because when a dialog is not managed the service will hang, waiting for the response until it times out. Dialog responses in this class are saved in the appmon.[appname].additional.[locale].xml file. When you add a new file type to PDFg, it’s very important to have a wide variety of files (the PDFg QE team uses 1,000s per file type) of that type so that all of the dialogs can be detected prior to deployment. Dialog box and window element terminology There are two ways to discuss the terminology for dialog boxes: from the internal perspective and the user perspective. • From the user perspective, dialog box subcomponents are items such as buttons, fields, and combo boxes. • From the internal perspective, or internal representation, the term window component is used. The internal representation of window elements is a hierarchy in which each window element instance is identified by labels. The window element instance also describes its physical characteristics and behavior. The difference between these two terminologies is that from the user perspective, the dialog boxes and their subcomponents manifest different behaviors. For example, some dialog box elements are hidden until activated by executing other parts of the dialog. From the internal perspective, no such issue of behavior exists. All window elements are available regardless of the execution of the user. The importance of the distinction is that the interactions cannot all be determined based on the visible behavior of the application. All of the interactions need to be taken into account, and the way to do that is through the internal perspective. This section and the LiveCycle ES (Enterprise Suite) SDK chapter called “XML Grammars for Supporting Native File Formats” XML Grammars for Supporting Native File Formats describe XML elements that provide AppMon with instructions. The LiveCycle ES SDK is included on the LiveCycle DVD and also available online at www.adobe.com/support/documentation/en/livecycle. These elements have names such as the dialog element and the window element. This document uses a monospaced font to distinguish XML elements. The dialog element identifies a dialog box that an XML script file can cause to be displayed, either intentionally or unintentionally. The window element identifies a window element (dialog box or the subcomponents of a dialog box). Hierarchy The following diagram shows the hierarchy of script and dialog XML. A script XML file conforms to the script.xsd schema, which includes (in the XML sense) the window.xsd schema. Similarly, a dialog box’s XML file conforms to the dialogs.xsd, which also includes the window. xsd schema. The chapter in the LiveCycle ES SDK, “XML Grammars for Supporting Native File Formats,” describes these XML grammars.

5

Dialog XML

Script XML

dialogs

application

ssttep p step st ep

abortMessage

step

acquiredWindow

expectedWindow

pause

window wi wind w ndow nd dow ow win win nd ndow dow window

window

Hierarchy of script and dialog XMLs

Figure 4. Hierarchy of script and dialog XML

Script XML files A script XML file specifies a series of discrete steps that direct the native application to navigate to certain window elements and then supplies responses to those elements. The majority of responses are text or keystrokes that correspond to the input a user would provide to a field, combo box, or button in the corresponding dialog box. The purpose of PDF Generator ES support for script XML files is to direct a native application to print a native file. However, script XML files can be used to accomplish any task that a user can perform when interacting with the native application’s dialog boxes. In most cases there will only be a single Script.xml file associated with any given application. The steps in a script XML file are executed in order, without any opportunity for branching. The only conditional test supported is a time-out/retry capability, which causes a script to terminate if a step does not complete successfully within a period of time and after a certain number of retries. In addition to steps being sequential, the instructions within a step are also executed in order. You must ensure that the steps and instructions reflect the order in which a user would perform those same steps. Each step in a script XML file identifies the window element that is expected to appear if the step’s instructions are successfully performed. If an unexpected dialog box appears during the course of executing a script step, PDF Generator ES searches the dialog XML files to determine the next course of action as described in the next section. Dialog XML files Running native applications displays a variety of dialog boxes. The dialog boxes can be generated by the operating system or by the application itself. When native applications are running under control of PDF Generator ES, system and native application dialog boxes are displayed in a hidden desktop. PDF Generator ES uses the dialog XML files to allow it to respond to unprompted dialog boxes in a way that facilitates the conversion process.

6

As mentioned earlier, there are several different dialog XML files available to PDF Generator. When the system or native application displays a dialog box that is not handled by the currently executing script XML file, PDF Generator ES searches the dialog XML files in the following order, stopping when it finds a match: 1. appmon.[appname].additional.[locale].xml 2. appmon.[appname].[locale].xml (Do not modify this file.) 3. appmon.global.[locale].xml (Do not modify this file.) If PDF Generator ES finds a match for the dialog box, it dismisses it by sending it the keystroke or other action specified for the dialog box. If the instructions for the dialog box specify an abort message, PDF Generator ES terminates the currently executing job and generates an error message. Such an abort message would be specified in the abortMessage element in the script XML grammar. If PDF Generator ES encounters a dialog box that is not described in any of the previously listed locations, PDF Generator ES incorporates the dialog box’s caption into the log file entry. The currently executing job eventually times out. The information in the log file can be used to compose new instructions in the appmon.[appname].additional.[locale].xml file for that native application. Adding or modifying support for a native file format This section describes the tasks to perform when adding new native file formats to PDFg or to modify support for an already supported native file format. The process is time consuming and prone to work/rework before a given application is ready for product. The reason for this is that identifying windows elements is not intuitive in all cases and the process is unforgiving—any missed action results in a hang. It takes expertise in both windows application development and writing XML scripts to support this. Set aside six to eight weeks to completely debug and deploy a new file type. The LiveCycle ES SDK contains examples of dialog and script XML files that can be used to get started with the process of adding new native file support. While there is no order required to do the following steps, each of them will need to be taken before a new native file will be supported by PDF Generator. There are examples later of the files that will need to be changed, but the LiveCycle SDK should be consulted for the full examples. For new changes to or addition of a native file type you will need to take the following steps: 1. Modify the Native2PDF_config.xml file to include a reference to the name of the new native application and the file extensions that are associated with it—obviously not needed for a modification of a file action. 2. Generate a new Script.xml file that contains the instructions for how AppMon will need to interact with the application. 3. Generate a new dialog.xml file that will manage the dialogs that are thrown by the application and not handled by the script.xml file. 4. Change optionally the global_dialog.xml or general_dialog.xml file to handle OS-level dialogs that the new application causes but that haven’t been needed by previous applications supported by PDFg. Most of the work will be focused on the script file that directs AppMon to print the file to the default printer—set to print PDF. PDFg interacts with these scripts through their names. For example, the files that control the use of Excel are: • Script XML - appmon.msexcel.script.en_US.xml • Dialog XML - appmon.msexcel.addition.en_US.xml The application name used in the script name is defined in the Native2PDF_config.xml.

7

Following are some best practices and issues to look out for when adding a new script or modifying an existing one. Determining if an application can be controlled through AppMon Not all applications can be controlled through AppMon. Specifically, applications that can move or detach the File Menu from the menu bar will not be customizable using AppMon. This is because the menu identifiers are different for these types of dialogs and the AppMon service has not been updated since they’ve become more widely used. You can use Microsoft Spy++ as well to determine if a given menu or dialog is going to be scriptable using AppMon. In all cases, if Spy++ can’t determine the window element names and contents then AppMon will be unable to control the dialog or menu. Microsoft Spy++ The dialog and script XML files require you to identify the window element (dialog box, field, or other dialog component) to which your dialog or script element is responding. For example, after a script invokes a menu for a native application, it must identify the window element on that menu to which keystrokes or an action are to be applied. You can easily identify a dialog box by the caption it displays in its title bar; however, you must use a tool such as Microsoft Spy++ to identify lower-level window elements. Method for identifying window elements Identifying window elements can be difficult. The lower level window elements can be identified through a variety of attributes, which are not externally obvious. Then each native application may identify its window element differently so there is no standard way to determine if all the elements have been addressed. As a result, there are multiple ways of identifying a window element. Here is a suggested order for considering window element identification. 1. Use the Caption itself if it is unique. 2. Use the Control ID, which may or may not be unique for a given dialog box. 3. Use the Class name, which may or may not be unique. Any one or a combination of these three attributes could be used to identify a window, but this method may not always identify a window element uniquely. The alternative is to use a window element’s index with respect to its parent. An index specifies the position of the window element relative to its sibling window elements. Be aware of these issues when identifying window elements • M icrosoft Spy++ displays captions by using an ampersand (&) to identify the caption’s hot key. For example, Spy++ shows the caption for one Print dialog box as Pri&nt. This presentation indicates that the hotkey is ‘n.’ Caption titles in script and dialog XML files must omit ampersands. • Some captions include line breaks. PDF Generator ES cannot identify line breaks. If a caption includes a line break, include enough of the caption to differentiate it from the other menu items and then use regular expressions for the omitted part (^Long caption title$). (Using regular expressions in caption attributes) • Character entities (also called escape sequences) should be used for reserved XML characters. For example, use & for ampersands, < and > for less than and greater than symbols, ' for apostrophes, and " for quotation marks. Additional limitations to identifying window elements • Most of the events sent to the application are static in nature. For example, if you would like to select a specific item in a pull-down list, you must know the relative positioning of that item in the list in advance. AppMon would not be able to search for that item in the list and select it irrespective of where in the list it occurs. This limitation does not apply to any text that you might want to type in any of the application’s windows.

8

• Certain dialogs popped up by various applications are such that AppMon (or any other utility similar to AppMon) is not able to read the contents of the dialog. We do not know how to classify such dialogs and also there is no way to get to know this information just by looking at the dialog. The dialog has to be examined by Spy++ to determine if it is a “normal dialog” or not. Adding a filetype entry in the native2pdfconfig.xml configuration file The following procedure explains how to update the PDF Generator ES configuration file to associate file types with native applications. To update this configuration file, you must use LiveCycle Administration Console to export the configuration data to a file. The default file name for the configuration data is native2pdfconfig.xml. Steps to update the PDF Generator ES configuration file: 1. Select Home > Services > Adobe LiveCycle PDF Generator ES > Configuration Files, and then select Export Configuration. 2. Modify the filetype-settings element in the native2pdfconfig.xml file, as needed following the steps in the next example. 3. Select Home > Services > Adobe LiveCycle PDF Generator ES > Configuration Files, and then select Import Configuration. The configuration data is imported into PDF Generator ES, replacing previous settings. Note: The name of the application is specified as the value of the GenericApp element’s name attribute. This value must exactly match the corresponding name specified in the script that you develop for that application. Likewise, the GenericApp element’s displayName attribute should be equivalent to the corresponding script’s expectedWindow window caption. Such equivalency is evaluated after resolving any regular expressions that appear in the displayName or caption attributes. In the following example, the default configuration data supplied with PDF Generator ES has been modified to specify that PNG files should be converted to PDF by Photoshop rather than the image converter. Note that other references to PNG file must be changed for this to work. Example: Modifications for directing additional image files to Photoshop (native2pdfconfig.xml)

Note: For this to work, the following entry in the …config.xml must be changed to omit the png extension:

-

Should be changed to:

-

9

Creating an environment variable to locate the native application In order for PDF Generator to use the native application, it must detect the location of its executable. This is done through the use of a system environment variable. The variable must use the format [applicationname]_PATH, where applicationname must exactly match the application name used in the XML configuration file and in the script, and where the path contains the path to the executable in double quotation marks. An example of such an environment variable is Photoshop _ PATH. After creating the new environment variable, you must restart the application server on which PDF Generator ES is deployed. To create a system variable in the Windows XP environment: 1. Select Control Panel > System. 2. Click the Advanced tab in the System Properties dialog box, and then click Environment Variables. 3. Click New under System Variables in the Environment Variables dialog box. 4. Type a name that uses the format [applicationname]_PATH in the Variable name box in the New System Variable dialog box. 5. Type the full path and file name of the application’s executable file in the Variable value box, and then click OK. For example, type c:\windows\Notepad.exe. 6. Click OK in the Environment Variables dialog box. Locating and editing the script and dialog XML files The script and dialog XML files are bound into the adobe-generatepdf-dsc.jar file. Use the existing files as an example by following the next instructions. Unpacking the dialog and script files 1. Navigate to C:\Adobe\LiveCycle8.2\deploy. 2. Open the file named “adobe-generatepdf-dsc.jar” in an archiving utility (such as WinRAR or WinZip). 3. Extract “appmondata.jar” inside the “adobe-generatepdf-dsc.jar” to a folder on your system. 4. Close “adobe-generatepdf-dsc.jar” and open “appmondata.jar” in the same application (WinRAR or WinZip). 5. Add new XML files to the “appmondata.jar” file or modify existing XML files in this file. Repacking the dialog and script xml files 1. Open “adobe-generatepdf-dsc.jar” in an archiving utility (such as WinRAR or WinZip). 2. Update the archive with the modified version of “appmondata.jar” in step 5. 3. Close the archiving application. Deploying the Modified Generate PDF DSC 1. Connect to the LiveCycle ES server using Adobe LiveCycle Workbench ES. 2. Navigate to the Components view. 3. Select the GeneratePDF service and right-click. In the context menu, choose Stop service. 4. Select the GeneratePDF service again and right-click. In the context menu, choose Patch service. 5. In the Open File dialog, navigate to the folder containing the modified “adobe-generatepdf-dsc.jar” and select this file. Click “Open.” 6. Finally, select the GeneratePDF service again and right-click. In the context menu, choose Start service. 7. Verify that your newly added/modified changes in AppMon XML scripts are operational.

10

Creating or modifying a script XML file for a native application If you want to direct files to a new native application, you must create a script XML file for that application. If you want to modify how PDF Generator ES interacts with a native application that is already supported, you must modify the script for that application. The script contains instructions that navigate through the native application’s window elements and that supply specific responses to those elements. The file that contains this information is appmon.[appname].script. [locale].xml (for example, appmon.notepad.script.en_US.xml). Identifying steps the script must execute Using the native application, determine the window elements that you must navigate and each response you must perform to print the document. Notice the dialog boxes that result from any response. For example, the steps will be similar to these: 1. Selecting File > Open 2. Specifying the path and then clicking Open 3. Selecting File > Print on the menu bar 4. Specifying the properties required for the printer 5. Selecting Print and waiting for the Save As dialog box to appear (The Save As dialog box is required for PDF Generator ES to specify the destination for the PDF file.) Identifying the dialogs specified in caption attributes Use Microsoft Spy++ to obtain the identities of window element properties in the native application. You must have these identities to write scripts. Using regular expressions in caption attributes You can use regular expressions in caption specifications. PDF Generator ES uses the java.util.regex.Matcher class to support regular expressions. That utility supports the regular expressions described java.util.regex.Pattern. (Go to the Java website at http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html.) Ordering the window and windowList elements You must order window and windowList elements as follows: • W hen multiple window elements appear as children in a windowList or dialog element, you must order those window elements in decreasing order, with the lengths of the caption names indicating the position in the order. • W hen multiple windowList elements appear in a window element, you must order those windowList elements in decreasing order, with the lengths of the caption attributes of the first windowList/window elements indicating the position in the order. Creating or modifying an additional dialog box XML file for a native application If you create a script for a native application that was not previously supported, you must also create an additional dialog box XML file for that application. Every native application that AppMon uses must have one and only one additional dialog box XML file. The additional dialog box XML file is required even if no unsolicited dialog boxes are expected. The additional dialog box must have at least one window element, even if that window element is merely a placeholder. Note: In this context, the term additional means the contents of the appmon.[applicationname]. addition.[locale].xml file. Such a file specifies overrides and additions to the dialog box XML file. You can also modify the additional dialog box XML file for a native application for the following purposes: • To override the dialog box XML file for an application with a different response • To add a response to a dialog box that is not addressed in the dialog box XML file for that application

11

The file name that identifies an additional dialog box XML file is appmon.[appname].addition. [locale].xml (for example, appmon.excel.addition.en_US.xml). The name of the additional dialog box must use the format appmon.[applicationname].addition. [locale].xml, where applicationname must exactly match the application name used in the XML configuration file and in the script. Note: None of the generic applications specified in the native2pdfconfig.xml configuration file have a primary dialog box XML file. Ordering windowList elements in a dialog XML file Ordering windowList elements that appear as children in a window element are done using the same method as described in creating the script XML file. (See “Ordering the window and windowList elements.”) Modifying the general dialog box file You can modify the general dialog box file to respond to dialog boxes that are generated by the system or to respond to dialog boxes that are common to multiple applications. For example, if the OS tends to throw a dialog box for a new file type that wasn’t before, use the means described previously for dialog XML files for this purpose. Additional dialog XML file The following example contains the additional dialog boxes for the Notepad application. These dialog boxes can be in addition to the ones specified by PDF Generator ES. The section in the LiveCycle ES SDK called “Dialog XML reference” describes the entire dialog box grammar. Example: Notepad dialog boxes(appmon.notepad.addition.en_US.xml)





The LiveCycle SDK The SDK includes sample XML files to use Microsoft Notepad to process any files with the file name extension .txt. Use the SDK to understand the specific grammars of the XML files. Conclusion This technical guide was created to provide a baseline to start the development process for adding or modifying existing conversions. PDFg uses a simple scripting and control language to instruct native applications to execute a File-Print gesture. Developers planning on adding a new file type to PDFg should plan for a four- to eight-week process depending on their experience with Adobe LiveCycle and the specific grammars needed by PDFg. There are limits to the extensibility. Applications with floating or detachable File Menus cannot be added to PDF Generator. If an application can be added, the connection is made through the native2PDF_config.xml file, which associates a file type with an XML script file. The process is essentially a programmatic mimic of the gestures used in the application’s UI. Each mouse click and dialog box must be determined and accounted for to reliably generate a good result. Microsoft Spy++ can be used to determine which window elements to control programmatically, and each of these elements will be called through the XML grammars.

12

Dialog boxes that may pop up during the conversion as information or error codes need to be taken into account when developing the extension. There are three dialog.xml files that will manage specific application dialog and those that come from the OS. In most cases, OS dialogs are already accounted for by the Adobe engineering team, but those thrown by the application must be accounted for. The testing process is straightforward. Simply use Spy++ during several conversions and conversion failures to determine the dialogs, and then track them in the .xml file. Adding or modifying existing applications within the PDFg architecture is straightforward. It will take some diligence to find all the dialogs and windows required to script the conversion but this is not a deep technical task. The steps are laid out in this document and there are specific examples in the LiveCycle SDK located on Adobe.com.

Technical guide feedback We welcome your comments. Please send any feedback on this technical guide to [email protected].

Adobe Systems Incorporated 345 Park Avenue San Jose, CA 95110-2704 USA www.adobe.com

Adobe, the Adobe logo, and LiveCycle are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are the property of their respective owners. © 2008 Adobe Systems Incorporated. All rights reserved. Printed in the USA.

95010488 03/08