Open Menu

Synergex Blog


Merging Data and Forms with the PSG PDF API

By Steve Ives, Posted on July 6, 2016 at 9:53 pm

When I introduced the PSG PDF API during the recent DevPartner Conference in Washington DC I received several questions about whether it was possible to define the layout of something like a standard form using one PDF file, and then simply merge in data in order to create another PDF file. I also received some suggestions about how this might be done, and I am pleased to report that one of those suggestions panned out into a workable solution, at least on the Windows platform.

The solution involves the use of a third-party product named PDFtk Pro. The bad news is that this one isn’t open source and neither is it free. But the good news is it only costs US$ 3.99, which I figured wouldn’t be a problem if you need the functionality that it provides.

Once you have PDFtk Pro installed and in your PATH you can then call the new SetBackgroundFile method on your PdfFile object, specifying the name of the existing PDF file to use as the page background for the pages in the PDF file that you are currently creating. All that actually happens is when you subsequently save your PDF file, by calling one of the Print, Preview or Save methods, the code executes a PDFtk Pro command that merges your PDF file with the background file that you specified earlier. Here’s an example of what the code looks like:

;;Create an instance of the PdfFile class
pdf = new PdfFile()

;;Name the other PDF file that defines page background content
if (!pdf.SetBackgroundFile(“FORMS:DeliveryTicketForm.pdf”,errorMessage)
    throw new Exception(errorMessage)

;;Other code to define the content of the PDF file

 

;;Show the results
pdf.Preview()

There are several possible benefits of using this approach, not least of which is the potential for a significant reduction in processing overhead when creating complex forms. Another tangible benefit will be the ability to create background forms and other documents using any Windows application that can create print output; Microsoft Word or Excel for example. Remember that in Windows 10 Microsoft has included the “Print to PDF” option, so now any Windows application that can create print output can be used to create PDF background documents.

I have re-worked the existing Delivery Ticket example that is distributed with the PDF API so that it first creates a “form” in one PDF file, then creates a second PDF file containing an actual delivery ticket with data, using the form created earlier as a page background.

I have just checked the code changes into the GitHub repository so this new feature is available for use right away, and I am looking forward to receiving any feedback that you may have. I will of course continue to research possible ways of doing this on the other platforms (Unix, Linux and OpenVMS) but for now at least we have a solution for the Windows platform that most of us are using.


PSG PDF API Moves to GitHub

By Steve Ives, Posted on May 28, 2016 at 11:05 am

This is just a brief update on the current status of the PDF API that I have mentioned previously on this forum. During the recent DevPartner Conference in Washington DC I received some really great feedback from several developers already using the API, and some very positive reactions from several others who hope to start working with it in the near future.

During my conference presentation about the API I mentioned that I was considering making the code a little easier to access by moving it out of the Code Exchange and on to GitHub. Well it turns out that was a popular idea too, so I am pleased to announce that I have done just that; you can now obtain the code from its new home at https://github.com/Synergex/SynPSG_PDF. And if any of you DBL developers out there want to get involved in improving and extending the API, we will be happy to consider any pull requests that you send to us.


Updated PDF API

By Steve Ives, Posted on October 16, 2015 at 11:24 am

A few weeks ago I announced that a new API called SynPSG_PDF had been added to the code exchange. Today I am pleased to announce that the API has been updated and, in addition to Windows, is now also supported on systems running Linux (32-bit and 64-bit), OpenVMS (AXP and IA64) and Synergy .NET.

Also, as a direct result of recent customer feedback, I have added a mechanism that allows a PDF file to be easily created from an existing text file with just a few lines of code. This means that existing report programs that already produce plain text output can be easily modified to produce PDF output with a small amount of code like this:

AttachFileExampleCode

If  you would like to check out the API you can download the code from https://resourcecenter.synergex.com/devres/code-exchange-details.aspx?id=245.


New Tools for Working with PDF Files

By Steve Ives, Posted on September 11, 2015 at 2:44 pm

For some time now the Synergy/DE Code Exchange has included an item called PDFKIT which essentially contains a set of DBL wrapper code that allows the open source Haru PDF Library to be used from DBL. The work done in PDFKIT was a great start and has been used successfully by several developers, but I don’t think that anyone would disagree with me if I were to suggest that it’s not exactly the most intuitive software to use, and it’s not exactly what you would call well documented either; just like the underlying Haru library!

So as time permitted for the last few weeks I have been working on what I hope is an improved solution. I certainly didn’t want to totally reinvent the wheel by starting from scratch, as I mentioned PDFKIT was a great start, but I did want to take a slightly different approach that I thought would be more useful to a wider number of developers, and I did want to make sure that complete documentation was included. What I came up with is called SynPSG.PDF, and it is available in Code Exchange now.

When you download and extract the zip file (SynPSG_PDF.zip) you will find that it contains these main elements:

  • pdfdbl.dbl
    • This is the DBL code that wraps the Haru PDF library and is taken directly from the latest version of PDFKIT.

    Haru PDF Library DLL’s

    • The same DLL’s that are distributed with PDFKIT. Refer to the documentation for instructions on where to place these DLL’s.
  • SynPSG.PDF.dbl
    • A source file containing the new API that I have created.
  • SynPDG.PDF.vpw
    • A Synergy/DE Workbench workspace that can be used to build the code, as well as build and run several sample programs that are also included (this is a Workbench 10.3.1 workspace and will not work with earlier versions of Workbench).
  • SynPSG.PDF.chm
    • A Windows help file containing documentation for the new API 

You don’t need to use the Workbench configuration that I have provided, if you prefer you can simply include the pdfdbl.dbl and SynPSG.PDF.dbl files into the build for your subroutine library. But remember that both of these files contain OO code, so you will need to prototype that code with DBLPROTO.

As you will see when you refer to the documentation, most things in the API revolve around a class called PdfFile. This class lets you basically do four things:

  1. Create a PDF file.
  2. Save the PDF file to disk.
  3. View the PDF file by launching it in a PDF viewer application.
  4. Print the PDF file to a printer.

I’m not going to go into a huge amount of detail about creating PDF documents or using the API here because these topics are discussed in the documentation, but I will mention a couple of basic things.

PDF documents inherently use an X,Y coordinates system that is based on a unit called a device independent pixel. These pixels are square and are 1/72 of an inch in each direction. The coordinates system that is used within pages of a PDF document is rooted in the lower left corner of the page which is assigned the X,Y coordinate 0,0. The width and height of the page in pixels depends on the page type as well as the orientation. So for example a standard US Letter page in a portrait orientation is 8.5 x 11 inches, so in device independent pixels it has the dimensions 612 x 792.

With most PDF API’s you work directly with this coordinates system, and you can do so with this API also, but doing so can require a lot of complex calculations, and hence can be a slow process. But often times when we’re writing software it is convenient for us to work in simple “rows and columns” of characters, using a fixed-pitch font. The new API makes it very easy to do just that, meaning that results can be produced very quickly, and also meaning that existing report programs (that already work in terms of rows and columns) can be easily modified to produce PDF output.

Here is an example of a simple row / column based report that took only a few minutes to create:

image 

Of course there are times when you need to produce more complex output, and the new API lets you do that too. To give you an idea of what it is capable of, here’s a screen shot of a mock up of a delivery ticket document that I created while working on a recent customer project:

image

As you can see this second example is considerably more complex; it uses multiple fonts and font sizes, line drawing, box drawing, custom line and stroke colors, etc. And although not shown on these examples, there is of course support for including images also.

The new API is currently available on Windows under traditional Synergy. It should be possible to make the code portable to other platforms in the near future, and .NET compatibility is definitely in the pipeline. The software requires the latest version of Synergy which at the time of writing is V10.3.1b. You can download the code from here:

https://resourcecenter.synergex.com/devres/code-exchange-details.aspx?id=245

It is early days for this new API and I have many ideas for how it can be extended and enhanced. I am looking forward to working on it some more soon, and also to receiving any feedback or suggestions that you may have.


RSS

Subscribe to the RSS Feed!

Recent Posts Categories Tag Cloud Archives