# The LearningOnline Network with CAPA
# Generating TeX tables.
#
# $Id: lontable.pm,v 1.2 2008/11/25 12:27:34 foxr Exp $
#
#
# Copyright Michigan State University Board of Trustees
#
# This file is part of the LearningOnline Network with CAPA (LON-CAPA).
#
# LON-CAPA 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.
#
# LON-CAPA 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.
#
# You should have received a copy of the GNU General Public License
# along with LON-CAPA; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# /home/httpd/html/adm/gpl.txt
#
# http://www.lon-capa.org/
## Copyright for TtHfunc and TtMfunc by Ian Hutchinson.
# TtHfunc and TtMfunc (the "Code") may be compiled and linked into
# binary executable programs or libraries distributed by the
# Michigan State University (the "Licensee"), but any binaries so
# distributed are hereby licensed only for use in the context
# of a program or computational system for which the Licensee is the
# primary author or distributor, and which performs substantial
# additional tasks beyond the translation of (La)TeX into HTML.
# The C source of the Code may not be distributed by the Licensee
# to any other parties under any circumstances.
#
# This module is a support packkage that helps londefdef generate
# LaTeX tables using the LaTeX::Table package. A prerequisite is that
# the print generator must have added the following to the LaTeX header:
#
# \usepackage{xtab}
# \usepackage{booktabs}
# \usepackage{array}
# \usepackage{colortbl}
# \usepackage{xcolor}
#
# These packages are installed in the packaged LaTeX distributions we know of as of
# 11/24/2008
#
package Apache::lontable;
use strict;
use LaTeX::Table;
=pod
=head1 lontable Table generation assistant for the LaTeX target
This module contains support software for generating tables in LaTeX output mode
In this implementation, we use the LaTeX::Table package to do the actual final formatting.
Each table creates a new object. Table objects can have global properties configured.
The main operations on a table object are:
=over 3
=item start_row
Opens a new table row.
=item end_row
Closes a table row.
=item start_header
Starts a new row that has the header attribute (e.g. <th> tagged row).
header rows are ended with an end_row just like any ordinary row.
=item configure_row
Modifies a configuration item in the currently open row.
=item generate
Returns the generated table string.
=item configure
Configures a table's global configuration.
=back
=cut
=pod
=head2 new - create a new object.
Create a new table object. Any of the raw table configuration items can be
modified by this. These configuration items include:
my $table = lontable::new(\%config_hash)
=over3
=item alignment
Table alignment. Some table styles support this but not all.
=item tableborder
If true, a border is drawn around the table.
=item cellborder
If true, borders are drawn around the cells inside a table.
=item caption
The table caption text.
=item theme
The theme of the table to use. Defaults to Zurich. Themes we know about are:
NYC, NYC2, Zurich, Berlin, Dresden, Houston, Miami, plain, Paris. Other themes can be added
to the LaTeX::Table package, and they will become supported automatically, as theme names are
not error checked. Any use of a non-existent theme is reported by the LaTeX::Table package
when the table text is generated.
=back
=head3 Member data
The object hash has the following members:
=over 3
=item column_count
Maintained internally, the number of colums in the widest row.
=item alignment
Table alignment (configurable) "left", "center", or "right".
=item outer_border
True if a border should be drawn around the entire table (configurable)
=item inner_borders
True if a border should be drawn around all cells (configurable).
=item caption
Table caption (configurable).
=item theme
Theme desired (configurable).
=item row_open
True if a row is open and not yet closed.
=item rows
Array of row data. This is an array of hashes described below.
=back
=head3 Row data.
Each row of table data is an element of the rows hash array. Hash elements are
=over 3
=item is_header
True if the user wants to format this row like a header. This row will be used to generate
the table header. All header rows will be gathered together into the table header. If there
are multiple table headers interspersed with non table header data, this can lead to some
surprises.
=item default_halign
Default horizontal alignment for cells in this row.
=item default_valign
Default vertical alignment for cells in this row (may be ignored).
=item cells
Array of hashes where each element represents the data for a cell.
The contents of each element of this hash are described below:
=over 3
=item halign
If present, overrides the row default horizontal alignment.
=item valign
if present, override the row default vertical alignment.
=item rowspan
If present, indicates the number of rows this cell spans.
=item colspan
If present indicates the number of columns this cell spans.
Note that a cell can span both rows and columns.
=item contents
The contents of the cell.
=back
=back
=cut
sub new {
my ($class, $configuration) = @_;
# Initialize the object member data with the default values
# then override with any stuff in $configuration.
my $self = {
alignment => "left",
outer_border => 0,
inner_border => 0,
caption => "",
theme => "Zurich",
column_count => 0,
row_open => 0,
rows => [],
};
foreach my $key (keys %$configuration) {
$self->{$key} = $$configuration{$key};
}
bless($self, $class);
return $self;
}
#-------------------------------------------------------------------------
#
# Methods that get/set table global configuration.
#
=pod
=head2 Gets/set alignment.
If the method is passed a new alignment value, that replaces the current one.
Regardless, the current alignment is used:
=head3 Examples:
my $align = $table->alignment(); # Return current alignment
$table->alignment("center"); # Attempt centered alignment.
=cut
sub alignment {
my ($self, $new_value) = @_;
if (defined($new_value)) {
$self->{alignment} = $new_value;
}
return $self->{alignment};
}
=pod
=head2 table_border
Set or get the presence of an outer border in the table.
If passed a parameter, that parameter replaces the current request
for or not for an outer border. Regardless, the function returns
the final value of the outer_border request.
=head3 Examples:
$table->table_border(1); # Request an outer border.
my $outer_requested = $table->table_border();
=cut
sub table_border {
my ($self, $new_value) = @_;
if (defined($new_value)) {
$self->{outer_border} = $new_value;
}
return $self->{outer_border};
}
=pod
=head2 cell_border
Set or get the presence of a request for cells to have borders
drawn around them. If a paramter is passed, it will be treated as
a new value for the cell border configuration. Regardless,the final
value of that configuration parameter is returned.
=head3 Examples:
my $cell_borders = $table->cell_border(); # ask if cell borders are requested.
$table->cell_border(1); # Request cell borders.
=cut
sub cell_borders {
my ($self, $new_value) = @_;
if (defined($new_value)) {
$self->{inner_border} = $new_value;
}
reurn $self->{inner_border};
}
=pod
=head2 caption
Gets and/or sets the caption string for the table. The caption string appears to label
the table. If a parameter is supplied it will become the new caption string.k
=head3 Examples:
$my caption = $table->caption();
$table->caption("This is the new table caption");
=cut
sub caption {
my ($self, $new_value) = @_;
if (defined($new_value)) {
$self->catpion = $new_value;
}
return $self->caption;
}
=pod
=head2 theme
Gets and optionally sets the table theme. The table theme describes how the
table will be typset by the table package. If a parameter is supplied it
will be the new theme selection.
=head3 Examples:
my $theme = $table->theme();
$table->theme("Dresden");
=cut
sub theme {
my ($self, $new_value) = @_;
if (defined($new_value)) {
$self->theme = $new_value;
}
return $self->theme;
}
=pod
=head2 start_row
Begins a new row in the table. If a row is already open, that row is
closed off prior to starting the new row. Rows can have the following attributes
which are specified by an optional hash passed in to this function.
=over 3
=item default_halign
The default horizontal alignment of the row. This can be "left", "center", or "right"
=item default_valign
The default vertical alignment of the row. This can be "top", "center", or "bottom"
=back
=head3 Examples:
$table_start_row(); # no attributes.
$table_start({default_halign => "center",
default_valign => "bottom"}); # Create setting the attrbutes.
=cut
sub start_row {
my ($self, %config) = @_;
if ($self->row_open) {
$self->end_row;
}
my $row_hash = {
is_header => 0,
default_halign => "left",
default_valign => "top",
cells => []
};
# Override the defaults if the config hash is present:
if (defined(%config)) {
foreach my $key (keys %config) {
$row_hash->{$key} = $config{$key};
}
}
my $rows = $self->{rows};
push(@$rows, $row_hash);
$self->row_open = 1; # Row is now open and ready for business.
}
=pod
=head2 end_row
Closes off a row. Once closed, cells cannot be added to this row again.
=head3 Examples:
$table->close_row();
=cut
sub close_row {
my ($self) = @_;
if ($self->row_open) {
# Mostly we need to determine if this row has the maximum
# cell count of any row in existence in the table:
my $row = $self->{rows}[-1];
my $cells = $row->{cells};
my $cell_count = scalar(@$cells);
if ($cell_count > $self->{column_count}) {
$self->{column_count} = $cell_count;
}
$self->row_closed;
}
}
=pod
=head2 start_header
Starts a row that is a header. This is the same as start_row,but the is_header flag
is set to true.
=cut
sub start_header {
my ($self, %config) = @_;
$self->start_row(%config);
$self->{rows}[-1]->is_header = 1;
}
# Mandatory initialization.
1;
__END__
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>