Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Spreadsheet::WriteExceUsertContributed Perl Spreadsheet::WriteExcel::Styler(3)

NAME
       Spreadsheet::WriteExcel::Styler - Styles	for formatting generated Excel
       files

SYNOPSIS
	 use Spreadsheet::WriteExcel; #	or use Excel::Writer::XLSX
	 use Spreadsheet::WriteExcel::Styler;

	 # Create an Excel workbook and	worksheet
	 my $workbook =	Spreadsheet::WriteExcel->new('output.xls');
		      #	or Excel::Writer::XLSX->new('output.xls');
	 $worksheet = $workbook->add_worksheet();

	 # Create a styler with	some styles
	 my $styler = Spreadsheet::WriteExcel::Styler->new($workbook);
	 $styler->add_styles(
	   title	=> {align	=> "center",
			    border	=> 1,
			    bold	=> 1,
			    color	=> 'white',
			    bg_color	=> 'blue'},
	   right_border	=> {right	=> 6,	      #	double line
			    right_color	=> 'blue'},
	   highlighted	=> {bg_color	=> 'silver'},
	   rotated	=> {rotation	=> 90},
	 );

	 # Write data into a cell, with	a list of cumulated styles
	 $worksheet->write($row, $col, $data,
			   $styler->(qw/highlighted right_border/));

	 # same	thing, but styles are expressed	as toggles in a	hashref
	 $worksheet->write($row, $col, $data,
			   $styler->({ highlighted  => 1,
				       rotated	    => 0,
				       right_border => should_border($row, $col) }));

DESCRIPTION
       This is a small utility to help formatting cells	while creating Excel
       workbooks through Spreadsheet::WriteExcel or Excel::Writer::XLSX.

       When working interactively within the Excel application,	users often
       change one format feature at a time (highlight a	row, add a border to a
       column, etc.); these changes do not affect other	format features	(for
       example if you change the background color, it does not affect fonts,
       borders,	or cell	alignment).  By	contrast, when generating a workbook
       programmatically	through	Spreadsheet::WriteExcel	or
       Excel::Writer::XLSX, formats express complete sets of features, and
       they cannot be combined together. This means that the programmer	has to
       prepare in advance all formats for all possible combinations of format
       features, and has to invent a way of cataloguing	those combinations.

       Styler objects from the current module come to the rescue: they hold a
       catalogue of styles, where each style is	a collection of	format
       features.  Then,	for any	combination of styles, the styler generates a
       Spreadsheet::WriteExcel::Format or Excel::Writer::XLSX::Format on the
       fly, or,	if a similar combination was already encountered, retrieves
       the format from its internal cache.

METHODS
   "new"
	 my $styler = Spreadsheet::WriteExcel::Styler->new($workbook);

       Creates a styler	object,	associated to a	given workbook.

   "add_styles"
	 $styler->add_styles(
	   $style_name_1 => \%format_properties_1,
	   $style_name_2 => \%format_properties_2,
	   ...
	  );

       Defines a number	of styles within the styler. Each style	has a name and
       a hashref containing format properties (like for
       "Spreadsheet::WriteExcel"'s add_format method).

   "format" or function	dereferencing operator
	 # explicit calls to the 'format()' method
	 my $format = $styler->format($style_name_1, $style_name_2, ...);
	 my $format = $styler->format({$style_name_1 =>	$toggle_1,
				       $style_name_2 =>	$toggle_2,
				       ...});

	 # same	as above, but in shorthand notation
	 my $format = $styler->($style_name_1, $style_name_2, ...);
	 my $format = $styler->({$style_name_1 => $toggle_1,
				 $style_name_2 => $toggle_2,
				 ...});

       The "format" method can be invoked either as a regular method call, or,
       in shorthand notation, as a simple coderef call (arrow operator and
       parentheses). It	returns	a "Format" object, either retrieved from
       cache, or created on the	fly, that can then be passed as	argument to
       any of the worksheet's write methods.

       Arguments to "format()" can be either :

       o   a list of style names

       o   a single arrayref containing	a list of style	names

       o   a single hashref where keys are style names and values are boolean
	   toggles that	specify	whether	that style should be applied or	not

       The array form is useful	when one knows statically the list of styles
       to apply. The hashref form is useful when decisions about styles	depend
       on the context, as for example in :

	 my $format = $styler->({
	   highlighted	=> ($row % 2),
	   right_border	=> $is_end_of_group{$col},
	   emphasized	=> is_very_important($data),
	  });

   "workbook"
       Returns the workbook to which this styler is bound.

   "styles"
       Returns the list	of style names defined in this styler.

   "style"
	 my $props_hashref = $styler->style($style_name);

       Returns the hashref of format properties	that were defined for the
       given $style_name through a previous call to the	"add_styles" method.

AUTHOR
       Laurent Dami, "<laurent.dami AT etat ge ch>"

BUGS
       Please report any bugs or feature requests to
       "bug-spreadsheet-writeexcel-styler at rt.cpan.org", or through the web
       interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Spreadsheet-WriteExcel-Styler>.
       I will be notified, and then you'll automatically be notified of
       progress	on your	bug as I make changes.

SUPPORT
       You can find documentation for this module with the perldoc command.

	   perldoc Spreadsheet::WriteExcel::Styler

       You can also look for information at:

       RT: CPAN's request tracker
	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Spreadsheet-WriteExcel-Styler>

       AnnoCPAN: Annotated CPAN	documentation
	   <http://annocpan.org/dist/Spreadsheet-WriteExcel-Styler>

       CPAN Ratings
	   <http://cpanratings.perl.org/d/Spreadsheet-WriteExcel-Styler>

       METACPAN
	   <https://metacpan.org/dist/Spreadsheet-WriteExcel-Styler/>

ACKNOWLEDGEMENTS
       Thanks to John McNamara and to all other	contributors for the wonderful
       Spreadsheet::WriteExcel and Excel::Writer::XLSX modules.

LICENSE	AND COPYRIGHT
       Copyright 2010, 2012 Laurent Dami.

       This program is free software; you can redistribute it and/or modify it
       under the terms of either: the GNU General Public License as published
       by the Free Software Foundation;	or the Artistic	License.

       See <http://dev.perl.org/licenses/> for more information.

perl v5.32.1			  2021-08-28Spreadsheet::WriteExcel::Styler(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHOR | BUGS | SUPPORT | ACKNOWLEDGEMENTS | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Spreadsheet::WriteExcel::Styler&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help