File: README — Documentation for Spreadsheet-HTML (1.0.3)

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 <thead>, <tbody> and <tfoot> sections.
  When tgroups is set to 1, the <tfoot> section is omitted. The last row of the data
  is found at the end of the <tbody> section instead. (loose) When tgroups is set to 2,
  the <tfoot> section is found in between the <thead> and <tbody> 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 <td> tags, no <th> 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' }

  Hash. Apply these attributes.

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

  <th> and <td> 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 } ]

  <th> and <td> 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 <tr> tag within the <thead> group.

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

tfoot.tr

  When tgroups is 2, this tag parameter is available to control the attributes of
  the <tr> tag within the <tfoot> 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