File Coverage

blib/lib/HTML/WWWTheme.pm
Criterion Covered Total %
statement 83 182 45.6
branch 19 128 14.8
condition 1 11 9.0
subroutine 15 38 39.4
pod 31 35 88.5
total 149 394 37.8


line stmt bran cond sub pod time code
1             # WWWTheme.pm - perl source for HTML::WWWTheme
2             #
3             # Copyright (C) 2000 Chad Hogan
4             # Copyright (C) 2000 Joint Astronomy Centre
5             #
6             # All rights reserved.
7             #
8             # This file is part of HTML::WWWTheme
9             #
10             #
11             # HTML::WWWTheme is free software; you can redistribute it and/or modify
12             # it under the terms of the GNU General Public License as published by the
13             # Free Software Foundation; either version 2, or (at your option) any
14             # later version.
15             #
16             # HTML::WWWTheme is distributed in the hope that it will be useful, but
17             # WITHOUT ANY WARRANTY; without even the implied warranty of
18             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19             # General Public License for more details.
20             #
21             # You should have received a copy of the GNU General Public License along
22             # with HTML::WWWTheme; see the file gpl.txt. If not, write to the Free
23             # Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
24              
25             package HTML::WWWTheme;
26              
27 4     4   6168 use strict;
  4         11  
  4         185  
28 4     4   22 use Carp;
  4         7  
  4         1286  
29              
30 4     4   57 use vars qw($VERSION);
  4         10  
  4         25760  
31              
32             $VERSION = '1.06';
33              
34             # You're going to notice that $self->{"link"} is in quotation marks.
35             # that's because I get an ambiguity error if I use it. So, I made
36             # some changes that will remove the error. No big deal.
37              
38             sub new {
39 4     4 0 1455 my $that = shift;
40 4   33     40 my $type = ref($that) || $that;
41 4         109 my $self = {
42             nextlink => "",
43             lastlink => "",
44             uplink => "",
45              
46             topbottomlinks => [],
47              
48             bgcolor => "#FFFFFF",
49             bgpicture => "",
50             alink => "",
51             "link" => "",
52             text => "",
53             vlink => "",
54              
55             sidebarcolor => "#FFFFFF",
56             blankgif => "/WWW/images/blank.gif",
57             infolinks => [],
58             sidebartop => "Nowhere",
59             sidebarmenutitle => "My Divisions",
60             sidebarsearchbox => "0",
61             sidebarmenulinks => [],
62             sidebarwidth => "150",
63             shortwidth => "120",
64             nosidebarextras => "",
65             morelinkstitle => "More links",
66             usenavbar => "",
67             configfile => "",
68             startstring => "Nothing",
69             endstring => "",
70             searchtemplate => "",
71             printablename => "",
72              
73             };
74 4         10 my $config;
75            
76 4 50       24 if (@_)
77             {
78 0 0       0 GetConfiguration($self, @_) || carp "configuration failed! probably bad files." && return 0;
79             }
80            
81 4         13 bless $self, $type;
82 4         13 return $self;
83             }
84              
85             ##############################################################################
86             #
87             # This subroutine will make the header that will wrap around the top of the page.
88             # Valid HTML should go between this and the end of the page, but *without* a
89             # tag, because we've already got one.
90             #
91             ##############################################################################
92              
93             sub MakeHeader
94             {
95              
96 1     1 1 27 my $self = shift;
97              
98 1         4 my $bodystring = "
99 1 50       9 $self->{bgcolor} && ( $bodystring .= "BGCOLOR=\"$self->{bgcolor}\" " );
100 1 50       4 $self->{bgpicture} && ( $bodystring .= "BACKGROUND=\"$self->{bgpicture}\" " );
101 1 50       7 $self->{alink} && ( $bodystring .= "ALINK=\"$self->{alink}\" " );
102 1 50       6 $self->{"link"} && ( $bodystring .= "LINK=\"" . $self->{"link"} . "\" ");
103 1 50       6 $self->{text} && ( $bodystring .= "TEXT=\"$self->{text}\" ");
104 1 50       5 $self->{vlink} && ( $bodystring .= "VLINK=\"$self->{vlink}\" ");
105 1         2 $bodystring .= ">";
106              
107             # now we'll create the meat of the header piece.
108             # you'll notice the appropriate additions here and there,
109             # including the $bodystring that we just made.
110              
111 1         16 my $navbar =
112             q{
113            
122              
123             } . $bodystring . q{
124            
125            
126            
127            
128            
129            
130            
131            
132            
133            
134            
135            
136            
137            
138             } . $self->{sidebartop} . q{
139            
140            
141            
142            
143            
144             }. $self->{sidebarmenutitle} .q{
145            
146            
147            
148            
149            
150            
151             152             q{" HEIGHT="1" VSPACE="3">
} . MakeSideBarMenuLinks($self) . q{
153            
154            
155            
156            
};
157            
158             # now, unless we've set the "nosidebarextras" bit, we'll add in the other pieces of the sidebar.
159             # including "more links" and the search bar.
160            
161 1 50       6 unless ($self->{nosidebarextras})
162             {
163 1         17 $navbar .= q{
164            
165             } . $self->{morelinkstitle} . q{
166            
167            
168            
169            
170            
171            
172             } .
173             join ("{blankgif} . "\" ALT=\"\" WIDTH=\"" .
174 1         21 $self->{shortwidth} . "\" HEIGHT=\"1\" VSPACE=\"3\">
" , @{$self->{infolinks}})
175             . q{
176            
177            
178            
179            
180            
181              
182            
183            
} .
184             MakeSearchBox($self);
185             } # end of the conditional addition of the sidebar extras! yeah, I know, it's a mess.
186              
187             # Now we have to close everything off nicely. This part must be added in every case.
188              
189 1         6 $navbar .= q{
190            
191            
192            
193            
194            
195            
196            
197            
198            
199            
200            
201            
202            
203              
204             }; # end of the $navbar string
207              
208 1         5 return $navbar;
209              
210              
211             }
212              
213              
214             ##############################################################################
215             #
216             # this subroutine creates the searching box at the side. It's called from
217             # MakeHeader. If you want to use Isearch, you must download it from
218             # http://www.cnidr.org/ir/isearch.html (though there are zillions of
219             # good search engines out there)
220              
221              
222             sub MakeSearchBox
223             {
224 1     1 0 3 my $self = shift;
225 1 50       14 return "" unless $self->{sidebarsearchbox};
226 0         0 return $self->{searchtemplate};
227             }
228              
229             #############################################################################
230             #
231             # here we make all the sidebar menu links. We call this routine from the
232             # MakeHeader subroutine.
233             #
234              
235             sub MakeSideBarMenuLinks
236             {
237 1     1 0 3 my $self = shift;
238 1 50       1 return '' unless (@{$self->{sidebarmenulinks}});
  1         5  
239 1         1 my $menu = shift @{$self->{sidebarmenulinks}};
  1         3  
240 1         2 foreach my $link (@{$self->{sidebarmenulinks}})
  1         4  
241             {
242 1         5 $menu .= "
{blankgif}."\" ALT=\"\" WIDTH=\"1\" HEIGHT=\"1\" VSPACE=\"2\">
";
243 1         3 $menu .= $link;
244             }
245            
246 1         4 $menu .= "
{blankgif}."\" ALT=\"\" WIDTH=\"1\" HEIGHT=\"1\" VSPACE=\"2\">
";
247 1         3 return $menu;
248             }
249              
250             #############################################################################
251             #
252             # This creates the top and bottom nav bars, if they're used.
253             # Again, this is called from the MakeHeader
254              
255             sub MakeNavBar
256             {
257 1     1 1 6 my $self = shift;
258 1         3 my $navthingy = "
\n";
259 1 50       10 $navthingy .= "Previous:$self->{lastlink}\n" if ($self->{lastlink});
260 1 50       6 $navthingy .= "Up:$self->{uplink}\n" if ($self->{uplink});
261 1 50       8 $navthingy .= "Next:$self->{nextlink}\n" if ($self->{nextlink});
262 1         3 $navthingy .= "
";
263 1         4 return $navthingy;
264             }
265              
266             ##############################################################################
267             #
268             # This creates the navigation bar to be found at the top and bottom of the
269             # page. It's usually called directly (eg. Apache::SetWWWTheme calls it directly)
270              
271             sub MakeTopBottomBar
272             {
273 1     1 0 6 my $self = shift;
274 1 50       2 return '' unless (@{$self->{topbottomlinks}});
  1         6  
275 1         2 my $bar = "\n
";
276 1         2 foreach my $link (@{$self->{topbottomlinks}})
  1         4  
277             {
278 2         6 $bar .= "$link
";
279             }
280 1         3 $bar .= "\n";
281 1         3 return $bar;
282             }
283              
284             ##############################################################################
285             #
286             # This footer must always be used, since it closes off all the table stuff
287             # that we created in the MakeHeader. It really doesn't do much else, except
288             # it throws in the "return to top...." bit.
289             #
290              
291             sub MakeFooter
292             {
293 1     1 1 6 my $self = shift;
294 1         2 my $endbody;
295 1         2 $endbody = "
";
296 1         5 $endbody .= '
return to top...
';
299 1         2 $endbody .= "";
300            
301 1         5 return $endbody;
302             }
303            
304              
305              
306             ##############################################################################
307             #
308             # This allows us to read everything from a file, if so desired. This way
309             # you can drop configs into a file, and then just edit the file instead of
310             # changing source code for any cgis that call this module.
311             #
312              
313             sub GetConfiguration
314             {
315 0     0 1 0 my $self = shift;
316 0         0 while (@_)
317             {
318 0         0 $self->{configfile} = shift;
319              
320 0 0 0     0 open (CONFIG, $self->{configfile}) || carp "couldn't open server config $self->{configfile}" && return 0;
321 0         0 local $/ = "";
322            
323 0         0 while ()
324             {
325 0 0       0 ( /\@BLANKGIF\s*=\s*(.*?);/s ) && ($self->{blankgif} = $1);
326 0 0       0 ( /\@NAVBAR\s*=\s*(.*?);/s ) && ($self->{usenavbar} = $1);
327 0 0       0 ( /\@NEXTLINK\s*?=\s*?(.*?);/s ) && ($self->{nextlink} = $1);
328 0 0       0 ( /\@LASTLINK\s*?=\s*?(.*?);/s ) && ($self->{lastlink} = $1);
329 0 0       0 ( /\@UPLINK\s*?=\s*?(.*?);/s ) && ($self->{uplink} = $1);
330            
331 0 0       0 ( /\@BGCOLOR\s*=\s*(.*?);/s ) && ($self->{bgcolor} = $1);
332 0 0       0 ( /\@BGPICTURE\s*=\s*(.*?);/s ) && ($self->{bgpicture} = $1);
333 0 0       0 ( /\@BACKGROUND\s*=\s*(.*?);/s ) && ($self->{bgpicture} = $1);
334 0 0       0 ( /\@ALINK\s*=\s*(.*?);/s ) && ($self->{alink} = $1);
335 0 0       0 ( /\@LINK\s*=\s*(.*?);/s ) && ($self->{"link"} = $1);
336 0 0       0 ( /\@TEXT\s*=\s*(.*?);/s ) && ($self->{text} = $1);
337 0 0       0 ( /\@VLINK\s*=\s*(.*?);/s ) && ($self->{vlink} = $1);
338            
339 0 0       0 ( /\@SIDEBARTOP\s*?=\s*?(.*?);/s ) && ($self->{sidebartop} = $1);
340 0 0       0 ( /\@SIDEBARMENUTITLE\s*?=\s*?(.*?);/s ) && ($self->{sidebarmenutitle} = $1);
341 0 0       0 ( /\@MORELINKSTITLE\s*?=\s*?(.*?);/s ) && ($self->{morelinkstitle} = $1);
342 0 0       0 ( /\@SEARCHTEMPLATE\s*?=\s*?(.*?);/s ) && ($self->{searchtemplate} = $1);
343 0 0       0 ( /\@SIDEBARSEARCHBOX\s*?=\s*?(.*?);/s ) && ($self->{sidebarsearchbox} = $1);
344 0 0       0 ( /\@SIDEBARCOLOR\s*?=\s*?(.*?);/s ) && ($self->{sidebarcolor} = $1);
345 0 0       0 ( /\@SIDEBARWIDTH\s*?=\s*?(.*?);/s ) && ($self->{sidebarwidth} = $1);
346              
347 0 0       0 ( /\@NOSIDEBAREXTRAS\s*?=\s*?(.*?);/s) && ($self->{nosidebarextras} = $1);
348              
349 0         0 my (@links, @sides);
350 0 0 0     0 ( /\@INFO\s*?=\s*?(.*?);/s ) && (@links = split(',',$1)) && ($self->{infolinks} = \@links);
351 0 0 0     0 ( /\@SIDEBARMENULINKS\s*?=\s*?(.*?);/s ) && (@sides = split(',',$1)) && ($self->{sidebarmenulinks} = \@sides);
352             }
353             }
354 0         0 close CONFIG;
355 0         0 return 1;
356             } #GetConfiguration
357            
358             ##############################
359             # all of my mutator methods.
360              
361             sub SetSearchTemplate
362             {
363 0     0 1 0 my $self = shift;
364 0 0       0 $self->{searchtemplate} = shift if (@_);
365 0         0 return $self->{blankgif};
366             }
367              
368             sub SetBlankGif
369             {
370 0     0 1 0 my $self = shift;
371 0 0       0 $self->{blankgif} = shift if (@_);
372 0         0 return $self->{blankgif};
373             }
374              
375             sub SetNextLink
376             {
377 1     1 1 7 my $self = shift;
378 1 50       14 $self->{nextlink} = shift if (@_);
379 1         4 return $self->{nextlink};
380             }
381              
382             sub SetLastLink
383             {
384 1     1 1 7 my $self = shift;
385 1 50       5 $self->{lastlink} = shift if (@_);
386 1         34 return $self->{lastlink};
387             }
388              
389             sub SetPrintableName
390             {
391 1     1 1 7 my $self = shift;
392 1 50       9 $self->{printablename} = shift if (@_);
393 1         9 return $self->{printablename};
394             }
395              
396             sub SetUpLink
397             {
398 1     1 1 7 my $self = shift;
399 1 50       6 $self->{uplink} = shift if (@_);
400 1         4 return $self->{uplink};
401             }
402              
403             sub SetBGColor
404             {
405 0     0 1 0 my $self = shift;
406 0 0       0 $self->{bgcolor} = shift if (@_);
407 0         0 return $self->{bgcolor};
408             }
409              
410             sub SetBGPicture
411             {
412 0     0 1 0 my $self = shift;
413 0 0       0 $self->{bgpicture} = shift if (@_);
414 0         0 return $self->{bgpicture}
415             }
416              
417             sub SetALink
418             {
419 0     0 1 0 my $self = shift;
420 0 0       0 $self->{alink} = shift if (@_);
421 0         0 return $self->{alink};
422             }
423              
424             sub SetLink
425             {
426 0     0 1 0 my $self = shift;
427 0 0       0 $self->{link} = shift if (@_);
428 0         0 return $self->{link};
429             }
430              
431             sub SetVLink
432             {
433 0     0 1 0 my $self = shift;
434 0 0       0 $self->{vlink} = shift if (@_);
435 0         0 return $self->{vlink};
436             }
437              
438             sub SetMoreLinksTitle
439             {
440 0     0 1 0 my $self = shift;
441 0 0       0 $self->{morelinkstitle} = shift if (@_);
442 0         0 return $self->{morelinkstitle};
443             }
444              
445             sub SetSideBarTop
446             {
447 0     0 1 0 my $self = shift;
448 0 0       0 $self->{sidebartop} = shift if (@_);
449 0         0 return $self->{vlink};
450             }
451              
452             sub SetSideBarMenuTitle
453             {
454 0     0 1 0 my $self = shift;
455 0 0       0 $self->{sidebarmenutitle} = shift if (@_);
456 0         0 return $self->{sidebarmenutitle};
457             }
458              
459             sub SetSideBarSearchBox
460             {
461 0     0 1 0 my $self = shift;
462 0 0       0 $self->{sidebarsearchbox} = shift if (@_);
463 0         0 return $self->{sidebarsearchbox};
464             }
465              
466             sub SetSideBarColor
467             {
468 0     0 1 0 my $self = shift;
469 0 0       0 $self->{sidebarcolor} = shift if (@_);
470 0         0 return $self->{sidebarcolor};
471             }
472              
473             sub SetSideBarWidth
474             {
475 0     0 1 0 my $self = shift;
476 0 0       0 $self->{sidebarwidth} = shift if (@_);
477 0         0 $self->{shortwidth} = $self->{sidebarwidth} - 30;
478 0 0       0 ($self->{shortwidth} < 0) && ($self->{shortwidth} = 0);
479 0         0 return $self->{sidebarwidth};
480             }
481              
482             sub SetNoSideBarExtras
483             {
484 0     0 1 0 my $self = shift;
485 0 0       0 $self->{nosidebarextras} = shift if (@_);
486 0         0 return $self->{nosidebarextras};
487             }
488              
489              
490             sub SetInfoLinks
491             {
492 0     0 1 0 my $self = shift;
493 0 0       0 $self->{infolinks} = shift if (@_);
494 0         0 return $self->{infolinks};
495             }
496              
497             sub SetSideBarMenuLinks
498             {
499 0     0 1 0 my $self = shift;
500 0 0       0 $self->{sidebarmenulinks} = shift if (@_);
501 0         0 return $self->{sidebarmenulinks};
502             }
503              
504             sub SetTopBottomLinks
505             {
506 1     1 1 11 my $self = shift;
507 1 50       12 $self->{topbottomlinks} = shift if (@_);
508 1         3 return $self->{topbottomlinks};
509             }
510              
511             sub SetUseNavBar
512             {
513 0     0 1   my $self = shift;
514 0 0         $self->{usenavbar} = shift if (@_);
515 0           return $self->{usenavbar};
516             }
517              
518             sub SetHTMLStartString
519             {
520 0     0 1   my $self = shift;
521 0 0         $self->{startstring} = shift if (@_);
522 0           return $self->{startstring};
523             }
524              
525             sub SetHTMLEndString
526             {
527 0     0 1   my $self = shift;
528 0 0         $self->{endstring} = shift if (@_);
529 0           return $self->{endstring};
530             }
531              
532             sub SetText
533             {
534 0     0 1   my $self = shift;
535 0 0         $self->{text} = shift if (@_);
536 0           return $self->{text};
537             }
538              
539             sub StartHTML
540             {
541 0     0 1   my $self = shift;
542 0           return $self->{startstring};
543             }
544              
545             sub EndHTML
546             {
547 0     0 1   my $self = shift;
548 0           return $self->{endstring};
549             }
550              
551              
552              
553             1;
554              
555              
556             # bah. A pox on pod.
557              
558             =head1 NAME
559              
560             HTML::WWWTheme - Standard theme generation, including sidebars and navigation bars
561              
562             =head1 SYNOPSIS
563              
564             use HTML::WWWTheme;
565             my $Theme = new HTML::WWWTheme(@args);
566              
567             =head1 REQUIREMENTS
568              
569             Nothing special -- Perl 5 or newer.
570              
571             =head1 DESCRIPTION
572              
573             HTML::WWWTheme is a module that creates a standard sidebar and implements local colour conventions.
574             It is used by the Apache::SetWWWTheme module to enforce this through the server. In fact,
575             the code in this module was originally contained within the SetWWWTheme module, but at the
576             suggestion of Tim Jenness, I separated this module to allow CGI programs to create standard
577             pages that would fit in with the static pages that are automatically rewritten by the Apache
578             module. So, static pages in the web tree are filtered through Apache::SetWWWTheme, and
579             CGI-generated pages are generated with the help of HTML::WWWTheme. In this manner, a consistent
580             look and feel can be maintained in all pages. Any changes in the structure of WWWTheme are
581             automatically reflected in both the CGI-generated and static pages.
582              
583             The new() function will return a reference to a Theme object. It will accept an
584             array of arbitrary length as arguments. Each element of this array must be a fully
585             qualified path to a configuration file.
586              
587             Configuration is accomplished in three ways. First, one may pass arguments to the
588             new() function. These arguments must be fully qualified paths to a configuration file.
589             The syntax of the directives in this file is simple:
590              
591             @DIRECTIVE=value;
592            
593             for example,
594              
595             @BGCOLOR=#FFFFFF;
596              
597             or, in the case of a directive that accepts a list, the values are comma-separated and
598             semi-colon terminated. Escaped semi-colons will be transformed into semi-colons, and
599             will not terminate the directive.
600              
601             @DIRECTIVE=value1, value2, value3;
602              
603             @DIRECTIVE=value1, value2\; still going, value3;
604              
605             In the second example, the value2\; will be replaced with value2; in the parsed text.
606              
607             for example,
608              
609             @INFO=Here, There;
610              
611             Second, the GetConfiguration() function may be passed a list of full-paths to configuration
612             files. The GetConfiguration() function will parse these files and set the appropriate values.
613              
614             Finally, one may use methods to directly change the settings of the page before it is
615             produced. This is the recommended method, because it is the most intuitive and the
616             easiest to figure out when you're trying to figure out someone else's code. I use these
617             methods extensively in my Apache::SetWWWTheme module.
618              
619             =head2 METHODS
620              
621             The following are all the methods that may be used to control the behaviour of the
622             module.
623              
624             =over 4
625              
626             =item GetConfiguration()
627              
628             This method takes the names of configuration files as arguments, and parses them one
629             by one. The configuration files contain a series of directives of the form
630              
631             @DIRECTIVE=value;
632              
633             or, in the case of a list-value (for example, with the infolinks that make up the
634             links on the sidebar under "More Links" or "More Info")
635              
636             @DIRECTIVE=value1, value2, value3;
637              
638             Valid directives are listed, along with the corresponding method that performs
639             the same method:
640              
641             @BLANKGIF (see SetBlankGif() )
642             @NAVBAR (see SetUseNavBar() )
643             @NEXTLINK (see SetNextLink() )
644             @LASTLINK (see SetLastLink() )
645             @UPLINK (see SetUpLink() )
646             @BGCOLOR (see SetBGColor() )
647             @BGPICTURE (see SetBGPicture() )
648             @BACKGROUND (see SetBGPicture() )
649             @ALINK (see SetALink() )
650             @LINK (see SetLink() )
651             @VLINK (see SetVLink() )
652             @SIDEBARTOP (see SetSideBarTop() )
653             @SIDEBARMENUTITLE (see SetSidebarMenuTitle() )
654             @SIDEBARSEARCHBOX (see SetSideBarSearchBox() )
655             @SIDEBARCOLOR (see SetSideBarColor() )
656             @SIDEBARWIDTH (see SetSideBarWidth() )
657             @NOSIDEBAREXTRAS (see SetNoSideBarExtras() )
658             @MORELINKSTITLE (see SetMoreLinksTitle() )
659             @INFO (see SetInfoLinks() )
660             @SIDEBARMENULINKS (see SetSideBarMenuLinks() )
661              
662             =item MakeFooter()
663              
664             Returns a footer to end the document. Should be the last part of a dynamically
665             generated HTML page. See the example.
666              
667             =item MakeHeader()
668              
669             Returns the header to the page. Should be the first part of a dynamically
670             generated HTML page. See the example.
671              
672             =item MakeNavBar()
673              
674             Returns a "previous/up/next" navigation bar. This bar is designed to be
675             sandwiched between the Header and the main body, and then later on between
676             the end of the main body and the Footer. See the example.
677              
678             =item SetNextLink()
679              
680             Sets the "Next" link on the top/bottom nav bars. Valid entries must be in the form
681             of an HTML link,
682              
683             $Theme->SetNextLink('somewhere');
684              
685             =item SetLastLink()
686              
687             Sets the "Last" or "Previous" link on the top/bottom nav bars. Valid entries must be
688             in the form of an HTML link,
689              
690             $Theme->SetLastLink('here');
691              
692             =item SetUpLink()
693              
694             Sets the "Up" link on the top/bottom nav bars. Valid entries must be in the form of an
695             HTML link,
696              
697             $Theme->SetUpLink('there');
698              
699             =item SetBGColor()
700              
701             Sets the background color for the page generated. Valid entries must be in the form of
702             a hex color code,
703              
704             $Theme->SetBGColor("#CCFFFF");
705              
706             =item SetBGPicture()
707              
708             Sets the background image for the page generated. Valid entries must be in the form of
709             an absolute URL or URI.
710              
711             $Theme->SetBGPicture("/WWW/images/wallpaper.gif");
712              
713             =item SetALink(), SetLink(), SetVLink()
714              
715             Sets the [a|v]link color for the EBODYE tag. Valid entries must be in the form of
716             a hex color code.
717              
718             $Theme->SetALink("#FFCCFF");
719             $Theme->SetVLink("#FFCCFF");
720             $Theme->SetLink ("#FFCCFF");
721              
722             =item SetMoreLinksTitle()
723              
724             Sets the "More links" title on the sidebar. By default it says "More
725             links", but you may want to change it something else.
726              
727             $Theme->SetMoreLinksTitle("More useful links");
728              
729             =item SetNoSideBarExtras()
730              
731             If this is true, it turns off the sidebar extras -- those parts of the
732             sidebar that aren't in the "SidebarMenuLinks" bit.
733              
734             $Theme->SetNoSideBarExtras("1");
735              
736             =item SetHTMLStartString()
737              
738             Sets the HTML starting string. This string should include the opening tag,
739             the tags (and anything inbetween). Essentially, it should contain
740             everything before the tag. If you are using this module for a CGI program,
741             you should probably include the usual Content-Type: text/html sort of thing.
742              
743             $Theme->SetHTMLStartString("This is my page.");
744              
745             =item SetHTMLEndString()
746              
747             Sets the HTML ending string. This string should contain everything after the
748             tag, including such things as .
749              
750             $Theme->SetHTMLEndString("");
751              
752             =item SetPrintableName()
753              
754             Sets the URL that is used to produce a printable version of the
755             page. This is used to generate the small "click here to produce a printable
756             version" link on the themed page. How this is implemented is left to the caller.
757             Apache::SetWWWTheme produces an un-themed page, with all the link tags stripped
758             out to discourage people from browsing in the printable pages and thus subverting
759             the theming.
760              
761             $Theme->SetPrintableName("/printable/path/to/file.html");
762              
763             =item SetText()
764              
765             Sets the text color for the EBODYE tag. Valid entries must be in the form of
766             a hex color code.
767              
768             $Theme->SetText("#000000");
769              
770             =item SetSideBarColor()
771              
772             Sets the color of the generated sidebar. Valid entries must be in the form of a hex
773             color code.
774              
775             $Theme->SetSideBarColor("#FFCCFF");
776              
777             =item SetSideBarWidth()
778              
779             Sets the width of the sidebar in pixels. The default is 150.
780              
781             $Theme->SetSideBarWidth("120");
782              
783             =item SetBlankGif()
784              
785             Sets the location of the blank gif. A blank gif (blank.gif) is included in the distribution
786             of this package. Valid entries must be in the form of a URL or URI pointing to this file.
787              
788             $Theme->SetBlankGif("/WWW/images/blank.gif");
789              
790             =item SetInfoLinks()
791              
792             Sets the value of the "info links". Info links are designed to be user-configurable and
793             fall under the "More Links" or "More information" section of the sidebar. Valid entries must
794             be in the form of a reference to an array of valid links.
795              
796             @array = ('here', 'there');
797             $Theme->SetInfoLinks(\@array);
798              
799             =item SetSideBarTop()
800              
801             Sets the name appearing at the top of the sidebar. This may be a link, if desired. Valid
802             entries are strings.
803              
804             $Theme->SetSideBarTop('My Webserver');
805              
806             =item SetSearchTemplate()
807              
808             Sets the template to insert into the HTML for the side searchbox. It should be self-contained
809             HTML with the appropriate form methods etc. to interface with your local search engine. Here
810             is an example of a template:
811              
812             Search JAC
813            
814            
815            
816            
817            
818            
819            
820            
821            
822            
823            
824            
825            
More searching....
826              
827             Your template must be customized as appropriate for your engine, of course. This template
828             should be passed to the SetSearchTemplate function as one big string.
829              
830             =item SetSideBarMenuLinks()
831              
832             Sets the value of the main sidebar links. Valid entries must be in the form of a reference
833             to an array of valid links.
834              
835             @array = ('here', 'there');
836             $Theme->SetSideBarMenuLinks(\@array);
837              
838             =item SetSideBarMenuTitle()
839              
840             Sets the name of the main sidebar links. Valid entries must be in the form of a string,
841              
842             $Theme->SetSideBarMenuTitle("Main Sections");
843              
844             =item SetSideBarSearchBox()
845              
846             Sets the state of the sidebar searchbox. If this value is set to anything true (in the perl sense),
847             the searchbox will appear on the sidebar.
848              
849             $Theme->SetSideBarSearchBox("1");
850              
851             =item SetUseNavBar()
852              
853             Sets the state of the top/bottom navbars. If this value is set to anything true (in the perl sense),
854             the top/bottom navbars will be place on the page. These navbars will be created with
855             the values set in the Set__Link() methods.
856              
857             $Theme->SetUseNavBar("1");
858              
859             =item SetTopBottomLinks()
860              
861             Sets the links used in the top/bottom link bars. It takes an array reference as data.
862              
863             @array = ('here', 'there');
864             $Theme->SetTopBottomLinks(\@array);
865              
866             =item StartHTML()
867              
868             Returns the contents of the string set in SetHTMLStartString. This is mostly just a placeholder
869             for some time in the future when I get around to fully implementing this module to mimic the
870             abilities of some other well-known modules.
871              
872             print $Theme->StartHTML();
873              
874             =item EndHTML()
875              
876             Returns the contents of the string set in SetHTMLEndString. This is mostly just a placeholder
877             for some time in the future when I get around to fully implementing this module to mimic the
878             abilities of some other well-known modules.
879              
880             print $Theme->EndHTML();
881              
882             The MakeNavBar() function may be used to create the top/bottom navigation bar. This bar contains
883             the previous/up/next links. It takes no arguments, but uses the [next|last|up]link keys in the hash.
884              
885             Finally, the MakeFooter() function is used to end the html file. This function is absolutely necessary, as
886             the page won't render without it! The tables will not be finished, and very few browswers can deal with this.
887              
888             Here is a simple but functional example. Notice that there are no EBODYE tags. The header and
889             footer take care of this. Write your HTML as if you were writing between the EBODYE and
890             E/BODYE tags.:
891              
892             #!/usr/bin/perl -w
893              
894             use strict;
895             use HTML::WWWTheme;
896              
897             # read in a few defaults
898             my $Theme = new HTML::WWWTheme("/WWW/LookAndFeel", "/home/chogan/Lookandfeel");
899              
900             # set a few things by hand
901             $Theme->SetBlankGif("/WWW/images/blank.gif");
902             $Theme->SetBGColor("#FFFFFF");
903             $Theme->SetHTMLStartString("My Example.");
904             $Theme->SetHTMLEndString("");
905              
906             # make the header, navbar, body, navbar, footer.
907             print $Theme->StartHTML();
908             print $Theme->MakeHeader();
909             print $Theme->MakeTopBottomBar();
910             print $Theme->MakeNavBar();
911             print "This is the body of my file. Isn't it groovy?";
912             print $Theme->MakeNavBar();
913             print $Theme->MakeTopBottomBar();
914             print $Theme->MakeFooter();
915             print $Theme->EndHTML();
916             exit 0;
917              
918             =head1 SEE ALSO
919              
920             L
921              
922             =head1 AUTHOR
923              
924             Copyright (C) 2000 Chad Hogan (chogan@uvastro.phys.uvic.ca).
925             Copyright (C) 2000 Joint Astronomy Centre
926              
927             All rights reserved. HTML::WWWTheme is free software;
928             you can redistribute it and/or modify it under the terms of the GNU General Public
929             License as published by the Free Software Foundation; either version 2 or
930             (at your option) any later version.
931              
932             HTML::WWWTheme is distributed in the hope that it will be useful, but
933             WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
934             FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
935             details.
936              
937             You should have received a copy of the GNU General Public License along
938             with HTML::WWWTheme; see the file gpl.txt. If not, write to the Free
939             Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
940              
941             =cut