Enhancements

[PhilterPaper]

I have table capability on my long-term to-do list for PDF::Builder, but it looks like PDF::Table may do the job. There are some additional features that I would like to see, that would make it far more useful, so if anyone is looking for some small projects to contribute with, these might provide some ideas:

1. In HTML, the header is defined separately, defaults to bold and centered in cells, and automatically repeats. I think it should have repeat=1 by default, but since it's easy to set, it could be justified not changing. The design would have been cleaner to have a header (<thead>-like) defined separately from the body data, but I can live with it being the first data row.
2. HTML offers a footer (<tfoot>), similar to the header, and PDF::Table should too. Perhaps it could be the second data line (first, if there's no header)?
3. There might be a code hook to dynamically define header and footer contents (such as page subtotals).
4. Either provide start-of-page and end-of-page code hooks, or make a per-page call to output that page's table. This would make it easier to put out running page headers and footers, page numbers, first and last content headings (like the first and last word on a dictionary page). Some sort of hook or flag to let the program know when the first row/column and last row/column are being processed would make it easier to output page headers.
5. Offer more control over splitting the table between pages: keep the table intact unless it exceeds one page (good for short tables), allow split only only between rows (unless a row exceeds one page), and some sort of splitting within a row (at a minimum, don't create orphans and widows), allow split between paragraphs, etc. CSS might give some ideas for controls.
6. API2 and Builder have a rotate(n) call to rotate the page, which can be useful for outputting wide tables. Page headers and footers should still be portrait mode, while the rest of the page content is rotated landscape. Unfortunately, I think you would have to (at page level) rotate(-90) and manually unrotate page headers and footers.
7. Consider how to use PDF::Table to output continuous text in two or three columns (of one row per page), with content output (like text blocks) automatically flowing from one column to the next. The last page of a table should permit some sort of column balancing, to even out the column lengths.
8. Permit vertical alignment of cell contents (see HTML and CSS valign): top, bottom, or middle.
9. Define rules (internal cell separators) separately from the outside enclosing border. Generally they would be lighter weight, or even omitted. If permitting flowed columns, allow a light vertical rule in the gutter between columns. Dashed or other pattern rules could be supported.
10. Permit more elaborate border lines than just solid -- double lines, 3D beveled effects with shadows, etc. like HTML and CSS support.

I don't know when I'll have time to get to any of these, but hopefully if someone is looking for something to do, this will give some ideas (clear them with the owner first, before spending a lot of time coding!). I'll be happy to elaborate offline on what I'm looking for in a specific item, if you're not sure what I'm asking for.

[PhilterPaper]

Regarding bullet 6, I don't think rotate() is going to be helpful in rotating the page and table. Indeed, rotate(-90) does rotate the page into landscape orientation, but the text is also rotated. When printed, the end result is that the rotated page is simply upside-down from the normal page.

However, it appears that calling $page->mediabox(0,0, H,W); (default H and W values, here reversed in order) and writing normally to it does give the desired result of the page turned 90 degrees CCW and text written in that orientation, for wide tables. Page headings and footings would have to be explicitly de-rotated ($text->transform(-translate=>[x,y], -rotate=>-90);) to orient them normally (i.e., consistent with the normal pages).

I have added an example to PDF::Builder, Rotated.pl, to illustrate this. Rotated pages are 90 degrees counterclockwise (normal for Left-to-Right reading). For other orientations (possibly for bidirectional text), or if you want the "bottom" of a page to be on the binding side, etc., you'd have to play around with the parameters and possibly do explicit rotations.

[PhilterPaper]

See #51 request for image support. At the moment, I'm not sure whether reserving space for an image is the best approach, or should PDF::Table be somehow rearchitected (if necessary) to allow any content at a given width and indefinite height for a cell. Having embedded images within flowed text could be quite a chore, although allowing images by themselves above or below text might not be too onerous.

[PhilterPaper]

Per #55, think about adding row_props to set overriding properties for an entire row. Think about expanding (generalizing) column_props and cell_props to specify "border" (actually, "rule") on 1 to 4 sides of a row, column, or cell, so effects such as a divider between two rows or two columns can be created.

Change "border" to mean just the exterior table border, and use "rules" to talk about interior lines dividing rows, columns, and cells.

[PhilterPaper]

Update for release 1.000: row_props has been added. Its priority is after cell_props and column_props, and before global settings. Per bullet 1, the header now repeats by default (this can be shut off).

Some sort of image support is in the wishlist/road map, for a subsequent release.

[PhilterPaper]

Items 1 and 9 done in release 1.000. Item 5 (ref #42) "to-do" list has mode to return lengths (heights) of header, footer, and each row, as well as the overall length, so you can have more control over where to break the table across pages (still between rows; no control over breaking within rows). Could think about preventing widows and orphans on breaks within rows.

[PhilterPaper]

See also [/forum/general-12/pdftable-general-discussion/] for general discussions of direction of PDF::Table package. This forum no longer exists. Put general discussion in this ticket.

[PhilterPaper]

Regarding items 3 and 4 (related), there is already a new_page_func callback to permit you to run your own code at the beginning of a page, to do things such as rotating the page and putting in page headers and footers. It might be a bit difficult to do things at the end of a page, unless you do them for the previous page on new_page_func invocations, and once when table() returns. Or, you can use the information returned by table() to go back and revisit each page, to add or revise header and footer information "after the fact" (page update). Exactly how that would be done depends on whether the page has actually been written to file and closed, or it's still in the $pdf structure. Perhaps a new end_page_func callback could be used for dealing with things not known until the end of the page? Maybe a begin_page_func (as distinct from new_page_func) invoked when ready to write any header (or first data row) on a page, and end_page_func when ready to write any footer or after the last data row on the page?

Updating table header row (and potentially footer row) content (e.g., running totals), is an interesting problem. To go back and update the page after table() has written it means knowing exactly where the cell content is, and where you are supposed to update it within that content. The cell_render_hook callback might help here, at least if you are willing to write the entire cell content at this time. Keep in mind that you can not increase the width or height of the cell (header or footer), or you'll throw all the sizing calculations off!

Finally, for item 5, one approach might be to 'virtually print' all the cells of a row (full content) and let table() decide where to split them. Or, a new setting 'heights' might prevent actually writing to the PDF, but just return an array of row heights: header, footer, row 1, row 2, ... (plus the overall single-page height). Allow 'next_y' and 'next_h' to be arrays of Y-positions and heights. This way you can decide to go to the top of the next page before starting a table that could fit on one page, rather than ending up split over two pages, and control how many rows go on each page. It still wouldn't do anything about widows and orphans, or restrict where a row could be split.

[PhilterPaper]

Item 8 (vertical alignment in a cell) requires knowing the final content height and the final total row height. Right now this is not known, as formatting and output is done on the fly line-by-line, and it is not known whether the limit has been reached (with more text to go). We would have to 'virtually print' the row's content (if not the whole table's) to figure out how much vertical space is needed for a row and each cell's content. Only then could we float the content up and down (alignment) and decide if and where to split within a row (due to running out of space) without leaving widows or orphans. If the bottom (horizontal) rules have already been output for the row above, and table() decides to skip to the next page (possibly due to leaving an orphan otherwise), something would have to be done about the rules already output, and page-break border.

Add: A "poor man's vertical alignment" could be done (after the fact) by adding extra padding_top on a per-cell basis, to push down the cell contents to effect a middle or bottom alignment. Of course, this will require some trial-and-error fitting. I haven't checked what happens if that row gets split across pages -- whether the extra padding will appear on the continuation page (not desired!) or if the rest of the text is without extra top padding. Defining blank lines before the real content of a cell might also work, and should split cleanly, although this would not permit precise middle alignment (it would align on text lines, which may be more desirable anyway).

Add: A more automated "poor man's vertical (or bottom) alignment" could be to make a "dry run" across a row, finding the natural number of lines of text (and images) for each cell, and adding padding_top or blank lines to the content to push it down. Not knowing where a row might possibly be split across pages, there's still no way to deal with widows and orphans. Any images that might have to be shoved to the next page due to insufficient remaining space, might cause the cell to be higher (taller) than planned. ===== If you have at least 4 lines of text, perhaps something can be done to avoid starting a cell if you're close enough to the bottom that a row will have to be split after one line of output (producing an orphan), or can be split earlier to avoid a single line (widow) on the next page. The key is knowing how many lines of text will need to be output.

[PhilterPaper]

See #69 for further implementation information.

Regarding item 5 (and #42 late request), one way to handle this (to a large degree) would be to have a setting size that does not output anything to the PDF file, but only returns an array of heights used.

• [0] Overall height, in Points (sum of following elements, as though whole table fits on one page).
• [1] Height of header, 0 if not using a header.
• [2] Height of footer (reserved for footer), 0 if not using a footer.
• [3] Height of data row 1 (first).
• [2+n] Height of data row n.

This way you can look at the height and decide whether to start the table now, or jump to the top of the next page. It's especially good for short tables which can fit on one page, and you want to avoid starting them too far down the page to avoid splitting them over two pages.

For further control, you can give next_y and next_h as anonymous arrays, to control how many rows get put on each page (along with h for the first page). Be sure to allow for a header and/or footer on a page, as well as any caption (#31). If you run out of next_y and next_h elements, just re-use the last one as many times as necessary.

This does not correlate to any CSS settings; nor does it prevent widows and orphans if a row does end up being split across two or more pages (although judicious setting of next_h may be helpful). If the data permits it, you might even be able to re-order the rows to better fill the pages.

Add: In addition to returning the height of a row in points, it could also return the count of lines of text. Something might then be done to pass this information for permitted row split points for the "actual" live run of the table, so you would know how to avoid an orphan or widow, and possibly avoid shoving an image onto the next page without correcting the cell height.

[PhilterPaper]

Since we have colspan, it would probably be nice to have rowspan capability. Into the hopper for a near-future release.

[PhilterPaper]

Just a note so you don't overlook it: PDF::Table now supports PDF::Builder's column() call, which supports Markdown and HTML markup. An example is given in Builder's examples/Column.pl. This is not supported in PDF::API2.

The request for "code" style display, with spaces and line-ends honored (#66), is expected to be satisfied in the near future with improvements to the column() call, rather than implementing them in PDF::Table itself.