NAME

Excel::Template - Excel::Template

SYNOPSIS

First, make a template. This is an XML file, describing the layout of the spreadsheet.

For example, test.xml:

<workbook>
    <worksheet name="tester">
        <cell text="$HOME"/>
        <cell text="$PATH"/>
    </worksheet>
</workbook>

Now, create a small program to use it:

#!/usr/bin/perl -w
use Excel::Template

# Create the Excel template
my $template = Excel::Template->new(
    filename => 'test.xml',
);

# Add a few parameters
$template->param(
    HOME => $ENV{HOME},
    PATH => $ENV{PATH},
);

$template->write_file('test.xls');

If everything worked, then you should have a spreadsheet in your work directory that looks something like:

           A                B                C
  +----------------+----------------+----------------
1 | /home/me       | /bin:/usr/bin  |
  +----------------+----------------+----------------
2 |                |                |
  +----------------+----------------+----------------
3 |                |                |

DESCRIPTION

This is a module used for templating Excel files. Its genesis came from the need to use the same datastructure as HTML::Template, but provide Excel files instead. The existing modules don't do the trick, as they require replication of logic that's already been done within HTML::Template.

MOTIVATION

I do a lot of Perl/CGI for reporting purposes. In nearly every place I've been, I've been asked for HTML, PDF, and Excel. HTML::Template provides the first, and PDF::Template does the second pretty well. But, generating Excel was the sticking point. I already had the data structure for the other templating modules, but I just didn't have an easy mechanism to get that data structure into an XLS file.

USAGE

new()

This creates a Excel::Template object. If passed a FILENAME parameter, it will parse the template in the given file. (You can also use the parse() method, described below.)

new() accepts an optional BIG_FILE parameter. This will attempt to change the renderer from Spreadsheet::WriteExcel to Spreadsheet::WriteExcel::Big. You must already have Spreadsheet::WriteExcel::Big installed on your system.

new() also accepts an optional USE_UNICODE parameter. This will use Unicode::String to represent strings instead of Perl's internal string handling. You must already have Unicode::String installed on your system.

The USE_UNICODE parameter will be ignored if you are using Perl 5.8 or higher as Perl's internal string handling is unicode-aware.

NOTE: Spreadsheet::WriteExcel::Big and mod_perl clash for some reason. This is outside of my control.

param()

This method is exactly like HTML::Template's param() method.

parse() / parse_xml()

This method actually parses the template file. It can either be called separately or through the new() call. It will die() if it runs into a situation it cannot handle.

write_file()

Create the Excel file and write it to the specified filename, if possible. (This is when the actual merging of the template and the parameters occurs.)

output()

It will act just like HTML::Template's output() method, returning the resultant file as a stream, usually for output to the web. (This is when the actual merging of the template and the parameters occurs.)

SUPPORTED NODES

This is a partial list of nodes. See the other classes in this distro for more details on specific parameters and the like.

Every node can set the ROW and COL parameters. These are the actual ROW/COL values that the next CELL-type tag will write into.

• WORKBOOK

  This is the node representing the workbook. It is the parent for all other nodes.

• WORKSHEET

  This is the node representing a given worksheet.

• IF

  This node represents a conditional expression. Its children may or may not be rendered. It behaves just like HTML::Template's TMPL_IF.

• LOOP

  This node represents a loop. It behaves just like HTML::Template's TMPL_LOOP.

• ROW

  This node represents a row of data. This is the A in A1.

• FORMAT

  This node varies the format for its children. All formatting options supported in Spreadsheet::WriteExcel are supported here. There are also a number of formatting shortcuts, such as BOLD and ITALIC.

• BACKREF

  This refers back to a cell previously named.

• CELL

  This is the actual cell in a spreadsheet.

• FORMULA

  This is a formula in a spreadsheet.

• RANGE

  This is a BACKREF for a number of identically-named cells.

• VAR

  This is a variable. It is generally used when the 'text' attribute isn't sufficient.

BUGS

None, that I know of.

SUPPORT

This is production quality software, used in several production web applications.

AUTHOR

Rob Kinyon (rob.kinyon@gmail.com)

CONTRIBUTORS

There is a mailing list at http://groups.google.com/group/ExcelTemplate

Robert Graff -

• Finishing formats

• Fixing several bugs in worksheet naming

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1), HTML::Template, Spreadsheet::WriteExcel.

cpanm Excel::Template

perl -MCPAN -e shell
install Excel::Template