Skip to content

Commit fc9ae04

Browse files
jmcnamarajmcnamara
committed
Add docs for default url format.
1 parent 7ee6f24 commit fc9ae04

File tree

8 files changed

+99
-67
lines changed

8 files changed

+99
-67
lines changed

‎examples/a_simple.pl

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,6 @@
3636

3737

3838
# Write a hyperlink
39-
my $hyperlink_format = $workbook->add_format(
40-
color => 'blue',
41-
underline => 1,
42-
);
43-
44-
$worksheet->write( 10, 0, 'http://www.perl.com/', $hyperlink_format );
39+
$worksheet->write( 10, 0, 'http://www.perl.com/' );
4540

4641
__END__

‎examples/demo.pl

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,6 @@
3737
align => 'vcenter',
3838
);
3939

40-
my $hyperlink_format = $workbook->add_format(
41-
color => 'blue',
42-
underline => 1,
43-
);
44-
45-
4640
my @headings = ( 'Features of Excel::Writer::XLSX', '' );
4741
$worksheet->write_row( 'A1', \@headings, $heading );
4842

@@ -97,7 +91,7 @@
9791
# Hyperlinks
9892
#
9993
$worksheet->write( 'A9', "Hyperlinks" );
100-
$worksheet->write( 'B9', 'http://www.perl.com/', $hyperlink_format );
94+
$worksheet->write( 'B9', 'http://www.perl.com/' );
10195

10296

10397
#######################################################################

‎examples/hyperlink1.pl

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,7 @@
2323
$worksheet->set_column( 'A:A', 30 );
2424
$worksheet->set_selection( 'B1' );
2525

26-
27-
# Add the standard url link format.
28-
my $url_format = $workbook->add_format(
29-
color => 'blue',
30-
underline => 1,
31-
);
32-
33-
# Add a sample format.
26+
# Add a user defined hyperlink format.
3427
my $red_format = $workbook->add_format(
3528
color => 'red',
3629
bold => 1,
@@ -45,12 +38,13 @@
4538
my $tip = 'Get the latest Perl news here.';
4639

4740

48-
# Write some hyperlinks
49-
$worksheet->write( 'A1', 'http://www.perl.com/', $url_format );
50-
$worksheet->write( 'A3', 'http://www.perl.com/', $url_format, $str );
51-
$worksheet->write( 'A5', 'http://www.perl.com/', $url_format, $str, $tip );
41+
# Write some hyperlinks. Unspecified or undefined format paraamters will be
42+
# replace with the defuault Excel hyperlink style.
43+
$worksheet->write( 'A1', 'http://www.perl.com/' );
44+
$worksheet->write( 'A3', 'http://www.perl.com/', undef, $str );
45+
$worksheet->write( 'A5', 'http://www.perl.com/', undef, $str, $tip );
5246
$worksheet->write( 'A7', 'http://www.perl.com/', $red_format );
53-
$worksheet->write( 'A9', 'mailto:jmcnamara@cpan.org', $url_format, 'Mail me' );
47+
$worksheet->write( 'A9', 'mailto:jmcnamara@cpan.org', undef, 'Mail me' );
5448

5549
# Write a URL that isn't a hyperlink
5650
$worksheet->write_string( 'A11', 'http://www.perl.com/' );

‎examples/hyperlink2.pl

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -34,32 +34,23 @@
3434
my $ire_links = $ireland->add_worksheet( 'Links' );
3535
my $ire_sales = $ireland->add_worksheet( 'Sales' );
3636
my $ire_data = $ireland->add_worksheet( 'Product Data' );
37-
my $ire_url_format = $ireland->add_format(
38-
color => 'blue',
39-
underline => 1,
40-
);
37+
my $ire_url_format = $ireland->get_default_url_format();
4138

4239

4340
my $italy = Excel::Writer::XLSX->new( 'C:\Temp\Europe\Italy.xlsx' );
4441

4542
my $ita_links = $italy->add_worksheet( 'Links' );
4643
my $ita_sales = $italy->add_worksheet( 'Sales' );
4744
my $ita_data = $italy->add_worksheet( 'Product Data' );
48-
my $ita_url_format = $italy->add_format(
49-
color => 'blue',
50-
underline => 1,
51-
);
45+
my $ita_url_format = $italy->get_default_url_format();
5246

5347

5448
my $china = Excel::Writer::XLSX->new( 'C:\Temp\Asia\China.xlsx' );
5549

5650
my $cha_links = $china->add_worksheet( 'Links' );
5751
my $cha_sales = $china->add_worksheet( 'Sales' );
5852
my $cha_data = $china->add_worksheet( 'Product Data' );
59-
my $cha_url_format = $china->add_format(
60-
color => 'blue',
61-
underline => 1,
62-
);
53+
my $cha_url_format = $china->get_default_url_format();
6354

6455

6556
# Add an alternative format

‎lib/Excel/Writer/XLSX.pm

Lines changed: 31 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,7 @@ The Excel::Writer::XLSX module provides an object oriented interface to a new Ex
149149
set_1904()
150150
set_optimization()
151151
set_calc_mode()
152+
get_default_url_format()
152153
153154
If you are unfamiliar with object oriented interfaces or the way that they are implemented in Perl have a look at C<perlobj> and C<perltoot> in the main Perl documentation.
154155
@@ -645,6 +646,18 @@ Excel will automatically re-calculate formulas except for tables.
645646
646647
=back
647648
649+
650+
651+
652+
=head2 get_default_url_format()
653+
654+
The C<get_default_url_format()> method gets a copy of the default url format used when a user defined format isn't specified with the worksheet C<write_url()> method. The format is the hyperlink style defined by Excel for the default theme:
655+
656+
my $url_format = $workbook->get_default_url_format();
657+
658+
659+
660+
648661
=head1 WORKSHEET METHODS
649662
650663
A new worksheet is created by calling the C<add_worksheet()> method from a workbook object:
@@ -1209,42 +1222,40 @@ See also the date_time.pl program in the C<examples> directory of the distro.
12091222
12101223
Write a hyperlink to a URL in the cell specified by C<$row> and C<$column>. The hyperlink is comprised of two elements: the visible label and the invisible link. The visible label is the same as the link unless an alternative label is specified. The C<$label> parameter is optional. The label is written using the C<write()> method. Therefore it is possible to write strings, numbers or formulas as labels.
12111224
1212-
The C<$format> parameter is also optional, however, without a format the link won't look like a link.
1213-
1214-
The suggested format is:
1215-
1216-
my $format = $workbook->add_format( color => 'blue', underline => 1 );
1225+
The C<$format> parameter is also optional and the default Excel hyperlink style will be used if it isn't specified. If required you can access the default url format using the Workbook C<get_default_url_format> method:
12171226
1218-
B<Note>, this behaviour is different from Spreadsheet::WriteExcel which provides a default hyperlink format if one isn't specified by the user.
1227+
my $url_format = $workbook->get_default_url_format();
12191228
12201229
There are four web style URI's supported: C<http://>, C<https://>, C<ftp://> and C<mailto:>:
12211230
1222-
$worksheet->write_url( 0, 0, 'ftp://www.perl.org/', $format );
1223-
$worksheet->write_url( 'A3', 'http://www.perl.com/', $format );
1224-
$worksheet->write_url( 'A4', 'mailto:jmcnamara@cpan.org', $format );
1231+
$worksheet->write_url( 0, 0, 'ftp://www.perl.org/' );
1232+
$worksheet->write_url( 'A3', 'http://www.perl.com/' );
1233+
$worksheet->write_url( 'A4', 'mailto:jmcnamara@cpan.org' );
12251234
12261235
You can display an alternative string using the C<$label> parameter:
12271236
1228-
$worksheet->write_url( 1, 0, 'http://www.perl.com/', $format, 'Perl' );
1237+
$worksheet->write_url( 1, 0, 'http://www.perl.com/', undef, 'Perl' );
12291238
12301239
If you wish to have some other cell data such as a number or a formula you can overwrite the cell using another call to C<write_*()>:
12311240
12321241
$worksheet->write_url( 'A1', 'http://www.perl.com/' );
12331242
12341243
# Overwrite the URL string with a formula. The cell is still a link.
1235-
$worksheet->write_formula( 'A1', '=1+1', $format );
1244+
# Note the use of the default url format for consistency with other links.
1245+
my $url_format = $workbook->get_default_url_format();
1246+
$worksheet->write_formula( 'A1', '=1+1', $url_format );
12361247
12371248
There are two local URIs supported: C<internal:> and C<external:>. These are used for hyperlinks to internal worksheet references or external workbook and worksheet references:
12381249
1239-
$worksheet->write_url( 'A6', 'internal:Sheet2!A1', $format );
1240-
$worksheet->write_url( 'A7', 'internal:Sheet2!A1', $format );
1241-
$worksheet->write_url( 'A8', 'internal:Sheet2!A1:B2', $format );
1242-
$worksheet->write_url( 'A9', q{internal:'Sales Data'!A1}, $format );
1243-
$worksheet->write_url( 'A10', 'external:c:\temp\foo.xlsx', $format );
1244-
$worksheet->write_url( 'A11', 'external:c:\foo.xlsx#Sheet2!A1', $format );
1245-
$worksheet->write_url( 'A12', 'external:..\foo.xlsx', $format );
1246-
$worksheet->write_url( 'A13', 'external:..\foo.xlsx#Sheet2!A1', $format );
1247-
$worksheet->write_url( 'A13', 'external:\\\\NET\share\foo.xlsx', $format );
1250+
$worksheet->write_url( 'A6', 'internal:Sheet2!A1' );
1251+
$worksheet->write_url( 'A7', 'internal:Sheet2!A1' );
1252+
$worksheet->write_url( 'A8', 'internal:Sheet2!A1:B2' );
1253+
$worksheet->write_url( 'A9', q{internal:'Sales Data'!A1} );
1254+
$worksheet->write_url( 'A10', 'external:c:\temp\foo.xlsx' );
1255+
$worksheet->write_url( 'A11', 'external:c:\foo.xlsx#Sheet2!A1' );
1256+
$worksheet->write_url( 'A12', 'external:..\foo.xlsx' );
1257+
$worksheet->write_url( 'A13', 'external:..\foo.xlsx#Sheet2!A1' );
1258+
$worksheet->write_url( 'A13', 'external:\\\\NET\share\foo.xlsx' );
12481259
12491260
All of the these URI types are recognised by the C<write()> method, see above.
12501261

‎lib/Excel/Writer/XLSX/Workbook.pm

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1024,6 +1024,22 @@ sub set_calc_mode {
10241024
}
10251025

10261026

1027+
###############################################################################
1028+
#
1029+
# get_default_url_format()
1030+
#
1031+
# Get the default url format used when a user defined format isn't specified
1032+
# with write_url(). The format is the hyperlink style defined by Excel for the
1033+
# default theme.
1034+
#
1035+
sub get_default_url_format {
1036+
1037+
my $self = shift;
1038+
1039+
return $self->{_default_url_format};
1040+
}
1041+
1042+
10271043
###############################################################################
10281044
#
10291045
# _store_workbook()

‎lib/Excel/Writer/XLSX/Worksheet.pm

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2682,7 +2682,7 @@ sub _escape_url {
26822682
26832683
###############################################################################
26842684
#
2685-
# write_url($row, $col, $url, $string, $format)
2685+
# write_url($row, $col, $url, format, $string)
26862686
#
26872687
# Write a hyperlink. This is comprised of two elements: the visible label and
26882688
# the invisible link. The visible label is the same as the link unless an
@@ -2712,18 +2712,19 @@ sub write_url {
27122712
if ( @_ < 3 ) { return -1 } # Check the number of args
27132713
27142714
2715-
# Reverse the order of $string and $format if necessary. We work on a copy
2716-
# in order to protect the callers args. We don't use "local @_" in case of
2717-
# perl50005 threads.
2715+
# Reverse the order of $string and $format if necessary, for backward
2716+
# compatibility. We work on a copy in order to protect the callers
2717+
# args. We don't use "local @_" in case of perl50005 threads.
27182718
my @args = @_;
2719-
( $args[3], $args[4] ) = ( $args[4], $args[3] ) if ref $args[3];
2720-
2719+
if (defined $args[3] and !ref $args[3]) {
2720+
( $args[3], $args[4] ) = ( $args[4], $args[3] );
2721+
}
27212722
27222723
my $row = $args[0]; # Zero indexed row
27232724
my $col = $args[1]; # Zero indexed column
27242725
my $url = $args[2]; # URL string
2725-
my $str = $args[3]; # Alternative label
2726-
my $xf = $args[4]; # Cell format
2726+
my $xf = $args[3]; # Cell format
2727+
my $str = $args[4]; # Alternative label
27272728
my $tip = $args[5]; # Tool tip
27282729
my $type = 'l'; # XML data type
27292730
my $link_type = 1;

‎t/regression/hyperlink28.t

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ use TestFunctions qw(_compare_xlsx_files _is_deep_diff);
1010
use strict;
1111
use warnings;
1212

13-
use Test::More tests => 2;
13+
use Test::More tests => 3;
1414

1515
###############################################################################
1616
#
@@ -85,6 +85,36 @@ $workbook->close();
8585
_is_deep_diff( $got, $expected, $caption );
8686

8787

88+
89+
90+
###############################################################################
91+
#
92+
# Test3. Test with the workbook default format.
93+
#
94+
$workbook = Excel::Writer::XLSX->new( $got_filename );
95+
$worksheet = $workbook->add_worksheet();
96+
$format = $workbook->get_default_url_format();
97+
98+
$worksheet->write_url( 'A1', 'http://www.perl.org/', $format);
99+
100+
$workbook->close();
101+
102+
103+
###############################################################################
104+
#
105+
# Compare the generated and existing Excel files.
106+
#
107+
( $got, $expected, $caption ) = _compare_xlsx_files(
108+
109+
$got_filename,
110+
$exp_filename,
111+
$ignore_members,
112+
$ignore_elements,
113+
);
114+
115+
_is_deep_diff( $got, $expected, $caption );
116+
117+
88118
###############################################################################
89119
#
90120
# Cleanup.

0 commit comments

Comments
 (0)