From 8fd9c002f063117966ceafb6ddefcec171bfd89a Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Thu, 18 Jul 2013 15:17:02 -0400 Subject: documentation --- lib/Spreadsheet/Template.pm | 397 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 397 insertions(+) diff --git a/lib/Spreadsheet/Template.pm b/lib/Spreadsheet/Template.pm index 21e432c..977b85b 100644 --- a/lib/Spreadsheet/Template.pm +++ b/lib/Spreadsheet/Template.pm @@ -5,24 +5,361 @@ use Moose; use Class::Load 'load_class'; use JSON; +=head1 SYNOPSIS + + use Spreadsheet::Template; + + my $template = Spreadsheet::Template->new; + my $in = do { local $/; <> }; + my $out = $template->render($in); + open my $fh, '>', 'out.xlsx'; + binmode $fh; + $fh->print($out); + $fh->close; + +=head1 DESCRIPTION + +This module is used to render spreadsheets from JSON files which describe the +desired content and formatting. These JSON files can be preprocessed with a +template engine such as L in order to customize the spreadsheet +contents before generation, in a similar way to how HTML pages can be rendered +with templates. + +The typical workflow for using this module is to create a sample spreadsheet in +Excel with the desired layout and formatting, and use +L (or the included C +script) to generate a base template. That base template can then be edited +to add in template declarations, and then this module can be used to generate +new spreadsheets based on the template. + +=head1 DATA FORMAT + +The intermediate data format that should be produced after the template has +been preprocessed is a JSON file, with a structure that looks like this: + + { + "selection" : 0, + "worksheets" : [ + { + "column_widths" : [ 10, 10, 10 ], + "name" : "Sheet1", + "row_heights" : [ 18, 18, 18 ], + "selection" : [ 0, 0 ], + "cells" : [ + [ + { + "contents" : "This is cell A1", + "format" : { + "color" : "#000000", + "size" : 14, + "text_wrap" : true, + "valign" : "vcenter" + }, + "type" : "string" + }, + { + "contents" : "3.25", + "format" : { + "color" : "#000000", + "num_format" : "\"$\"#,##0.00_);[Red]\\(\"$\"#,##0.00\\)", + "size" : 14 + }, + "type" : "number" + } + ], + [ + { + "contents" : "2013-03-20T00:00:00", + "format" : { + "color" : "#000000", + "align" : "center", + "num_format" : "d-mmm", + "size" : 14, + "border_color" : [ + "#000000", + "#000000", + "#000000", + "#000000" + ], + "border" : [ + "thin", + "thin", + "thin", + "thin" + ] + }, + "type" : "date_time" + }, + { + "contents" : "3.25", + "formula" : "SUM(B1:B1)", + "format" : { + "bg_color" : "#d8d8d8", + "bold" : true, + "color" : "#000000", + "num_format" : "\"$\"#,##0.00_);[Red]\\(\"$\"#,##0.00\\)", + "pattern" : "solid", + "size" : 14 + }, + "type" : "string" + } + ] + ] + } + ] + } + +=head2 workbook + +The entire JSON document describes a workbook to be produced. The document +should be a JSON object with these keys: + +=over 4 + +=item selection + +The (zero-based) index of the worksheet to be initially selected when the +spreadsheet is opened. + +=item worksheets + +An array of worksheet objects. + +=back + +=head2 worksheet + +Each element of the C array in the workbook object should be a JSON +object with these keys: + +=over 4 + +=item name + +The name of the worksheet. + +=item column_widths + +An array of numbers corresponding to the widths of the columns in the +spreadsheet. + +=item row_heights + +An array of numbers corresponding to the heights of the rows in the +spreadsheet. + +=item selection + +An array of two numbers corresponding to the (zero-based) row and column of the +cell that should be selected when the worksheet is first displayed. + +=item cells + +An array of arrays of cell objects. Each innermost array represents a row, +containing all of the cell data for that row. + +=back + +=head2 cell + +Each element of the two-dimensional C array in a worksheet object should +be a JSON object with these keys: + +=over 4 + +=item contents + +The unformatted contents of the cell. For cells with a C of C, +this should be a string, for cells with a C of C, this should be +a number, and for cells with a C of C, this should be a string +containing the ISO8601 representation of the date and time. + +=item format + +The format object describing how the cell's contents should be formatted. + +=item type + +The type of the data in the cell. Can be either C, C, or +C. + +=item formula + +The formula used to calculate the cell contents. This field is optional. If you +want the generated spreadsheet to be able to be read by programs other than +full spreadsheet applications (such as by L, +then you should ensure that you include an accurate value for C as +well, since most simple spreadsheet parsers don't include a full formula +calculation engine. + +=back + +=head2 format + +Each cell object contains a C key whose value should be a JSON object +with these (all optional) keys: + +=over 4 + +=item size + +The font size for the cell contents. + +=item color + +The font color for the cell contents. + +=item bold + +True if the cell contents are bold. + +=item italic + +True if the cell contents are italic. + +=item pattern + +The background pattern for the cell. Can have any of these values (with +C being the default if nothing is specified): + + none + solid + medium_gray + dark_gray + light_gray + dark_horizontal + dark_vertical + dark_down + dark_up + dark_grid + dark_trellis + light_horizontal + light_vertical + light_down + light_up + light_grid + light_trellis + gray_125 + gray_0625 + +=item bg_color + +The background color for the cell. Only has meaning if a C other than +C is chosen. + +=item fg_color + +The foreground color for the cell. Only has meaning if a C other than +C or C is chosen. + +=item border + +The border style for the cell. This should be an array with four elements, +corresponding to the left, right, top, and bottom borders. Each element can +have any of these values (with C being the default if nothing is +specified): + + none + thin + medium + dashed + dotted + thick + double + hair + medium_dashed + dash_dot + medium_dash_dot + dash_dot_dot + medium_dash_dot_dot + slant_dash_dot + +=item border_color + +The border color for the cell. This should be an array with four elements, +corresponding to the left, right, top, and bottom borders. + +=item align + +The horizontal alignment for the cell contents. Can have any of these values, +with C being the default: + + none + left + center + right + fill + justify + center_across + +=item valign + +The vertical alignment for the cell contents. Can have any of these values, +with C being the default: + + top + vcenter + bottom + vjustify + +=item text_wrap + +True if the contents of the cell should be text-wrapped. + +=item num_format + +The numeric format for the cell. Only meaningful if the cell's type is +C or C. This is the string representation of the format as +understood by Excel itself. + +=back + +=cut + +=attr processor_class + +Name of the L class to use to preprocess the +template. Defaults to L. + +=cut + has processor_class => ( is => 'ro', isa => 'Str', default => 'Spreadsheet::Template::Processor::Xslate', ); +=attr processor_options + +Arguments to pass to the C constructor. + +=cut + has processor_options => ( is => 'ro', isa => 'HashRef', default => sub { {} }, ); +=attr writer_class + +Name of the L class to use to preprocess the +template. Defaults to L. + +=cut + has writer_class => ( is => 'ro', isa => 'Str', default => 'Spreadsheet::Template::Writer::XLSX', ); +=attr writer_options + +Arguments to pass to the C constructor. + +=cut + has writer_options => ( is => 'ro', isa => 'HashRef', @@ -55,6 +392,15 @@ has writer => ( }, ); +=method render($template, $vars) + +Calls C on the L instance with +C<$template> and C<$vars> as arguments, decodes the result as JSON, and returns +the result of passing that data to the C method of the +L instance. + +=cut + sub render { my $self = shift; my ($template, $vars) = @_; @@ -68,4 +414,55 @@ sub render { __PACKAGE__->meta->make_immutable; no Moose; +=head1 BUGS + +No known bugs. + +Please report any bugs to GitHub Issues at +L. + +=head1 SEE ALSO + +L + +=head1 SUPPORT + +You can find this documentation for this module with the perldoc command. + + perldoc Spreadsheet::Template + +You can also look for information at: + +=over 4 + +=item * MetaCPAN + +L + +=item * Github + +L + +=item * RT: CPAN's request tracker + +L + +=item * CPAN Ratings + +L + +=back + +=head1 SPONSORS + +Parts of this code were paid for by + +=over 4 + +=item Socialflow L + +=back + +=cut + 1; -- cgit v1.2.3