File: user_guide.txt

TABLE CLASS USER GUIDE

6/16/00 2:26 PM by jestevez

Copyright (C) 2000 Travel-Italy.com

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

-----------------------------------------------------------------

SETTING TABLE DEFAULTS

Table defaults are handled by the constructor.
The contstructor takes one argument, an array.

$polly = new table ( array ( 'bgcolor'=>'blue', 'cellpadding'=>'3' ) );
$polly->start_table();
$polly->add_row ( array( "Upper Left", "Upper Right" ) ) ;
$polly->add_row (array( "Lower Left", "Lower Right" ) );
$polly->finish_table ( );
print $polly->return ( );

-----------------------------------------------------------------


SETTING ROW AND COL ATTRIBUTES

Set attributes (either column or row) to make the magic happen.

Two methods set attributes, they take the following form...

add_col_attribute ( ATTRIBUTE_NAME, ATTRIBUTE_VALUES, LOOP_INSTRUCTION )
add_row_attribute ( ATTRIBUTE_NAME, ATTRIBUTE_VALUES, LOOP_INSTRUCTION )

The methods above take two, optionally three arguments.

(1) ATTRIBUTE_NAME (string)...
is the name of a name-value pair put inside the TD tag.
Example:  bgcolor or colspan (some ATTRIBUTE_NAME values are special, like 'bold' and 'nowrap'.  
See documentation below.)

(2) ATTRIBUTE_VALUES (array)...
is an array holding the values passed to 
the name-value pair with each new cell added.  Empty strings are skipped.
Example:  If you are setting a col bgcolor attribute, the array might be  
array ( 'red', blue' ).  The first col would be red, the second col would be blue.

(3) LOOP_INSTRUCTION... (optional integer)
The number of times to loop through (2) above
before the attribute 'expires'.  If not set, an attribute will loop
indefinately.

-----------------------------------------------------------------

SIMPLE TABLE EXAMPLE

$polly = new table ( );
$polly->start_table();
$polly->add_row(array("Upper Left", "Upper Right"));
$polly->add_row(array("Lower Left", "Lower Right"));
$polly->finish_table();
print $polly->return_table();

-----------------------------------------------------------------

COMPLEX TABLE EXAMPLE

$polly = new table ( );

// Make 1st col red
// Make 2nd col white
// Make 3rd col red,
// Make 4th col white
// All other cols have not color attribute.
$polly->add_col_attribute( "bgcolor", array ( 'RED', 'WHITE' ), 2) ;

// Do nothing to first row.
// Make second row bold.
// Do nothing to all other rows.
$polly->add_row_attribute( "bold", array ( 0, 1 ), 1);

// Do nothing to first three rows.
// Make all cells in rows 4, 5, and 6
// have an COLSPAN of 2.
$polly->add_row_attribute( "cellspan", array ( '', '', '', 2, 2, 2 ), 1 );

$polly->start_table ( );
$polly->add_row( array( "1 Left", "1 Right" ) );
$polly->add_row( array( "2 Left", "2 Right" ) );
$polly->add_row( array( "3 Left", "3 Right" ) );
$polly->add_row( array( "4 Center" ) );
$polly->add_row( array( "5 Center" ) );
$polly->add_row( array( "6 Center" ) );
$polly->finish_table ( );

print $polly->return_table( );

-----------------------------------------------------------------

HOW TO OVERRIDE ROW AND COL ATTRIBUTES

Say you set up a table so that the first row is orange,
the second is blue, then orange, then blue, and so on, like 
this...

$cb = new table ();
$cb->add_row_attribute ( 'bgcolor', array ( 'orange', 'blue' ));
$cb->start_table ();
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->finish_table ();
$table =  $cb->return_table();

Now, after some though you decide you want one
red cell.

Here is what we were passing to add_row:

array ( 1, 2, 3, 4, 5, 6 )

We want to change the first cell, which is 1.

To do this we make the first cell an array where the first element of the array
is the contents of the cell and all other elements are name value pairs
which are attributes to pass to the cell.  These are "local" values which will
override any "global" values set by set_col_attribute and set_row_attribute.

So:    1   becomes     array ( 1, 'bgcolor'=>'red' ) 

We put this back in the array we pass to add_row...

array ( array ( 1, 'bgcolor'=>'red'), 2, 3, 4, 5, 6)

And we get this...

$cb = new stable ();
$cb->add_row_attribute ( 'bgcolor', array ( 'orange', 'blue' ));
$cb->start_table ();
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( array (1, 'bgcolor'=>'red'), 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->add_row ( array ( 1, 2, 3, 4, 5, 6 ) );
$cb->finish_table ();
$table =  $cb->return_table();

So, to override values set with set_col_attribute and set_row_attribute
you need to make the cell you want to change an array such
that the first element is the content and the other elements are name
value pairs.

-----------------------------------------------------------------

ADDING SEVERAL ROWS AT ONCE

Use add_mulitple_rows () and pass an array of arrays.

-----------------------------------------------------------------

DEBUGGING

To turn on debugging...
$polly = new table ( array ( 'debugging'=>1 ));

-----------------------------------------------------------------

LIMITATIONS

(1) There is no way to take control of an attribute at an arbitrary point.
All attribute controls start at row one, cell one.

(2) NOWRAP and BOLD can not override attributes set
with add_col_attribute and add_row_attribute

-----------------------------------------------------------------

NOWRAP AND BOLD

Turn turn bold or nowrap on for a col or row, use and array of
boolean values for the second argument to the control.

-----------------------------------------------------------------

USING TABLE TEMPLATES

Table templates can be used to store the attributes for your 
favorite table desgin.  Two table template samples are bundled
with this release:  mustang.tpl and two_col_form.tpl

All template names must end with '.tpl'

To use either one, you must put it in the directory
specified by the object property path_to_table_templates

Then use the method use_template ().

For example...

use_template ( 'mustang' );

Do not pass the '.tpl' extension to use_template ().

-----------------------------------------------------------------

HINTS

* Use pass_thru ( ) to sneak in hidden fields or form tags.
* Use templates to standardize results from db queries.
* Send jestevez@travel-italy.com any questions about this class.


**********************************************************************/