Tech Tip

How to create a PDF Form Overlay

by Gary Rogers, APPX Director of Training and Consulting

There have been a lot of inquiries on how to create a form overlay in APPX.

A PDF form overlay is a predefined image, or electronic form, that is printed underneath the data associated with the process. The use of form overlays eliminates the need for preprinted forms or creating the forms from scratch in Application Design. This article explains the basic concepts of creating an output process using a form overlay.

In most cases when data and a form are merged the data is printed first and the form is laid over the data (thus the term overlay). APPX works exactly the opposite. The form is printed as an image, and then the data is printed on top of the form.

It is best if you can find an image that is scaled close to your form size. The less scaling that needs to be done when the PDF output is created, the less chance you will have blurred or distorted images. It may also be necessary to create a form definition in System Administration that matches the size of the image you are using.

I have a PO form that prints on a letter sized page. I added a form named PDF-6P10 that is a type PDF with a form length of 60 lines and a width of 80 characters. On the second page of the Forms definition, I set the top and bottom margins to .5 and the left and right margins to .25.

The overlay image is a .png file named POForm.png. Although Appx accepts .jpg, .gif and .png images, .png images are recommended as they provide a more portable format, good compression, and you will not have to be worried about active channels and other image related issues.

1. The first step is to obtain or develop the electronic form you wish to use in your output process and create the APPX form definition as described above. You can scan a form, but it is very difficult to get the scanned image straight.
2. Place the image where it will be accessible to your process. The most convenient location is the $APPXPATH/vv/aaa/Resource directory where vv is the application version and aaa is the application id.
3. In Application Design add a Named Resource (PO FORM). The State will be ENABLED. That is the active state when creating a PDF document. Set the Type to the value that will point to where you placed your image. In this case I chose Design File since the POForm.png file is in the Resource directory. If you place all your images in a common location you may need to use Server File. The Location is the name of the image file, POForm.png. If you use any Type other than Design File you will need to enter the fully qualified path to the image. On Linux or Unix platformst, make sure that you match the case in the Location to that of the actual file name in the Resource directory.
4. Now create an output process. In this example the form is letter size so the output process would be designed with Columns set to 80, Standard Page heading set to No, Standard Column headings set to No, and the default Separator character (=) would be removed.
5. Set the Preferred Form in Additional Attributes with the form name added for this image, PDF-6P10 in my example. This is an important step. The Image editor will scale the image in design to the size of the preferred form so what you see on the screen will be in the same aspect as what prints. If you do not use a default form APPX will use a form defined to print on an 8 ½ x 11 page with portrait orientation, 6 lines per inch, and 10 characters per inch.
6. Select PAGE-START for the first output frame and set the rows for the image to the length of image you will be using. In this example the form is length 60.
7. Navigate to the image editor and select the Picture icon from the toolbar. Starting in row 1, column 1 drag out a box the size of the entire image editor display area. You only need to enter the Resource name you added above, PO FORM in the GUI attributes screen (don’t forget to include the Application ID). If you like, you could set a border type and color. Click the Save button to get back to the image editor.
8. Page the image editor screen down a page (Ctrl-down arrow) and drag the bottom of the Picture widget to the bottom of the display area. Repeat this step until you are at the bottom of the display area, line 60.
9. If the image is not in scale you can edit the Picture properties and set the scale to a number that fits your liking. This might be a trial-and-error process until the image looks the way you want. If you cannot get it to look right, it may be necessary to adjust the image with an editing tool, such as Paint or Photoshop. There are literally hundreds of editors available, free and otherwise.
10. Save the image and return to the Frame level. Reset the rows to 1, or to the number of rows needed for any data you will print in the heading.
11. Add frames as needed to complete the output process. Place the fields on the image area for each frame, starting in the row and column locations based on the layout of your form. This may not be exact to your form the first time you print it out, but you can use micro-adjustments to place the fields exactly where needed.

How This Works

APPX processes all outputs the same, whether the output is a text file or a PDF file. Each frame is executed in sequence and prints each line one after the other. When the number of lines exceeds the length of the defined form any Page-End and Page-Start frames are processed, and processing continues until all records are processes. The difference between text and PDF is that PDF output is more like printing an image rather than text. That allows us to anchor a 60 line long image, such as the POForm, in a single cell. The result is a form that prints over the entire page, but as far as APPX is concerned it is on a single line. That is why it is important to change the frame’s length back to the minimum size needed to print your data. If the frame size is left at 60 lines, then APPX would print the frame, count 60 lines printed, invoke the page end and page start routines, count 60 lines printed again, and the process would end up in a loop.

Since APPX treats the POForm image as a single line subsequent images are printed on the succeeding lines, printing over the top of the POForm image. There you have it, a form overlay.

One thing to consider when using this technique is layering. APPX prints each widget and text area in order. There are no hard and fast rules to follow and at this time there are no controls to tell APPX to process one image before another. Because of layering, sometimes the form’s image prints after data that may be included on the frame, causing the data to disappear (the form is layered over the data). If that occurs you may need to create a 1 line Page-Start frame that has only the form widget on it and move the data to a second Page-Start frame. In this case you may lose the option to print data on the first line of the form.

Comments:

Read what other users have said about this page or add your own comments.