Generating Reports with JavaScript

Dave Wraight Planet PDF Contributing Editor

May 17, 2004

Advertisement
Advertisement

Another underused tool in our Javascript toolkit is the Report Object. This object provides a mechanism to create detailed reports on almost anything that comes to mind.

For example we could generate a report on the annotations in a document, detailing their type, content, destination (if any), author, date of creation etc. We could also generate a report across a whole series of PDF files using the Batch Processing function.

The examples that are included with Acrobat 6 Pro (in the Annots.js) really highlight the potential uses for reporting.

Hopefully through this exercise you can get a better appreciation of what the Report object is and also how you might be able to make use of it.

The Report object has been around since version 5 and there have been very little changes to the way it operates. So this means that the code we use here although it's being used in an Acrobat 6 context should stil apply to version 5.

What is this Thing?

Effectively the Report Object is a blank canvas. The difference between this blank canvas and other blank pages is that this one has rules for positioning, tools for laying out and methods to create a finished PDF document from your handywork.

One thing to keep in the back of your head when using the Report object is that it's not InDesign or PageMaker, it's a simple and effective way to place text on the page in determined locations.

The other point to make mention here is that the Report object is like a container, as you change settings and write text to it, it keeps filling up -- it's not until you generate the report will any of the text display in the final PDF.

How does it Work?

It's really simple. Firstly you create your object:

var myReport = new Report();

Note: The documentation has a little error that states the constructor [new Report()] doesn't return anything, well this isn't the case -- it actually returns a Report object.

Then you write onto your blank canvas using the methods provided. For example if we wanted to put a header at the top of the page:

myReport.writeText("My First Report");

Here we are using the writeText method from the Report object to put text onto the page.

The Report object is actually similar to an open file, we open the file and continue to add text to it. However, there's no mechanism to go back to correct mistakes or alter position of text or change colors, it's a forward moving process.

So where exactly does the text go? Well the Report object is taking care of a lot of the details for us, the title "My First Report" has a default size and color and of course a default location.

So this brings us to the next part: How do we change these things?

Color, Size and Position

These three properties give us a little bit of control over how the report will actually be laid out. The best part about the Report object is that pagination and text flow are taken care of for us automatically, we don't have to worry about how much text is on the page and of course creating new pages to put the text onto -- this has a side effect: what if we wanted to control it? The answer is you cant -- yet (perhaps the next version of Acrobat will give us more control).

We have the following properties available to us when we use the Report Object:

• color
• size
• style (new in version 6)

To change the color of the text we simply update the property:

myReport.color = color.blue;

The following colors are predefined by the Color object:

You can also make your own colors:

myReport.color = ["RGB",0,0.5,0.5]; // Greeny-Blue color

The font size can be controlled by adjusting the 'scale' of the font, that is to say this size number is simply a multiplier:

myReport.size = 1.3;

The above simply makes the font 3 times bigger than the default font size.

Now that we know how to change the color of the text and also its size, what about the positioning? The easiest way to position text is to make use of two methods:

myReport.indent();
myReport.outdent();

Since this isnt page design and layout we are restricted to indenting and outdenting, kinda like the old days of programming ;) The Tab is your friend and you quickly learn how to lay your pages out using the simplest of tools.

As far as positioning is concerned we have the above two methods, and we also have another method that gives us more control on the absolute position of the indentation: myReport.absIndent(). I wont go into to much detail about this method except to say that it takes a bit of tuning to make it work correctly and indentation overflows are not taken care of for your automatically.

At this point we have some layout control and of course we can change the color of the text and lastly we can resize our text as we create the report.

An Example Report

In our example I've built a report that whizzes round a bunch of selected PDF's and extracts the document information, number of pages, number of form fields, file size and file name. There are three parts to this example, the first part declares some global variables -- one of which is the Report Object -- this code has been attached to a form field button (Action>Mouse Up>Javascript)

Normally we wouldn't need to make use of global's (global.) but in our example we need to create a variable that will be available to all our of routines, we also need to continue adding to the report object as we are batch processing.

The second part of the example is where all the action happens. In our example we want to execute a batch sequence that will open each PDF so we can extract the information we need, once we have collected that information we are going to add it to our report object:

global.rep.indent();
global.rep.color = color.red;
global.rep.writeText("File Name: " + this.documentFileName);
global.rep.indent();
global.rep.color = color.black;
global.rep.writeText("Title: " + this.info.title);
global.rep.writeText("Author: " + this.info.author);
global.rep.writeText("Subject: " + this.info.subject);
global.rep.divide();
global.rep.writeText("File Size: " + this.filesize);
global.rep.writeText("Page Count: " + this.numPages);
global.rep.writeText("Field Count: " + this.numFields);
global.rep.divide();
global.rep.outdent();
global.rep.outdent();

The second part of this example uses a 'Batch Sequence' to execute our code against loads of different PDF files.

Here I've created a sequence 'ReportBuilder_A' which executes a Javascript 'Execute Javascript' with the above code inserted into it.

1. global.rep.indent();
2. global.rep.color = color.red;
3. global.rep.writeText("File Name: " + this.documentFileName);
4. global.rep.indent();
5. global.rep.color = color.black;
6. global.rep.writeText("Title: " + this.info.title);
7. global.rep.writeText("Author: " + this.info.author);
8. global.rep.writeText("Subject: " + this.info.subject);
9. global.rep.divide();
10. global.rep.writeText("File Size: " + this.filesize);
11. global.rep.writeText("Page Count: " + this.numPages);
12. global.rep.writeText("Field Count: " + this.numFields);
13. global.rep.divide();
14. global.rep.outdent();
15. global.rep.outdent();

So let's break the main part of our example down. Line 1 tell's the report object that whatever text follow should be indented one level, line 2 changes the color to the predefined color red (RGB [1,0,0]), the next line (3) we write some text into the report object and then indent another level (line 4). The remaining lines/code continues to add information to report object. You'll also notice that we are using the 'this' object to extract information from our open PDF documents.

The last part of our example generates the report. This basically takes all of the information contained inside the report object and generates a blank PDF file and writes the content of the report to the PDF.

Summary

The overall process of generating reports requires only three parts:

1. Create a Report Object,
2. Add content to it and then
3. Close the Report Object.

The only thing that holds you back in using reports is finding uses for it.

Enjoy.

Copyright Dave Wraight & Planet PDF. No unauthorised reproduction, distribution or publication permitted.