1Excel::Template(3)    User Contributed Perl Documentation   Excel::Template(3)
2
3
4

NAME

6       Excel::Template - Excel::Template
7

SYNOPSIS

9       First, make a template. This is an XML file, describing the layout of
10       the spreadsheet.
11
12       For example, test.xml:
13
14         <workbook>
15             <worksheet name="tester">
16                 <cell text="$HOME" />
17                 <cell text="$PATH" />
18             </worksheet>
19         </workbook>
20
21       Now, create a small program to use it:
22
23         #!/usr/bin/perl -w
24
25         use strict;
26
27         use Excel::Template;
28
29         # Create the Excel template
30         my $template = Excel::Template->new(
31             filename => 'test.xml',
32         );
33
34         # Add a few parameters
35         $template->param(
36             HOME => $ENV{HOME},
37             PATH => $ENV{PATH},
38         );
39
40         $template->write_file('test.xls');
41
42       If everything worked, then you should have a spreadsheet called
43       text.xls in your working directory that looks something like:
44
45                    A                B                C
46           +----------------+----------------+----------------
47         1 | /home/me       | /bin:/usr/bin  |
48           +----------------+----------------+----------------
49         2 |                |                |
50           +----------------+----------------+----------------
51         3 |                |                |
52

DESCRIPTION

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

MOTIVATION

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

USAGE

69   new()
70       This creates a Excel::Template object.
71
72       Parameters
73
74       •   FILE / FILENAME
75
76           Excel::Template will parse the template in the given file or
77           filehandle automatically. (You can also use the parse() method,
78           described below.)
79
80           If you want to use the __DATA__ section, you can do so by passing
81
82             FILE => \*DATA
83
84       •   RENDERER
85
86           The default rendering engine is Spreadsheet::WriteExcel. You may,
87           if you choose, change that to another choice. The legal values are:
88
89           •   Excel::Template->RENDER_NML
90
91               This is the default of Spreadsheet::WriteExcel.
92
93           •   Excel::Template->RENDER_BIG
94
95               This attempts to load Spreadsheet::WriteExcel::Big.
96
97           •   Excel::Template->RENDER_XML
98
99               This attempts to load Spreadsheet::WriteExcelXML.
100
101       •   USE_UNICODE
102
103           This will use Unicode::String to represent strings instead of
104           Perl's internal string handling. You must already have
105           Unicode::String installed on your system.
106
107           The USE_UNICODE parameter will be ignored if you are using Perl 5.8
108           or higher as Perl's internal string handling is unicode-aware.
109
110           NOTE: Certain older versions of OLE::Storage_Lite and mod_perl
111           clash for some reason. Upgrading to the latest version of
112           OLE::Storage_Lite should fix the problem.
113
114       Deprecated
115
116       •   BIG_FILE
117
118           Instead, use RENDERER => Excel::Template->RENDER_BIG
119
120   param()
121       This method is exactly like HTML::Template's param() method.
122
123   parse() / parse_xml()
124       This method actually parses the template file. It can either be called
125       separately or through the new() call. It will die() if it runs into a
126       situation it cannot handle.
127
128       If a filename is passed in (vs. a filehandle), the directory name will
129       be passed in to XML::Parser as the Base parameter. This will allow for
130       XML directives to work as expected.
131
132   write_file()
133       Create the Excel file and write it to the specified filename, if
134       possible. (This is when the actual merging of the template and the
135       parameters occurs.)
136
137   output()
138       It will act just like HTML::Template's output() method, returning the
139       resultant file as a stream, usually for output to the web. (This is
140       when the actual merging of the template and the parameters occurs.)
141
142   register()
143       This allows you to register a class as handling a node. q.v.
144       Excel::Template::Factory for more info.
145

SUPPORTED NODES

147       This is a partial list of nodes. See the other classes in this distro
148       for more details on specific parameters and the like.
149
150       Every node can set the ROW and COL parameters. These are the actual
151       ROW/COL values that the next CELL-type tag will write into.
152
153       •   WORKBOOK
154
155           This is the node representing the workbook. It is the parent for
156           all other nodes.
157
158       •   WORKSHEET
159
160           This is the node representing a given worksheet.
161
162       •   IF
163
164           This node represents a conditional expression. Its children may or
165           may not be rendered. It behaves just like HTML::Template's TMPL_IF.
166
167       •   LOOP
168
169           This node represents a loop. It behaves just like HTML::Template's
170           TMPL_LOOP.
171
172       •   ROW
173
174           This node represents a row of data. This is the 1 in A1. There is
175           no COLUMN node, as of yet.
176
177       •   FORMAT
178
179           This node varies the format for its children. All formatting
180           options supported in Spreadsheet::WriteExcel are supported here.
181           There are also a number of formatting shortcuts, such as BOLD and
182           ITALIC.
183
184       •   BACKREF
185
186           This refers back to a cell previously named.
187
188       •   CELL
189
190           This is the actual cell in a spreadsheet.
191
192       •   FORMULA
193
194           This is a formula in a spreadsheet.
195
196       •   RANGE
197
198           This is a BACKREF for a number of identically-named cells.
199
200       •   VAR
201
202           This is a variable. It is generally used when the 'text' attribute
203           isn't sufficient.
204

BUGS

206       None, that I know of.
207

SUPPORT

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

MAINTAINERS

213           Jens Gassmann <jegade@cpan.org>
214           Robert Bohne <rbo@cpan.org>
215           Rob Kinyon <rkinyon@cpan.org>
216

CONTRIBUTORS

218       There is a mailing list at http://groups.google.com/group/ExcelTemplate
219       or exceltemplate@googlegroups.com
220
221   Robert Bohne <rbo@cpan.org>
222       •   Swichting to Module::Install
223
224       •   Add autofilter to worksheet
225
226   Robert Graff
227       •   Finishing formats
228
229       •   Fixing several bugs in worksheet naming
230
231   Jens Gassmann
232       •   Add hide_gridlines to worksheet
233

TEST COVERAGE

235       I use Devel::Cover to test the coverage of my tests. Every release, I
236       intend to improve these numbers.
237
238       Excel::Template is also part of the CPAN Kwalitee initiative, being one
239       of the top 100 non-core modules downloaded from CPAN. If you wish to
240       help out, please feel free to contribute tests, patches, and/or
241       suggestions.
242
243         ---------------------------- ------ ------ ------ ------ ------ ------ ------
244         File                           stmt   bran   cond    sub    pod   time  total
245         ---------------------------- ------ ------ ------ ------ ------ ------ ------
246         blib/lib/Excel/Template.pm     93.8   60.0   58.8  100.0  100.0   31.8   83.3
247         ...ib/Excel/Template/Base.pm   94.4   50.0    n/a  100.0    0.0    4.4   80.0
248         ...cel/Template/Container.pm  100.0   50.0   33.3  100.0    0.0    2.0   83.3
249         ...emplate/Container/Bold.pm  100.0    n/a    n/a  100.0    0.0    0.1   95.0
250         .../Container/Conditional.pm   95.9   90.0   66.7  100.0    0.0    0.3   91.0
251         ...plate/Container/Format.pm  100.0    n/a    n/a  100.0    0.0    1.5   96.8
252         ...plate/Container/Hidden.pm  100.0    n/a    n/a  100.0    0.0    0.0   95.0
253         ...plate/Container/Italic.pm  100.0    n/a    n/a  100.0    0.0    0.0   95.0
254         ...ainer/KeepLeadingZeros.pm  100.0  100.0    n/a  100.0    0.0    0.0   96.3
255         ...plate/Container/Locked.pm  100.0    n/a    n/a  100.0    0.0    0.0   95.0
256         ...emplate/Container/Loop.pm   96.8   50.0   50.0  100.0    0.0    0.1   82.7
257         ...late/Container/Outline.pm  100.0    n/a    n/a  100.0    0.0    0.0   95.0
258         ...Template/Container/Row.pm  100.0   75.0    n/a  100.0    0.0    0.1   90.6
259         ...mplate/Container/Scope.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
260         ...plate/Container/Shadow.pm  100.0    n/a    n/a  100.0    0.0    0.0   95.0
261         ...te/Container/Strikeout.pm  100.0    n/a    n/a  100.0    0.0    0.0   95.0
262         ...ate/Container/Workbook.pm  100.0    n/a    n/a  100.0    n/a    7.0  100.0
263         ...te/Container/Worksheet.pm   95.5   87.5  100.0  100.0    0.0    1.1   90.2
264         ...Excel/Template/Context.pm   98.0   80.0   75.0  100.0   73.3   17.0   90.7
265         ...Excel/Template/Element.pm  100.0    n/a    n/a  100.0    n/a    0.1  100.0
266         ...mplate/Element/Backref.pm  100.0   50.0   33.3  100.0    0.0    0.1   87.1
267         .../Template/Element/Cell.pm   97.9   75.0   80.0  100.0    0.0    5.6   88.6
268         ...mplate/Element/Formula.pm  100.0    n/a    n/a  100.0    0.0    0.0   94.1
269         ...te/Element/FreezePanes.pm  100.0    n/a    n/a  100.0    0.0    0.0   95.5
270         ...Template/Element/Image.pm  100.0  100.0    n/a  100.0    0.0    0.0   94.3
271         ...Template/Element/Range.pm  100.0   66.7    n/a  100.0    0.0    0.1   88.9
272         ...l/Template/Element/Var.pm  100.0    n/a    n/a  100.0    0.0    0.0   94.1
273         ...Excel/Template/Factory.pm  100.0   73.1   66.7  100.0  100.0   22.3   91.4
274         .../Excel/Template/Format.pm   98.4   75.0   33.3  100.0   66.7    2.6   90.5
275         ...xcel/Template/Iterator.pm   98.6   80.0   70.6  100.0   50.0    0.3   88.8
276         ...el/Template/TextObject.pm   92.9   62.5   33.3  100.0    0.0    3.3   80.9
277         Total                          97.8   74.7   64.6  100.0   35.7  100.0   89.4
278         ---------------------------- ------ ------ ------ ------ ------ ------ ------
279
281       This program is free software; you can redistribute it and/or modify it
282       under the same terms as Perl itself.
283
284       The full text of the license can be found in the LICENSE file included
285       with this module.
286

SEE ALSO

288       perl(1), HTML::Template, Spreadsheet::WriteExcel
289
290
291
292perl v5.36.0                      2023-01-20                Excel::Template(3)
Impressum