Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PDF::Table(3)	      User Contributed Perl Documentation	 PDF::Table(3)

NAME
       PDF::Table - A utility class for	building table layouts in a
       PDF::Builder (or	PDF::API2) object.

SYNOPSIS
       Rather than cluttering up the following documentation with (or
       PDF::API2) additions, wherever it refers	to "PDF::Builder", understand
       that you	can substitute "PDF::API2" to use that product instead.

	use PDF::Builder;
	use PDF::Table;

	my $pdftable = new PDF::Table;
	my $pdf	= new PDF::Builder(-file => "table_of_lorem.pdf");
	my $page = $pdf->page();

	# some data to lay out
	my $some_data =[
	   ["1 Lorem ipsum dolor",
	   "Donec odio neque, faucibus vel",
	   "consequat quis, tincidunt vel, felis."],
	   ["Nulla euismod sem eget neque.",
	   "Donec odio neque",
	   "Sed	eu velit."],
	   # ... and so	on
	];

	$left_edge_of_table = 50;
	# build	the table layout
	$pdftable->table(
	    # required parameters
	    $pdf,
	    $page,
	    $some_data,
	    'x'	=> $left_edge_of_table,
	    'w'	=> 495,
	    'y'	=> 500,
	    'h'	=> 300,
	    # some optional parameters
	    'next_y'	      => 750,
	    'next_h'	      => 500,
	    'padding'	      => 5,
	    'padding_right'   => 10,
	    'bg_color_odd'    => "gray",
	    'bg_color_even'   => "lightblue", #	cell bg	color for even rows
	    'max_word_length' => 50, # 50 between forced splits
	 );

	# do other stuff with $pdf
	$pdf->save();
       ...

   EXAMPLE
       For a complete working example or initial script	look into
       distribution's 'examples' folder.

DESCRIPTION
       This class is a utility for use with the	PDF::Builder (or PDF::API2,
       see note	above) module from CPAN.  It can be used to display text data
       in a table layout within	a PDF.	The text data must be in a 2D array
       (such as	returned by a DBI statement handle "fetchall_arrayref()"
       call).  PDF::Table will automatically add as many new pages as
       necessary to display all	of the data.  Various layout properties, such
       as font,	font size, cell	padding, and background	color can be specified
       for each	column and/or for even/odd rows.  Also a (non)repeated header
       row with	different layout properties can	be specified.

       See the "METHODS" section for complete documentation of every
       parameter.

COMPATIBILITY
       Starting	with version 1.000, several behaviors have changed (for	the
       better, I believe). Nevertheless, there may be some users who prefer
       the old behaviors.  To keep everybody happy, it is possible to easily
       revert to the old behaviors.  Near the top of Table.pm, look for	a
       section labeled "COMPATIBILITY WITH OLDER VERSIONS". You	can change
       settings	here to	match old behaviors:

       repeating headers
	   The old default for the "repeat" setting for	a header was '0' (do
	   not repeat after a table has	been split across a page). I believe
	   that	most users will	want to	automatically repeat a header row at
	   the start of	each table fragment, but you can change	this behavior
	   if you wish.	Change $repeat_default from 1 to 0 to get the old
	   behavior (or, explicitly give "repeat =" 0> in the header
	   properties settings).

       which rows are 'odd' (and which are 'even')
	   PDF::Table decided which rows were odd/even (background and
	   foreground colors, etc) in an inconsistent manner, especially if a
	   header was used (whether repeated or	not). Now, the first data row
	   (excluding headers) is "odd", and all rows after that alternate
	   "even", "odd", etc.,	even across page breaks. If you	want the old
	   behavior, it	can be requested. Change $oddeven_default from 1 to 0
	   to get the old behavior.

       default cell padding
	   The old default for padding around the contents of a	cell was 0. It
	   is now 2pt. Change $padding_default from 2 to 0 to get the old
	   behavior.

       behavior	of borders
	   The old behavior was	calling	both the frame around the table	and
	   the cell-divider rules as "border", and using the same settings for
	   both. This has been changed to separate the two classes, with
	   "border" referring to the outside framework,	and "rules" referring
	   to the dividers. Note that "rules" still inherit from "border", so
	   an explicit definition of "rules => 0" (to hide interior rules) or
	   another width (line weight) may still be needed to override the
	   "border" setting for	interior dividers.

   Maintaining compatibility
       Near the	top of file Table.pm, look for "my $compat_mode	= 0;".
       PDF::Table is shipped with a flag of 0 to use the new features of the
       library.	If you have a pressing need to maintain	compatibility with
       older versions of the library, you may change the value to 1.  Note
       that a flag of 1	will break some	of the t-tests,	because	of different
       padding defaults	resulting in different text locations on the page.

   Run-time changes
       If you do not wish to change the	PDF::Table code	section	to permanently
       change old-versus-new behavior, you can use the compatibility flag in
       the settings to temporarily change the variables	listed above.

	   compatibility => [ 0, 0, 0 ]

       will restore all	behaviors to the old style, while

	   compatibility => [ 1, 0, 2 ]

       will change only	the designation	of "odd/even" rows (element 1) to the
       old behavior, while leaving header repeat (element 0) and default
       padding (element	2) in the new behavior.

METHODS
   new()
	   my $pdf_table = new PDF::Table;
	      or
	   my $pdf_table = PDF::Table->new();

       Description
	   Creates a new instance of the class.

       Parameters
	   There are no	required parameters. You may pass $pdf,	$page, $data,
	   and %options; or can	defer this until the table() method invocation
	   (the	usual technique).

       Returns
	   Reference to	the new	instance

   table()
	   my ($final_page, $number_of_pages, $final_y)	= table($pdf, $page, $data, %settings)

       Description
	   Generates a multi-row, multi-column table into an existing PDF
	   document, based on provided data set	and settings.

       Parameters
	       $pdf	 - a PDF::Builder instance representing	the document being created
	       $page	 - a PDF::Builder::Page	instance representing the current page of
			   the document
	       $data	 - an ARRAY reference to a 2D data structure that will be used
			   to build the	table
	       %settings - HASH	with geometry and formatting parameters

	   For full %settings description see section "Table settings" below.

	   This	method will add	more pages to the PDF instance as required,
	   based on the	formatting options and the amount of data.

       Returns
	   The return value is a 3 item	list where

	       $final_page - A PDF::Builder::Page instance that	the table ends on
	       $number_of_pages	- The count of pages that the table spans
	       $final_y	- The Y	coordinate of the table	bottom,	so that	additional
			  content can be added on the same page	($final_page)

       Example
	       my $pdf	= new PDF::Builder;
	       my $page	= $pdf->page();
	       my $data	= [
		   ['foo1','bar1','baz1'],
		   ['foo2','bar2','baz2']
	       ];
	       my %settings = (
		   'x' => 10,
		   'w' => 570,
		   'y' => 220,
		   'h' => 180,
	       );

	       my ($final_page,	$number_of_pages, $final_y) =
		   $pdftable->table( $pdf, $page, $data, %options );

       Table settings

       Unless otherwise	specified, all dimensional and geometry	units used are
       measured	in points. Line	counts are not used anywhere.

       "Even" rows start with the first	data (non-header) row. Think of	this
       first row as number zero	(an even number). Even rows alternate with odd
       rows.  The odd/even flag	is not reset when a table is split across
       pages. If a table fragment ends on an odd row, the next fragment	(on
       the next	page), starting	the next row, will start with an even row. If
       a row is	split across pages, it will resume with	the same odd/even
       setting as on the previous page.	If you desire to have the old
       (previous) odd/even behavior, see "COMPATIBILITY".

       The name	(key) of any table setting hash	element	may be given with or
       without a leading dash (hyphen).	A leading dash is allowed for
       compatibility with older	versions of PDF::Table,	but is DEPRECATED! It
       is recommended that the dash be omitted in new code, and	removed	from
       old code	before November	2022.

       Note: if	you use	a deprecated setting name, or a	setting	beginning with
       a hyphen	'-', PDF::Table	will update the	settings list with the
       preferred name.	It does	this by	inserting the item using the
       preferred, non-hyphen name, and then deletes the	deprecated one.	Due to
       peculiarities in	the way	Perl copies arrays, hashes, and	references; it
       is possible that	your input settings hash may end up being modified!
       This normally will not be a cause for concern, but you should be	aware
       of this behavior	in case	you wish to reuse all or part of a PDF::Table
       settings	list (hash) for	other purposes (or another table) -- it	may
       have been slightly modified.

       Note that any "Color specifier" is not limited to a name	(e.g.,
       'black')	or a 6-digit hex specification (e.g., '#3366CC'). See the
       PDF::Builder writeup on specifying colors for CMYK, L*a*b, HSV, and
       other methods.

       Mandatory global	settings

       There are some mandatory	parameters for setting table geometry and
       position	on the first (initial) or only page of the table. It is	up to
       you to tell PDF::Table where to start (upper left corner) the table,
       and its width and maximum height	on this	page.

       x - X coordinate	of upper left corner of	the table.
	   The left edge of the	sheet (media) is 0.  Note that this "X"	will
	   be used for any spillover of	the table to additional	page(s), so
	   you cannot have spillover (continuation) rows starting at a
	   different "X".

	   Value: can be any number satisfying "0 ax X < PageWidth"

	   Default: No default value

	       'x' => 10,

       y - Y coordinate	of upper left corner of	the table on the initial page.
	   Value: can be any number satisfying "0 < y <	PageHeight" (depending
	   on space availability when embedding	a table)

	   Default: No default value

	       'y' => 327,

	   Deprecated name: start_y (will go away in the future!)

       w - width of the	table starting from "x".
	   Note	that this "width" will be used for any spillover of the	table
	   to additional page(s), so you cannot	have spillover (continuation)
	   rows	with a different "width".

	   Value: can be any number satisfying "0 < w <	PageWidth - x"

	   Default: No default value

	       'w'  => 570,

	   NOTE: If PDF::Table finds that the table width needs	to be
	   increased to	accommodate the	requested text and formatting, it will
	   output a warning. This could	lead to	undesired results. Possible
	   solutions to	keep the table from being widened include:

	       1) Increase table width (w)
	       2) Decrease font	size (font_size)
	       3) Choose a narrower font
	       4) Decrease "max_word_length" parameter,	so long	words are split	into
		   shorter chunks
	       5) Rotate media to landscape (if	it is portrait)
	       6) Use a	larger (wider) media size

       h - Height of the table on the initial (current)	page.
	   Think of this as the	maximum	height (Y dimension) of	the start of
	   the table on	this page. This	would be the current "Y" location less
	   any bottom margin. Normally you would let as	much as	possible fit
	   on the page,	but it's possible that you might want to split the
	   table at an earlier point, to put more on the next (spill) page.

	   Value: can be any number satisfying "0 < h <	PageHeight - Current Y
	   position"

	   Default: No default value

	       'h' => 250,

	   Deprecated name: start_h (will go away in the future!)

       Optional	settings

       These are settings which	are not	absolutely necessary, although their
       use may result in a much	more pleasing appearance for the table.	They
       all have	a "reasonable" default (or inheritance from another setting).

       Optional	Global Settings

       These settings apply only to the	entire table, and cannot be used to
       specify cell, column, or	row properties.	A global setting may only
       occur once.

       next_h -	Height of the table on any additional page.
	   Think of this as the	maximum	height (Y dimension) of	any overflow
	   (spill) table portions on following pages.  It is highly
	   recommended that you	explicitly specify this	setting	as the full
	   (body content) height of a page, rather than	having PDF::Table try
	   to figure out a good	value and give a warning.

	   Value: can be any number satisfying "0 < next_h < PageHeight	- y"

	   You need to leave a non-negative amount of space at the bottom of
	   the page.

	   Default: Media height * 80% (80% of the paper height) You will
	   receive a warning if	"next_h" is needed for a spill page and	you
	   did not provide it!

	       'next_h'	 => 700,

       next_y -	Y coordinate of	upper left corner of the table at any
       additional page.
	   Think of this as the	starting "Y" position of any overflow (spill
	   or continuation) table portions on following	pages.	It is highly
	   recommended that you	explicitly specify this	setting	to be at the
	   top of the body content of a	page, rather than having PDF::Table
	   try to figure out a good value and give a warning.

	   Value: can be any number satisfying "0 < next_y < PageHeight"

	   Default: Media height * 90% (10% down from the top of the paper)
	   You will receive a warning if "next_y" is needed for	a spill	page
	   and you did not provide it!

	       'next_y'	 => 750,

       new_page_func - CODE reference to a function that returns a
       PDF::Builder::Page instance. See	section	"New Page Function Hook"
       below.
	       'new_page_func'	=> $code_ref,

       cell_render_hook	- CODE reference to a function called with the current
       cell coordinates. See section "Cell Render Hook"	below.
	       'cell_render_hook'  => $code_ref,

       header_props - HASH reference to	specific settings for the Header row
       of the table. See section "Header Row Properties" below.
	       'header_props' => $hdr_props,

       row_props - HASH	reference to specific settings for each	row of the
       table. See section "Row Properties" below.
	       'row_props' => $my_row_props,

       column_props - HASH reference to	specific settings for each column of
       the table. See section "Column Properties" below.
	       'column_props' => $col_props,

       cell_props - HASH reference to specific settings	for each column	of the
       table. See section "Cell	Properties" below.
	       'cell_props' => $cell_props,

       border_w	- Width	of table border	lines.
       h_border_w - Width of horizontal	border lines (top and bottom of	the
       table). Overrides 'border_w' value for horizontal usage.	Note that if
       the table spills	over onto following pages, only	the very first top and
       very last bottom	table border will be full width. Dividers on row
       boundaries will be 1pt wide ($border_w_default) solid lines, and	where
       a row is	divided	within its content, a dashed (pattern
       $dashed_rule_default) 1pt wide line is used.
       v_border_w -  Width of vertical border lines. Overrides 'border_w'
       value for vertical usage.
	   Value: can be any positive number. When set to 0, it	will disable
	   border lines. This is the line thickness for	drawing	a border.

	   Default: 1  ($border_w_default)

	   The border is the outside frame around the table. It	does not enter
	   into	table height or	width calculations, so be sure to set your "x"
	   and "w" settings to allow for the width of vertical borders,	and
	   your	"y" or "next_y"	and "h"	or "next_h" settings to	allow for the
	   width (thickness or height) of the horizontal borders, especially
	   if you make them more than a	Point or two in	thickness (line
	   width).

	       'border_w'     => 3,	# border width is 3
	       'h_border_w'   => 1,	# horizontal borders will be 1,	overriding 3
	       'v_border_w'   => undef,	# vertical borders will	be 3, as it will
					# fall back to 'border_w'

	   Note	that both borders and rules overlay the	exact boundary between
	   two cells (i.e., the	centerline). That is, one half of a rule or
	   border will overlay the adjoining cells. Rules do not expand	the
	   size	of the table, although borders will (by	a total	of their
	   thickness/width). If	you set	particularly thick (wide) rules, pay
	   attention to	adding some padding on the appropriate side(s),	so
	   that	valuable content is not	overlaid. For cells along the outer
	   border, one half the	width of a border will overlay the cell, so
	   account for this in the padding specification.

	   Deprecated names: border (now 'border_w'), horizontal_borders (now
	   'h_border_w'), and vertical_borders (now 'v_border_w'); will	go
	   away	in the future!

       border_c	-  Border color	for all	borders.
	   Value: Color	specifier as 'name' or '#rrggbb'

	   Default: 'black' ($fg_color_default)

	       'border_c' => 'red',

	   Deprecated name: border_color (will go away in the future!)

	   The same color is used for both the horizontal and vertical
	   borders.

       Optional	Cell, Column, Row, or Global Settings

       These settings can be specified to apply	to the entire table, or	more
       narrowly	applied	to the header row (in header_props hash), one or more
       rows (in	row_props array), one or more columns (in column_props array),
       or one or more individual cells (in cell_props hash).

       If a setting is specified in more than one place, the order of
       precedence is as	follows: a header property (header row only), followed
       by a cell property, followed by a column	property, followed by a	row
       property, followed by a global setting, and finally, any	hard-coded
       default value (if required).

       A global	setting	may only occur once (although it may be	overridden by
       cell, column, or	row usage of the same setting).

       default_text - A	string to use if no content (text) is defined for a
       cell.
	   Value: any string (can be a blank)

	   Default: '-'	 ($empty_cell_text)

       max_word_length - Breaks	long words
	   It may be necessary to break	up long	words (like serial numbers,
	   hashes, etc.) to fit	within a column, by adding a space after every
	   Nth symbol, unless a	space (x20) is found already in	the text.

	   Note	that this does not add a hyphen	(dash)!	 It merely ensures
	   that	there will be no runs of non-space characters longer than N
	   characters, reducing	the chance of forcing an overly	wide column.

	   Value: can be any positive integer number (character	count)

	   Default: 20

	       'max_word_length' => 25,	   # Will add a	space after every 25 symbols
					   # unless there is a natural break (space)

       padding - Padding applied to every cell
       padding_top    -	top cell padding, overrides 'padding'
       padding_right  -	right cell padding, overrides 'padding'
       padding_left   -	left cell padding, overrides 'padding'
       padding_bottom -	bottom padding,	overrides 'padding'
	   Value: can be any non-negative number (aY 0)

	   Default padding: 2.	($padding_default)

	   See "COMPATIBILITY" for returning to	the old	value of 0.

	   Default padding_* 'padding'

	       'padding'	=> 5,	  # all	sides cell padding
	       'padding_top'	=> 8,	  # top	cell padding, overrides	'padding'
	       'padding_right'	=> 6,	  # right cell padding,	overrides 'padding'
	       'padding_left'	=> 2,	  # left cell padding, overrides 'padding'
	       'padding_bottom'	=> undef, # bottom padding will	be 5, as it will fall
					  # back to 'padding' value

       font - instance of PDF::Builder::Resource::Font defining	the font to be
       used in the table (or a subsection of it).
	   Value: can be any PDF::Builder::Resource::* type of font

	   Default: 'Times' core font with latin1 encoding

	       'font' => $pdf->corefont("Helvetica", -encoding => "latin1"),

	   CAUTION: Only TrueType and OpenType fonts (ttfont call) can make
	   use of multibyte encodings such as 'utf8'. Errors will result if
	   you attempt to use 'utf8', etc. with	corefont, psfont, etc. font
	   types! For these, you must only specify a single-byte encoding.

       font_size - Size	of the font that will be used in the table (or a
       subsection of it).
	   Value: can be any positive number

	   Default: 12	($font_size_default)

	       'font_size' => 16,

       fg_color	- Font color for all text.
       bg_color	- Background color for all text.
	   Value: Color	specifier as 'name' or '#rrggbb' (or other suitable
	   color specification format)

	   Default: 'black' text on (transparent) background. In other words,
	   there is no default background color. The exception is for any
	   header row, where the default colors	are "#000066" (dark blue,
	   $h_fg_color_default)	on "#FFFFAA" (light yellow,
	   $h_bg_color_default).

	       'fg_color'      => '#333333',

	   Deprecated names: font_color, background_color (both	will go	away
	   in the future!)

       fg_color_odd - Font color for odd rows (override	"fg_color").
       fg_color_even - Font color for even rows	(override "fg_color").
       bg_color_odd - Background color for odd rows (override "bg_color").
       bg_color_even - Background color	for even rows (override	"bg_color").
	   Value: Color	specifier as 'name' or '#rrggbb' (or other suitable
	   color specification format)

	       'fg_color_odd'  => 'purple',
	       'fg_color_even' => '#00FF00',
	       'bg_color_odd'  => 'gray',
	       'bg_color_even' => 'lightblue',

	   Deprecated names: font_color_odd, font_color_even,
	   background_color_odd, background_color_even (all will go away in
	   the future!)

	   Note	that *_color_odd/even usually make the most sense as global
	   settings, although it is possible to	use them within	columns	(see
	   chess.pl example), and even rows and	cells, but not header rows.

       underline - Underline specifications for	text in	the table.
	   Value: 'auto', integer of distance (below baseline),	or arrayref of
	   distance & thickness	(more than one pair will provide multiple
	   underlines).	 Negative distance gives strike-through. "[]" ('none'
	   also	works for PDF::Builder)	gives no underline.

	   Note	that it	is unwise to underline all content in the table! It
	   should be used selectively to emphasize important text, such	as
	   header content, or certain cells. Unfortunately, there is currently
	   no way to turn underlining off and on within	a cell.

	   Default: none

	   Deprecated name: font_underline (will go away in the	future!)

       min_rh -	Desired	minimum	row height.
	   This	setting	will be	honored	only if	"min_rh	> font_size +
	   padding_top + padding_bottom" (i.e.,	it is taller than the
	   calculated minimum value).

	   This	setting	doesn't	usually	make sense when	used in	a column_props
	   or a	cell_props, but	it is possible to do, and may be useful	in
	   certain situations.

	   Value: can be any positive number

	   Default: "font_size + padding_top + padding_bottom"

	       'min_rh'	=> 24,

	   Deprecated name: row_height (will go	away in	the future!)

       justify - Alignment of text in a	cell.
	   Value: One of 'left', 'right', 'center'

	   Default: 'left'

       min_w - Minimum width of	this cell or column.
	   PDF::Table will set a cell (and the column it's in) minimum width
	   to fit the longest word (after splitting on "max_word_length")
	   found in the	text. This amount may be increased to "min_w". A
	   column should be no narrower	than its widest	minimum	width, but
	   could be larger in order to fill out	the table width.

	   Value: can be any number satisfying "0 < min_w < w"

	   Default: Auto calculated

	   Note	that "min_w" is	usually	used for a column_props	to set the
	   column minimum width. If used in a row_props, it will act as	a
	   global setting; if used in a	cell_props, that will force the
	   minimum width for the cell's	column.

       max_w - Maximum width of	this column.
	   PDF::Table will set a cell (and the column it's in) maximum width
	   to fit the total length of the text content.	This will seldom be
	   actually used, but "max_w" may be used to reduce this maximum. When
	   columns are being widened in	order to meet the desired table	width,
	   it will try to honor	the maximum width setting and avoid adding any
	   width to a column already at	its maximum width (but this cannot be
	   guaranteed).

	   Value: can be any number satisfying "0 < min_w ax max_w < w"

	   Default: Auto calculated

       rule_w -	Width of table rule lines (internal table dividers).
       h_rule_w	- Width	of horizontal rules (bottom of a cell).	Overrides
       'rule_w'	value for horizontal usage.
       v_rule_w	-  Width of vertical rules (left side of a cell). Overrides
       'rule_w'	value for vertical usage.
	   Value: can be any positive number. When set to 0, it	will disable
	   rules. This is the line thickness for drawing a rule.

	   Default: 1  (corresponding border value)

	   A rule is a line bordering a	cell in	the table. While it does not
	   enter into table height or width calculations, be sure to set your
	   "padding" settings to allow sufficient clearance of cell content,
	   especially if you make the rules more than a	Point or two in
	   thickness (line width). Note	that a cell only defines and draws its
	   left	and bottom rules -- the	top rule is defined in the cell	or row
	   above, and the right	rule is	defined	in the cell or column to the
	   right of this one.

	       'rule_w'	    => 3,     #	rule width is 3
	       'h_rule_w'   => 1,     #	horizontal rules will be 1, overriding 3
	       'v_rule_w'   => undef, #	vertical rules will be 3, as it	will
				      #	fall back to 'rule_w'

	   Note	that both borders and rules overlay the	exact boundary between
	   two cells (i.e., the	centerline). That is, one half of a rule or
	   border will overlay the adjoining cells. Rules do not expand	the
	   size	of the table. If you set particularly thick (wide) rules, pay
	   attention to	adding some padding on the appropriate side(s),	so
	   that	valuable content is not	overlaid. For cells along the outer
	   border, a border will be drawn instead of a rule.

	   Cell	rules inherit thickness	and color from the border settings, so
	   if you want no internal rules, you need to set

	       'rule_w'	    => 0,     #	no rules

       rule_c -	 Rule color for	all rules.
       h_rule_c	-  Rule	color for horizontal (bottom) rules, overriding
       "rule_c"	for this usage.
       v_rule_c	-  Rule	color for vertical (left) rules, overriding "rule_c"
       for this	usage.
	   Value: Color	specifier as 'name' or '#rrggbb'

	   Default: 'black' (corresponding border value)

	       'rule_c'	=> 'red',

       New Page	Function Hook

       new_page_func is	a CODE reference to a function that returns a
       PDF::Builder::Page instance.

       If used,	the parameter '"new_page_func"'	must be	a function reference
       which, when executed, will create a new page and	will return the	object
       to the module.  For example, you	can use	it to put Page Title, Page
       Frame, Page Numbers and other content that you need.  Also if you need
       a different paper size and orientation than the default US-Letter,
       e.g., B2-Landscape, you can use this function ref to set	it up for you.
       For more	info about creating pages, refer to PDF::Builder PAGE METHODS
       Section.	 Don't forget that your	function must return a page object
       created with the	PDF::Builder page() method. $code_ref can be something
       like "\&new_page".

	   'new_page_func'  => $code_ref,

       The $code_ref may be an inline sub definition (as show below), or a
       regular named "sub" (e.g., 'new_page()')	referenced as "\&new_page".
       The latter may be cleaner than inlining,	if the routine is quite	long.

       An example of reusing a saved PDF page as a template:

	   my $pdf	= PDF::API2->new();
	   my $template	= PDF::API2->open('pdf/template.pdf');
	   my $new_page_func = sub { return $pdf->import_page($template, 1); }

	   table(
	       ...
	       new_page_func =>	$new_page_func,
	       ...

       This will call a	function to grab a copy	of a template PDF's page 1 and
       insert it as the	new last page of the PDF, as the starting point	for
       the next	overflow (continuation)	page of	the table, if needed. Note
       that the	"$template->openpage(1)" call is unsuitable for	this purpose,
       as it does not insert the page into the current PDF.

       You can also create a blank page	and prefill it with desired content:

	   my $pdf	= PDF::API2->new();
	   my $new_page_func = sub {
	       my $page	= $pdf->page();	# so far, no difference	from default behavior
	       $page->mediaBox(...);  #	set page size/orientation, etc.
	       my $text	= $page->text();
	       # set font, placement, etc.
	       $text->text(...);  # write header, footer, etc.
	       ...
	       return $page;
	   }

	   table(
	       ...
	       new_page_func =>	$new_page_func,
	       ...

       If "new_page_func" is not defined, PDF::Table will simply call
       "$pdf->page()" to generate a new, blank,	"next" page.

       Note that this function is not called for the first page	of a table.
       That one	uses the current $page parameter passed	to the "table()" call.
       It is only called when needed for overflow ("next_y" and	"next_h")
       pages, where it replaces	the $page parameter with a new page framework.
       You may want to consider	using the same function	to create your other
       (non-table) pages, assuming you want the	same format (PDF content)
       across all pages	of the table.

       Cell Render Hook

       cell_render_hook	is a CODE reference to a function called with the
       current cell coordinates. If used, the parameter	"cell_render_hook"
       must be a function reference. It	is most	useful for creating special
       items within a text block, such as a URL	link inside of a cell.	The
       following example adds a	link in	the first column of each non-header
       row:

	   'cell_render_hook'  => sub {
	       my ($page, $first_row, $row, $col, $x, $y, $w, $h) = @_;

	       # Do nothing except for first column (and not a header row)
	       return unless ($col == 0);
	       return if ($first_row);

	       # Create	link
	       my $value = $list_of_vals[$row-1];
	       my $url = "https://${hostname}/app/${value}";

	       my $annot = $page->annotation();
	       $annot->url( $url, -rect	=> [$x,	$y, $x+$w, $y+$h] );
	   },

       Header Row Properties

       If the 'header_props' parameter is used,	it should be a hashref.
       Passing an empty	HASH will trigger a header row initialized with
       Default values.	There is no 'data' variable for	the content, because
       the module asumes that the first	table row will become the header row.
       It will copy this row and put it	on every new page if the 'repeat'
       parameter is set.

       repeat -	Flag showing if	header row should be repeated on every new
       page.
	   Value: 0,1	1-Yes/True, 0-No/False

	   Default: 1 ($repeat_default)

	   See "COMPATIBILITY" if you wish to change it	back to	the old
	   behavior of 0.

	       my $hdr_props = {
		   'font'	=> $pdf->corefont("Helvetica", -encoding => "latin1"),
		   'font_size'	=> 18,
		   'fg_color'	=> '#004444',
		   'bg_color'	=> 'yellow',
		   'repeat'	=> 0,
		   'justify'	=> 'center',
	       };

       Row Properties

       If the 'row_props' parameter is used, it	should be an arrayref of
       hashrefs, with one hashref for each row of the table. The rows are
       counted from top	to bottom, so the hash reference at $row_props[0] will
       hold properties for the first row (from top to bottom).	If you DO NOT
       want to give properties for a row, but to give for another, just	insert
       an empty	hash reference into the	array for the row that you want	to
       skip. This will cause the counting to proceed as	expected and the
       properties to be	applied	at the right rows.

       Each hashref can	contain	any of the keys	shown below:

	   Example:

	       my $row_props = [
		   # This is an	empty hash to indicate default properties for first row
		   {},
		   # the next hash will	hold the properties for	the second row from
		   # top to bottom.
		   {
		       'min_rh'	   => 75,	 # Minimum row height of 75
		       'justify'   => 'right',	 # Right text alignment
		       'font'	   => $pdf->corefont("Helvetica",
						     -encoding => "latin1"),
		       'font_size' => 10,
		       'fg_color'  => 'blue',
		       'bg_color'  => '#FFFF00',
		   },
		   # etc.
	       ];

	   There are no	settings unique	to rows. Do be aware of	when "row 0"
	   may refer to	header row properties!

       Column Properties

       If the 'column_props' parameter is used,	it should be an	arrayref of
       hashrefs, with one hashref for each column of the table.	The columns
       are counted from	left to	right, so the hash reference at	$col_props[0]
       will hold properties for	the first column (from left to right).	If you
       DO NOT want to give properties for a column, but	to give	for another,
       just insert an empty hash reference into	the array for the column that
       you want	to skip. This will cause the counting to proceed as expected
       and the properties to be	applied	at the right columns.

       Each hashref can	contain	any of the keys	shown below:

	   Example:

	       my $col_props = [
		   # This is an	empty hash to indicate default properties for first col.
		   {},
		   # the next hash will	hold the properties for	the second column from
		   # left to right.
		   {
		       'min_w'	   => 100,	 # Minimum column width	of 100
		       'max_w'	   => 150,	 # Maximum column width	of 150
		       'justify'   => 'right',	 # Right text alignment
		       'font'	   => $pdf->corefont("Helvetica",
						     -encoding => "latin1"),
		       'font_size' => 10,
		       'fg_color'  => 'blue',
		       'bg_color'  => '#FFFF00',
		   },
		   # etc.
	       ];

	   There are no	settings unique	to columns.

       NOTE: If	'min_w'	and/or 'max_w' parameter is used in 'col_props', keep
       in mind that it may be overridden by the	calculated minimum/maximum
       cell width so that the table can	be created.  When this happens,	a
       warning will be issued with some	suggestions on what can	be done.  In
       cases of	a conflict between column formatting and odd/even row
       formatting, 'col_props' will override odd/even.

       Cell Properties

       If the 'cell_props' parameter is	used, it should	be an arrayref with
       arrays of hashrefs (of the same dimension as the	data array) with one
       hashref for each	cell of	the table.

       Each hashref can	contain	any of the keys	shown below:

       colspan - Span this cell	over multiple columns to the right.
	   Value: can be any positive number less than the number of columns
	   to the right	of the current column

	   Default: undef

	   NOTE: If you	want to	have regular columns after a colspan, you have
	   to provide "undef" for the columns that should be spanned

	   NOTE: If you	use "colspan" to span a	column,	but provide data for
	   it, your table will be mangled: the spanned-but-data-provided-
	   column will be rendered!  But, as HTML works	the same way, we do
	   not consider	this a bug.

	   Example:

	       # row0 col1 should span 2 cols:
	       @data = ( [ 'r1c1', 'r1c2', 'r1c3' ], ['r2c1+',undef,'r2c3'] );
	       $tab->table( $pdf, $page, \@data, %TestData::required,
		 'cell_props' => [
		     [],
		     [{'colspan' => 2}]
		 ]
	       );

       See the file "examples/colspan.pl" for detailed usage.

       Example:

	   my $cell_props = [
	       [ # This	array is for the first row (0).
		 # If header_props is defined, it will override	these settings.
		   {	# Row 0	cell 0
		       'bg_color'  => '#AAAA00',
		       'fg_color'  => 'yellow',
		       'underline' => [	2, 2 ],
		   },

		   # etc.
	       ],
	       [ # Row 1 (first	data row, if header_props given)
		   {	# Row 1	cell 0
		       'bg_color' => '#CCCC00',
		       'fg_color' => 'blue',
		   },
		   {	# Row 1	cell 1
		       'bg_color' => '#BBBB00',
		       'fg_color' => 'red',
		   },
		   # etc.
	       ],
	       [ # Row 2
		   {	# Row 2	cell 0 span cell 1
		       'colspan' => 2
		   },
		   # etc.
	       ],
	       # etc.
	   ];

	   OR

	   my $cell_props = [];
	   $cell_props->[1][0] = {
	       # Row 2 cell 1
	       'bg_color' => '#CCCC00',
	       'fg_color' => 'blue',
	   };

   text_block()
	   my ($width_of_last_line, $ypos_of_last_line,	$left_over_text) =
	       text_block( $txt, $data,	%settings)

       Description
	   Utility method to create a block of text. The block may contain
	   multiple paragraphs (input $data separated by implicit or explicit
	   newlines "\n").  It is mainly used internally, but you can use it
	   from	outside	for placing formatted text anywhere on the sheet.

	   NOTE: This method will NOT add more pages to	the PDF	instance if
	   the space is	not enough to place the	string inside the block.
	   Leftover text will be returned and has to be	handled	by the caller
	   - i.e., add a new page and a	new block with the leftover.

       Parameters
	       $txt  - a PDF::Builder::Page::Text instance representing	the text tool.
	       $data - a string	that will be placed inside the block, broken up	into
		       lines that fit within the indicated width.
	       %settings - HASH	with geometry and formatting parameters. Note that
			   several parameters are mandatory.

       Returns
	   The return value is a 3 item	list where

	       $width_of_last_line - Width of last line	in the block
	       $final_y	- The Y	coordinate of the block	bottom so that additional
			  content can be added after it
	       $left_over_text - Text that did not fit in the provided box geometry.

       Example
	       # PDF::Builder objects
	       my $page	= $pdf->page();
	       my $txt	= $page->text();

	       my %settings = (
		   # MANDATORY position	and table size
		   'x' => 10,
		   'y' => 570,
		   'w' => 220,
		   'h' => 180,

		   # OPTIONAL PARAMETERS
		   'leading'  => $font_size*1.15 | $distance_between_lines,
		   'align'    => "left|right|center|justify|fulljustify",
				   default: left
		   'max_word_length' =>	$optional_max_word_chars_between_splits
				   default: 20
		   'parspace' => $optional_vertical_space_before_paragraph,
				   default: 0 extra vertical space

		   # Only one of the following parameters can be given.
		   # They override each	other, in the order given. C<hang> is the
		   # highest weight.
		   'hang'     => $optional_hanging_text_to_lead_a_paragraph,
		   'flindent' => $optional_indent_of_first_line,
		   'fpindent' => $optional_indent_of_first_paragraph,
		   'indent'   => $optional_indent_of_text_to_every_non_first_line,
	       );

	       my ( $width_of_last_line, $final_y, $left_over_text ) =
		    $pdftable->text_block( $txt, $data,	%settings );

VERSION
       1.002

AUTHOR
       Daemmon Hughes

DEVELOPMENT
       Further development Versions 0.02 -- 0.11 - Desislav Kamenov

       Further development since Ver: 0.12 - Phil Perry

COPYRIGHT AND LICENSE
       Copyright (C) 2006 by Daemmon Hughes, portions Copyright	2004 Stone
       Environmental Inc. (www.stone-env.com) All Rights Reserved.

       Copyright (C) 2020 by Phil M Perry.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.7 or, at
       your option, any	later version of Perl 5	you may	have available.	 Note
       that Perl 5.10 is the minimum supported level.

PLUGS
       by Daemmon Hughes
	   Much	of the original	development work on this module	was sponsered
	   by Stone Environmental Inc. (www.stone-env.com).

	   The text_block() method is a	slightly modified copy of the one from
	   Rick	Measham's PDF::API2 tutorial at
	   http://pdfapi2.sourceforge.net/cgi-bin/view/Main/YourFirstDocument

       by Desislav Kamenov (@deskata on	Twitter)
	   The development of this module was supported	by SEEBURGER AG
	   (www.seeburger.com) till year 2007

	   Thanks to my	friends	Krasimir Berov and Alex	Kantchev for helpful
	   tips	and QA during development of versions 0.9.0 to 0.9.5

	   Thanks to all GitHub	contributors!

CONTRIBUTION
       PDF::Table is on	GitHub.	You are	more than welcome to contribute!

       https://github.com/PhilterPaper/PDF-Table

SEE ALSO
       PDF::API2, PDF::Builder

perl v5.32.1			  2020-12-27			 PDF::Table(3)

NAME | SYNOPSIS | DESCRIPTION | COMPATIBILITY | METHODS | VERSION | AUTHOR | DEVELOPMENT | COPYRIGHT AND LICENSE | PLUGS | CONTRIBUTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDF::Table&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help