.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\" ========================================================================
.\"
.IX Title "Excel::Template 3pm"
.TH Excel::Template 3pm "2017-07-13" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Excel::Template \- Excel::Template
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
First, make a template. This is an \s-1XML\s0 file, describing the layout of the
spreadsheet.
.PP
For example, test.xml:
.PP
.Vb 6
\&
\&
\& |
\& |
\&
\&
.Ve
.PP
Now, create a small program to use it:
.PP
.Vb 1
\& #!/usr/bin/perl \-w
\&
\& use strict;
\&
\& use Excel::Template;
\&
\& # Create the Excel template
\& my $template = Excel::Template\->new(
\& filename => \*(Aqtest.xml\*(Aq,
\& );
\&
\& # Add a few parameters
\& $template\->param(
\& HOME => $ENV{HOME},
\& PATH => $ENV{PATH},
\& );
\&
\& $template\->write_file(\*(Aqtest.xls\*(Aq);
.Ve
.PP
If everything worked, then you should have a spreadsheet called text.xls in your working directory that looks something like:
.PP
.Vb 7
\& A B C
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& 1 | /home/me | /bin:/usr/bin |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& 2 | | |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& 3 | | |
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "MOTIVATION"
.IX Header "MOTIVATION"
I do a lot of Perl/CGI for reporting purposes. In nearly every place I've been, I've been asked for \s-1HTML, PDF,\s0 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 \s-1XLS\s0 file.
.SH "USAGE"
.IX Header "USAGE"
.SS "\fInew()\fP"
.IX Subsection "new()"
This creates a Excel::Template object.
.PP
\fIParameters\fR
.IX Subsection "Parameters"
.IP "\(bu" 4
\&\s-1FILE / FILENAME\s0
.Sp
Excel::Template will parse the template in the given file or filehandle automatically. (You can also use the \fIparse()\fR method, described below.)
.Sp
If you want to use the _\|_DATA_\|_ section, you can do so by passing
.Sp
.Vb 1
\& FILE => \e*DATA
.Ve
.IP "\(bu" 4
\&\s-1RENDERER\s0
.Sp
The default rendering engine is Spreadsheet::WriteExcel. You may, if you choose, change that to another choice. The legal values are:
.RS 4
.IP "\(bu" 4
Excel::Template\->\s-1RENDER_NML\s0
.Sp
This is the default of Spreadsheet::WriteExcel.
.IP "\(bu" 4
Excel::Template\->\s-1RENDER_BIG\s0
.Sp
This attempts to load Spreadsheet::WriteExcel::Big.
.IP "\(bu" 4
Excel::Template\->\s-1RENDER_XML\s0
.Sp
This attempts to load Spreadsheet::WriteExcelXML.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1USE_UNICODE\s0
.Sp
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.
.Sp
The \s-1USE_UNICODE\s0 parameter will be ignored if you are using Perl 5.8 or higher as Perl's internal string handling is unicode-aware.
.Sp
\&\s-1NOTE:\s0 Certain older versions of OLE::Storage_Lite and mod_perl clash for some reason. Upgrading to the latest version of OLE::Storage_Lite should fix the problem.
.PP
\fIDeprecated\fR
.IX Subsection "Deprecated"
.IP "\(bu" 4
\&\s-1BIG_FILE\s0
.Sp
Instead, use \s-1RENDERER\s0 => Excel::Template\->\s-1RENDER_BIG\s0
.SS "\fIparam()\fP"
.IX Subsection "param()"
This method is exactly like HTML::Template's \fIparam()\fR method.
.SS "\fIparse()\fP / \fIparse_xml()\fP"
.IX Subsection "parse() / parse_xml()"
This method actually parses the template file. It can either be called separately or through the \fInew()\fR call. It will \fIdie()\fR if it runs into a situation it cannot handle.
.PP
If a filename is passed in (vs. a filehandle), the directory name will be passed in to XML::Parser as the \fIBase\fR parameter. This will allow for \s-1XML\s0 directives to work as expected.
.SS "\fIwrite_file()\fP"
.IX Subsection "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.)
.SS "\fIoutput()\fP"
.IX Subsection "output()"
It will act just like HTML::Template's \fIoutput()\fR 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.)
.SS "\fIregister()\fP"
.IX Subsection "register()"
This allows you to register a class as handling a node. q.v. Excel::Template::Factory for more info.
.SH "SUPPORTED NODES"
.IX Header "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.
.PP
Every node can set the \s-1ROW\s0 and \s-1COL\s0 parameters. These are the actual \s-1ROW/COL\s0 values that the next CELL-type tag will write into.
.IP "\(bu" 4
\&\s-1WORKBOOK\s0
.Sp
This is the node representing the workbook. It is the parent for all other nodes.
.IP "\(bu" 4
\&\s-1WORKSHEET\s0
.Sp
This is the node representing a given worksheet.
.IP "\(bu" 4
\&\s-1IF\s0
.Sp
This node represents a conditional expression. Its children may or may not be rendered. It behaves just like HTML::Template's \s-1TMPL_IF.\s0
.IP "\(bu" 4
\&\s-1LOOP\s0
.Sp
This node represents a loop. It behaves just like HTML::Template's \s-1TMPL_LOOP.\s0
.IP "\(bu" 4
\&\s-1ROW\s0
.Sp
This node represents a row of data. This is the 1 in A1. There is no \s-1COLUMN\s0 node, as of yet.
.IP "\(bu" 4
\&\s-1FORMAT\s0
.Sp
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 \s-1BOLD\s0 and \s-1ITALIC\s0.
.IP "\(bu" 4
\&\s-1BACKREF\s0
.Sp
This refers back to a cell previously named.
.IP "\(bu" 4
\&\s-1CELL\s0
.Sp
This is the actual cell in a spreadsheet.
.IP "\(bu" 4
\&\s-1FORMULA\s0
.Sp
This is a formula in a spreadsheet.
.IP "\(bu" 4
\&\s-1RANGE\s0
.Sp
This is a \s-1BACKREF\s0 for a number of identically-named cells.
.IP "\(bu" 4
\&\s-1VAR\s0
.Sp
This is a variable. It is generally used when the 'text' attribute isn't
sufficient.
.SH "BUGS"
.IX Header "BUGS"
None, that I know of.
.SH "SUPPORT"
.IX Header "SUPPORT"
This is production quality software, used in several production web applications.
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.Vb 3
\& Jens Gassmann
\& Robert Bohne
\& Rob Kinyon
.Ve
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
There is a mailing list at http://groups.google.com/group/ExcelTemplate or exceltemplate@googlegroups.com
.SS "Robert Bohne "
.IX Subsection "Robert Bohne "
.IP "\(bu" 4
Swichting to Module::Install
.IP "\(bu" 4
Add autofilter to worksheet
.SS "Robert Graff"
.IX Subsection "Robert Graff"
.IP "\(bu" 4
Finishing formats
.IP "\(bu" 4
Fixing several bugs in worksheet naming
.SS "Jens Gassmann"
.IX Subsection "Jens Gassmann"
.IP "\(bu" 4
Add hide_gridlines to worksheet
.SH "TEST COVERAGE"
.IX Header "TEST COVERAGE"
I use Devel::Cover to test the coverage of my tests. Every release, I intend to improve these numbers.
.PP
Excel::Template is also part of the \s-1CPAN\s0 Kwalitee initiative, being one of the top 100 non-core modules downloaded from \s-1CPAN.\s0 If you wish to help out, please feel free to contribute tests, patches, and/or suggestions.
.PP
.Vb 10
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-
\& File stmt bran cond sub pod time total
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-
\& blib/lib/Excel/Template.pm 93.8 60.0 58.8 100.0 100.0 31.8 83.3
\& ...ib/Excel/Template/Base.pm 94.4 50.0 n/a 100.0 0.0 4.4 80.0
\& ...cel/Template/Container.pm 100.0 50.0 33.3 100.0 0.0 2.0 83.3
\& ...emplate/Container/Bold.pm 100.0 n/a n/a 100.0 0.0 0.1 95.0
\& .../Container/Conditional.pm 95.9 90.0 66.7 100.0 0.0 0.3 91.0
\& ...plate/Container/Format.pm 100.0 n/a n/a 100.0 0.0 1.5 96.8
\& ...plate/Container/Hidden.pm 100.0 n/a n/a 100.0 0.0 0.0 95.0
\& ...plate/Container/Italic.pm 100.0 n/a n/a 100.0 0.0 0.0 95.0
\& ...ainer/KeepLeadingZeros.pm 100.0 100.0 n/a 100.0 0.0 0.0 96.3
\& ...plate/Container/Locked.pm 100.0 n/a n/a 100.0 0.0 0.0 95.0
\& ...emplate/Container/Loop.pm 96.8 50.0 50.0 100.0 0.0 0.1 82.7
\& ...late/Container/Outline.pm 100.0 n/a n/a 100.0 0.0 0.0 95.0
\& ...Template/Container/Row.pm 100.0 75.0 n/a 100.0 0.0 0.1 90.6
\& ...mplate/Container/Scope.pm 100.0 n/a n/a 100.0 n/a 0.0 100.0
\& ...plate/Container/Shadow.pm 100.0 n/a n/a 100.0 0.0 0.0 95.0
\& ...te/Container/Strikeout.pm 100.0 n/a n/a 100.0 0.0 0.0 95.0
\& ...ate/Container/Workbook.pm 100.0 n/a n/a 100.0 n/a 7.0 100.0
\& ...te/Container/Worksheet.pm 95.5 87.5 100.0 100.0 0.0 1.1 90.2
\& ...Excel/Template/Context.pm 98.0 80.0 75.0 100.0 73.3 17.0 90.7
\& ...Excel/Template/Element.pm 100.0 n/a n/a 100.0 n/a 0.1 100.0
\& ...mplate/Element/Backref.pm 100.0 50.0 33.3 100.0 0.0 0.1 87.1
\& .../Template/Element/Cell.pm 97.9 75.0 80.0 100.0 0.0 5.6 88.6
\& ...mplate/Element/Formula.pm 100.0 n/a n/a 100.0 0.0 0.0 94.1
\& ...te/Element/FreezePanes.pm 100.0 n/a n/a 100.0 0.0 0.0 95.5
\& ...Template/Element/Image.pm 100.0 100.0 n/a 100.0 0.0 0.0 94.3
\& ...Template/Element/Range.pm 100.0 66.7 n/a 100.0 0.0 0.1 88.9
\& ...l/Template/Element/Var.pm 100.0 n/a n/a 100.0 0.0 0.0 94.1
\& ...Excel/Template/Factory.pm 100.0 73.1 66.7 100.0 100.0 22.3 91.4
\& .../Excel/Template/Format.pm 98.4 75.0 33.3 100.0 66.7 2.6 90.5
\& ...xcel/Template/Iterator.pm 98.6 80.0 70.6 100.0 50.0 0.3 88.8
\& ...el/Template/TextObject.pm 92.9 62.5 33.3 100.0 0.0 3.3 80.9
\& Total 97.8 74.7 64.6 100.0 35.7 100.0 89.4
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), HTML::Template, Spreadsheet::WriteExcel