Provide access to page number, pages coordinates and width/height of items to possible PDF post-processors

[hvbtup]

See https://bugs.eclipse.org/bugs/show_bug.cgi?id=407974

BIRT is an excecellent solution for creating PDF reports.
However, there are cases where BIRT's capabilities are not sufficient - and where these capabilities should not be added to BIRT itself.
We don't want BIRT to become a "jack of all trades" (don't know if this the right expression :-) or "eierlegende Wollmilchsau" in German.

For example, in some cases you want to add a visible digital signature to the PDF generated by BIRT at a certain place (depending on the content). For that, you would use other software, but that software must know where exactly to place the signature (yes, I know, often this software can scan the PDF for a special "code word" in the text).

Other examples may be when you want to add an existing PDF, SVG or whatever at a certain place afterwards.

All this could be greatly simplified if BIRT would allow to access the following properties for a layout item instance:

• name or id of the corresponding design element
• page number
• rectangle (in absolute PDF coordinates).

It doesn't matter if this is for the first page, last page or every page where the item is rendered, because in reality the item will have page-break inside:avoid anyway and will fit onto a single page.

As a developer, I could then e.g. add an empty 1x1 grid of fixed size and name it "signature-placeholder" and mark this item somehow as "export-rendered-position".
The code calling the report could then ask BIRT after the RunAndRenderTask or RenderTask for a list of those items.
It would find an item with the name "signature-placeholder" in this list and e.g. the information that this was rendered on page 3 with a rect of bottom=200, left=180, width=92.5, height=88.3 (in PDF units (=points IIRC)".

A natural choice for this could be objects with a bookmark.
For these the necessary data will appear in the generated PDF anyway.

So one possible solution without changing BIRT would be to use iText (or any other PDF) after the PDF has been generated by BIRT and examine the PDF with that library.

But probably BIRT knows that information internally anyway, so it would be nice if BIRT provided an API to extract it after rendering.
That way it wouldn't be necessary to parse the generated PDF with a different library at all, so it would be faster and more memory efficient.

[hvbtup]

I created #812 for this.

Probably it would also be possible to export the TOC in a similar way, and maybe that approach could even be extended to support section-wise page numbering based on the TOC or to add a visible TOC.

[hvbtup]

export_bookmarks.zip

Created a new PR #819 for this. The attached ZIP contains a sample report created with this code. The report displays the info in afterRender and afterFactory events to demonstrate it. stderr.txt shows the output.

[TheLaserNinja]

I added a PDF append feature for adding things like legal docs and signature sheets to PDF renders during the Render phase a few version back. It basically does a post-processing of the PDF to append a separate set of PDF's to the end of a render. It's already in the product. Let me know if something like that would work.

In addition, I don't recall if BIRT provides all of that information in the emitter layer. It's been a few years since I wrote any in depth emitters. What I remember is that there are two different distinct render types, one for HTML type layouts, and one for content with coordinate renders. So the HTML, XML, and JSON emitters all use the HTML type, and the PDF, JPG, Office (I think) all used the content emitter. I had written an article for IBM Developerworks some years back that explained how the emitters work in detail (I believe Jason also included that same info in Integrating and Extending BIRT), but it looks like IBM scrubbed those articles recently. I can see if I can find the basics that explain how they work.

[hvbtup]

I'd definite like to see that article!
It is very hard to understand how BIRT actually works from looking at the source code. An overview would be very helpful.
For example, what is the purpose of layout vs. nlayout ?

I already saw the PDF append feature.
It serves a different purpose, though - appending a PDF vs adding content at certain locations inside the PDF.

In our commercial software we are using a different tool (outside of BIRT) to append PDFs later, but the ability to do this with BIRT directly is a very nice feature nevertheless, and your solution will be good enough for many use-cases.

I'm not totally satisfied with it because the page numbering is very basic (eg using a built-in font will prevent PDF/A compatibility).

Maybe some of the code could be reused, for example to support something like an "image with PDF content".

For our users, the PDF output format is by far the most important, so I always think about possible improvement.
For example, improving the "auto-text" page numbering: With the currrent RunAndRenderTask it is not possible to provide "page n of m" right-aligned and we don't have "grouped page numbering". That's why in our commercial solution we have a work-around for this including Javascript in the report, the appContext and Java code running after BIRT has generated the PDF, using the info in the appContext to add page numbers e.g. based on the TOC.
If I understand cocrectly, the auto-text creates /XObjects in the PDF (that is placeholder rects for which the content will be created later on). If the content would'n be just the current page number or the total page number, but a template string like "{page} of {numpages}" this would allow right-aligned output and also TOC-based grouped pages numbering.

The fact that the emitter is able to export the page/rect location of items in the PDF opens a lot of opportunities to modify the PDF with tools outside of BIRT (eg. adding electronic signatures) as well as inside BIRT.