Is there anyway to default to portrait, but change to landscape if the contents (a large table) does not fit on portrait, but will fit on landscape? And then also if it does not fit landscape to prince-shrink-to-fit auto?

Similarly, is there way to force the page to change to A3 from A4 if the contents cannot fit on A4?

Edited 13 Jun 2014 by dancotter

No, not at the moment. Recently we have added an experimental box tracking API, so if you are willing to write some tricky JavaScript then it would be possible to measure the generated PDF file, check if the table is too big, and then run Prince again with different CSS.

where can I get the info about using this box tracking API

The experimental box tracking API is available in the latest Prince alpha builds.

You can use it like this:

Prince.trackBoxes = true;
Prince.addEventListener("complete", check, false);

function check()
{
    var bs = document.body.getPrinceBoxes();

    console.log("body element boxes: "+bs.length);
    console.log("first box properties:");

    for (var i in bs[0])
    {
        console.log("  "+i+": "+bs[0][i]);
    }
}

Is there a real documentation for this API yet? I can't seem to find it anywhere. Also, what tools are available for debugging scripts that use PrinceXML's APIs?

At the moment the best examples of the API are on the forum:

Changebars
Detecting Overflow

We are working on documentation that will be available in the next release:

The box tracking API must be enabled before formatting starts with Prince.trackBoxes. It then becomes available in the oncomplete event, where you can access PDF.pages, which is a list of page boxes, and call the getPrinceBoxes() method on any DOM element. This returns a list of boxes.

Boxes are JavaScript objects with some or all of the following properties:

type = "BODY" |
"COLUMN" |
"FLEXLINE" |
"FOOTNOTES" |
"FLOATS" |
"BOX" |
"LINE" |
"SPAN" |
"TEXT" |
"SVG" |
"IMAGE"
pageNum
x
y (set to zero on some boxes)
w
h (set to zero on some boxes)
children = array of child boxes
parent = parent box
element = DOM element for box (may be null)
pseudo = pseudo-element name or null
text = string
src = URL string for images
style = CSS style object for box

Since the box tracking API is available only after the oncomplete event, it cannot be used to modify the document (see JavaScript in Printed Media). However, see The "Two-Pass" Solution for making use of its output.