Description

Just another HTML table generator for ruby.
Generate HTML tables with ease (HTML4, XHTML and HTML5).
Generate portrait, landscape and other rotated views. Handles
rotating table attributes via HTML-AutoTag.

Installation

gem install Spreadsheet-HTML

Synopsis

require 'Spreadsheet/HTML'

data = Array[ [1,2,3], [4,5,6], [7,8,9] ]
generator = Spreadsheet::HTML.new()
puts generator.generate( data )
puts generator.generate( 'data' => data )

generator = Spreadsheet::HTML.new( 'data' => data, 'indent' => "\t" )
puts generator.portrait( 'encodes' => 1 )
puts generator.landscape( 'encode' => 1 )

puts generator.generate( 'tgroups' => 1 )
puts generator.generate( 'tgroups' => 2, 'indent' => nil )

puts generator.generate( 'tr' => { 'class' => %w{ odd even } } )

# See t/ directory for more examples

Dependencies

HTML-AutoTag

Methods

With the exception of new, all methods return an HTML table as a string.

new( params ) Constructs a new generator configured with given params. These params will be used for each call to a generator method. Any params specified in the constructor may be overriden in a subsequent call to a generator method (which are listed next).

generate( params ) Generates an HTML table with headings positioned at the top.

portrait( params ) Generates an HTML table with headings positioned at the top.

north( params ) Generates an HTML table with headings positioned at the top.

landscape( params ) Generates an HTML table with headings positioned at the left.

west( params ) Generates an HTML table with headings positioned at the left.

south( params ) Generates an HTML table with headings positioned at the bottom.

east( params ) Generates an HTML table with headings positioned at the right.

Literal Parameters

Literal Parameters provides the means to modify the macro aspects of the table,
such as indentation, encoding, data source and table orientation.

data The data to be rendered as an HTML table. Array of Arrays.

'data' = > [ [ 1, 2, 3 ], [ 4, 5, 6 ], [7, 8, 9 ] ]

tgroups Integer (0, 1 or 2). Group table rows into , and sections. When tgroups is set to 1, the section is omitted. The last row of the data is found at the end of the section instead. (loose) When tgroups is set to 2, the section is found in between the and sections. (strict)

'tgroups' => 1
'tgroups' => 2

indent The string to indent each row by. Defaults to undefined which produces no indentation. Automatically adds newlines when set to any defined value.

'indent' => '    '
'indent' => "\t"

level Positive integer. The level to start indentation at. This is useful for matching the nesting styles of original HTML text that you may wish in insert into. (A value of 4 says "apply the repitition operator to the value of indent 4 times.)

'level' => 3

empty String. Render any empty cells with this value. Defaults to &nbps;

'empty' => ''

encode Boolean. Whether or not to Encode entities.

'encode' => 1

encodes String. Encode these HTML entities. Pass string with chars you want encoded or leave blank for default control and high bit chars and <>!'"

'encodes' => '<>'

matrix Boolean. Render the headings row with only tags, no tags.

'matrix' => 1

headless Boolean. Render the table without the headings row at all.

'headless' => 1

theta Rotates table clockwise for positive values and counter-clockwise for negative values. Default is 0: headings at top. 90 yields headings at right, 180 yields headings at bottom. 270 yields headings at left. To achieve landscape, use -270 (or use the landscape() method).

'theta' => -270

flip Flips the table horizontally from the perspective of the headings "row" by negating the value of theta.

'flip' => 1

pinhead Works in conjunction with theta to ensure reporting readability. Without it, south() and east() would have data cells arranged in reverse order.

'pinhead' => 1

fill Can be used instead of data to create a "blank" table or with data to pad rows and cells.

'fill' => '8x12' # 8 rows, 12 columns

Dynamic Parameters

Dynamic parameters provide a means to control the micro elements of the table,
such as modifying headings by their name and rows and columns by their indices.
They contain leading underscores to seperate them from literal and tag parameters.
They accepts Hashes for use as tag attributes, Procs or lambdas for altering the
CDATA of the cell, or Arrays that contain either (just like the 'td' and 'th' Tag
Parameters described below).

_rX Apply these attributes to row X (zero index based).

'_r2' => { 'class' => 'third-row' }
'_r2' => lambda { |c| c.upcase }
'_r2' => [ lambda { |c| c.upcase }, { 'class' => 'third-row' } ]

cX Apply these attributes to colum X (zero index based). You can also alias any column by the value of the heading name in that column prepended with underscore ()

'_c4' => { 'class' => 'fifth-column' }
'_c4' => lambda { |c| c.upcase }
'_c4' => [ lambda { |c| c.upcase }, { 'class' => 'fifth-column' } ]

'_occupation' => { 'class' => 'foo' }
'_salary' => lambda { |c| c.capitalize }

_rXcY Apply these attributes to colum Y in row X (zero index based).

'_r2c4' => { 'class' => 'third-row-fifth-column' }
'_r2c4' => lambda { |c| c.upcase }
'_r2c4' => [ lambda { |c| c.upcase }, { 'class' => 'third-row-fifth-column' } ]

Tag Parameters

Tag Parameters provide a means to control the attributes of the table's tags, and in
the case of <th> and <td> the contents via callback subroutines. Although
similar in form, they are differentiated from litertal parameters because they share
the names of the actual HTML table tags.

table Hash. Apply these attributes.

'table' => { 'class' => 'spreadsheet' }

thead Hash. Apply these attributes.

'thead' => { 'class' => 'headings' }

tfoot Hash. Apply these attributes.

'tfoot' => { 'class' => 'footings' }

tbody Hash. Apply these attributes.

'tbody' => { 'class' => 'bodyings' }

tr Hash. Apply these attributes.

'tr => { 'class' => %w{ odd even } }

th and are the only Tag Parameters that also accept callback methods.

'th' => { 'style' => { 'color' => %w{ red green blue } } }
'th' => lambda { |c| c.upcase }
'th' => [ { 'style' => { 'color' => %w{ red green blue } }, lambda { |c| c.upcase } ]

td and are the only Tag Parameters that also accept callback methods.

'td' => { 'style' => { 'color' => %w{ red green blue } } }
'td' => lambda { |c| c.upcase }
'td' => [ { 'style' => { 'color' => %w{ red green blue } }, lambda { |c| c.upcase } ]

caption Caption is special in that you can either pass a string to be used as CDATA or a hash whose only key is the string to be used as CDATA.

'caption' => 'Just Another Title'

'caption' => { 'A Title With Attributes' => { 'align' => 'bottom' } }

colgroup Add colgroup tag(s) to the table. Use an AoH for multiple.

colgroup => { 'span => '2', 'style' => { 'background-color' => 'orange' } }

colgroup => Array[ { 'span => '20' }, { 'span' => '1', 'class' => 'end' } ]

col Add col tag(s) to the table. Use an AoH for multiple. Wraps tags within a colgroup tag. Same usage as colgroup.

col => { 'span' => '2', 'style' => { 'background-color' => 'orange' } }

col => Array[ { 'span' => 20 }, { 'span' => '1', 'class' => 'end' } ]

thead.tr When tgroups is 1 or 2, this tag parameter is available to control the attributes of the tag within the group.

'thead.tr' => { 'class' => 'body-cell' }

tfoot.tr When tgroups is 2, this tag parameter is available to control the attributes of the tag within the group.

'tbody.tr' => { 'class' => 'body-cell' }

License

MIT

Warranty

This package is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.

Author

Jeff Anderson
jeffa@cpan.org