Return to lontable.pm CVS log

Up to [LON-CAPA] / loncom / xml

Initial definition of the data structures and implementation of the
new operator.

This file will contain an object oriented interface to the data structures
needed to define a table in 'tex' mode and generate it using the
Latex::Table package.

    1: # The LearningOnline Network with CAPA
    2: #  Generating TeX tables.
    3: #
    4: # $Id: lontable.pm,v 1.1 2008/11/24 11:56:53 foxr Exp $
    5: # 
    6: #
    7: # Copyright Michigan State University Board of Trustees
    8: #
    9: # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
   10: #
   11: # LON-CAPA is free software; you can redistribute it and/or modify
   12: # it under the terms of the GNU General Public License as published by
   13: # the Free Software Foundation; either version 2 of the License, or
   14: # (at your option) any later version.
   15: #
   16: # LON-CAPA is distributed in the hope that it will be useful,
   17: # but WITHOUT ANY WARRANTY; without even the implied warranty of
   18: # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   19: # GNU General Public License for more details.
   20: #
   21: # You should have received a copy of the GNU General Public License
   22: # along with LON-CAPA; if not, write to the Free Software
   23: # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   24: #
   25: # /home/httpd/html/adm/gpl.txt
   26: #
   27: # http://www.lon-capa.org/
   28: ## Copyright for TtHfunc and TtMfunc by Ian Hutchinson. 
   29: # TtHfunc and TtMfunc (the "Code") may be compiled and linked into 
   30: # binary executable programs or libraries distributed by the 
   31: # Michigan State University (the "Licensee"), but any binaries so 
   32: # distributed are hereby licensed only for use in the context
   33: # of a program or computational system for which the Licensee is the 
   34: # primary author or distributor, and which performs substantial 
   35: # additional tasks beyond the translation of (La)TeX into HTML.
   36: # The C source of the Code may not be distributed by the Licensee
   37: # to any other parties under any circumstances.
   38: #
   39: 
   40: # This module is a support packkage that helps londefdef generate
   41: # LaTeX tables using the LaTeX::Table package.  A prerequisite is that
   42: # the print generator must have added the following to the LaTeX header:
   43: #
   44: #  \usepackage{xtab}
   45: #  \usepackage{booktabs}
   46: #  \usepackage{array}
   47: #  \usepackage{colortbl}
   48: #  \usepackage{xcolor}
   49: #
   50: #  These packages are installed in the packaged LaTeX distributions we know of as of
   51: #  11/24/2008
   52: #
   53: 
   54: 
   55: 
   56: package Apache::lontable;
   57: use strict;
   58: use LaTeX::Table;
   59: 
   60: 
   61: =pod
   62: 
   63: =head1  lontable Table generation assistant for the LaTeX target
   64: 
   65: This module contains support software for generating tables in LaTeX output mode 
   66: In this implementation, we use the LaTeX::Table package to do the actual final formatting.
   67: Each table creates a new object.  Table objects can have global properties configured.
   68: The main operations on a table object are:
   69: 
   70: =over 3
   71: 
   72: =item start_row  
   73: 
   74: Opens a new table row.
   75: 
   76: =item end_row
   77: 
   78: Closes a table row.
   79: 
   80: =item start_header
   81: 
   82: Starts a new row that has the header attribute (e.g. <th> tagged row).
   83: header rows are ended with an end_row just like any ordinary row.
   84: 
   85: =item configure_row
   86: 
   87: Modifies a configuration item in the currently open row.
   88: 
   89: =item generate
   90: 
   91: Returns the generated table string.
   92: 
   93: =item configure
   94: 
   95: Configures a table's global configuration.
   96: 
   97: =back
   98: 
   99: =cut
  100: 
  101: =pod
  102: 
  103: =head2 new - create a new object.
  104: 
  105: Create a new table object.  Any of the raw table configuration items can be
  106: modified by this.  These configuration items include:
  107: 
  108:   my $table = lontable::new(\%config_hash)
  109: 
  110: =over3
  111: 
  112: =item alignment
  113: 
  114: Table alignment.  Some table styles support this but not all.
  115: 
  116: =item tableborder
  117: 
  118: If true, a border is drawn around the table.
  119: 
  120: =item cellborder
  121: 
  122: If true, borders are drawn around the cells inside a table.
  123: 
  124: =item caption
  125: 
  126: The table caption text.
  127: 
  128: =item theme
  129: 
  130: The theme of the table to use.  Defaults to Zurich.  Themes we know about are:
  131: NYC, NYC2, Zurich, Berlin, Dresden, Houston, Miami, plain, Paris.  Other themes can be added
  132: to the LaTeX::Table package, and they will become supported automatically, as theme names are
  133: not error checked.  Any use of a non-existent theme is reported by the LaTeX::Table package
  134: when the table text is generated.
  135: 
  136: =back
  137: 
  138: =head3 Member data
  139: 
  140: The object hash has the following members:
  141: 
  142: =over 3
  143: 
  144: =item column_count 
  145: 
  146: Maintained internally, the number of colums in the widest row.
  147: 
  148: =item alignment
  149: 
  150: Table alignment (configurable) "left", "center", or "right".
  151: 
  152: =item outer_border
  153: 
  154: True if a border should be drawn around the entire table (configurable)
  155: 
  156: =item inner_borders
  157: 
  158: True if a border should be drawn around all cells (configurable).
  159: 
  160: =item caption
  161: 
  162: Table caption (configurable).
  163: 
  164: =item theme
  165: 
  166: Theme desired (configurable).
  167: 
  168: =item row_open 
  169: 
  170: True if a row is open and not yet closed.
  171: 
  172: =item rows
  173: 
  174: Array of row data. This is an array of hashes described below.
  175: 
  176: =back
  177: 
  178: =head3 Row data.
  179: 
  180: Each row of table data is an element of the rows hash array.  Hash elements are
  181: 
  182: =over 3
  183: 
  184: =item is_header
  185: 
  186: True if the user wants to format this row like a header.  This row will be used to generate
  187: the table header.  All header rows will be gathered together into the table header.  If there
  188: are multiple table headers interspersed with non table header data, this can lead to some 
  189: surprises.
  190: 
  191: =item default_halign 
  192: 
  193: Default horizontal alignment for cells in this row.
  194: 
  195: =item default_valign
  196: 
  197: Default vertical alignment for cells in this row (may be ignored).
  198: 
  199: =item cells
  200: 
  201: Array of hashes where each element represents the data for a cell.
  202: The contents of each element of this hash are described below:
  203: 
  204: =over 3
  205: 
  206: =item halign
  207: 
  208: If present, overrides the row default horizontal alignment.
  209: 
  210: =item valign
  211: 
  212: if present, override the row default vertical alignment.
  213: 
  214: =item rowspan
  215: 
  216: If present, indicates the number of rows this cell spans.
  217: 
  218: =item colspan
  219: 
  220: If present indicates the number of columns this cell spans.
  221: Note that a cell can span both rows and columns.
  222: 
  223: =item contents
  224: 
  225: The contents of the cell.
  226: 
  227: =back
  228: 
  229: =back
  230: 
  231: =cut
  232: 
  233: sub new {
  234:     my ($class, $configuration) = @_;
  235: 
  236:     #  Initialize the object member data with the default values
  237:     #  then override with any stuff in $configuration.
  238: 
  239:     my $self = {
  240: 	alignment      => "left",
  241: 	outer_border   => 0,
  242: 	inner_borders  => 0,
  243: 	caption        => "",
  244: 	theme          => "Zurich",
  245: 	column_count   => 0,
  246: 	row_open       => 0,
  247: 	rows           => [],
  248:     };
  249: 
  250:     foreach my $key (keys %$configuration) {
  251: 	$self->{$key} = $$configuration{$key};
  252:     }
  253: 
  254:     bless($self, $class);
  255: 
  256:     return $self;
  257: }
  258: 
  259: #-------------------------------------------------------------------------
  260: #
  261: #  Methods that get/set table global configuration.
  262: 
  263: 
  264: 
  265: 
  266: #   Mandatory initialization.
  267: 
  268: 1;
  269: __END__