blib/lib/PerlPoint/Template/Traditional.pm untested

filter: Statementstmt 0.0% 0 / 246 Branchbran 0.0% 0 / 158 Conditioncond 0.0% 0 / 80 MC/DCmcdc 0.0% 0 / 51 Subroutinesub 0.0% 0 / 17 Podpod 0.0% 0 / 8 totaltotal 0.0% 0 / 560 CC 80 SCAR 60.1
CC
80
Cov
0%
transform
702.0
_processTemplate
650.0
bootstrap
240.0
CRAP 407.2
1  
2  
3 # = HISTORY SECTION =====================================================================
4  
5 # ---------------------------------------------------------------------------------------
6 # version | date | author | changes
7 # ---------------------------------------------------------------------------------------
8 # 0.02 |03.12.2005| JSTENZEL | producing better XHTML: empty tags closed (<tag />);
9 # 0.01 |08.07.2004| JSTENZEL | new.
10 # ---------------------------------------------------------------------------------------
11  
12 # = POD SECTION =========================================================================
13  
14 =head1 NAME
15  
16 B<PerlPoint::Template::Traditional> - PerlPoint template processor for traditional pp2html layouts
17  
18 =head1 VERSION
19  
20 This manual describes version B<0.02>.
21  
22 =head1 SYNOPSIS
23  
24  
25  
26 =head1 DESCRIPTION
27  
28  
29 =head1 METHODS
30  
31 =cut
32  
33  
34  
35  
36 # check perl version
37 require 5.00503;
38  
39 # = PACKAGE SECTION (internal helper package) ==========================================
40  
41 # declare package
42 package PerlPoint::Template::Traditional;
43  
44 # declare package version and author
45 $VERSION=0.02;
46 $AUTHOR=$AUTHOR='J. Stenzel (perl@jochen-stenzel.de), 2004-2006';
47  
48  
49 # = PRAGMA SECTION =======================================================================
50  
51 # set pragmata
52 use strict;
53  
54 # declare object data fields
55 use fields qw(
56 );
57  
58 # derive ...
59 use base qw(PerlPoint::Template);
60  
61  
62 # = LIBRARY SECTION ======================================================================
63  
64 # load modules
65 use Carp;
66 use File::Copy;
67 use File::Basename;
68 use POSIX qw(strftime);
69 use PerlPoint::Constants 0.17 qw(:templates);
70  
71  
72 # = CODE SECTION =========================================================================
73  
74  
75 =pod
76  
77 =head2 new()
78  
79  
80 B<Parameters:>
81  
82 =over 4
83  
84 =item class
85  
86 The class name.
87  
88 =back
89  
90 B<Returns:> the new object.
91  
92 B<Example:>
93  
94  
95 =cut
96 sub new
97 {
98 # get parameter
99 my ($class, %params)=@_;
100  
101 # check parameters
102 confess "[BUG] Missing class name.\n" unless $class;
103  
104 # build and supply new object
105 fields::new($class);
106 }
107  
108  
109 # provide option declarations
110 sub declareOptions
111 {
112 # get and check parameters
113 (my __PACKAGE__ $me)=@_;
114 confess "[BUG] Missing object parameter.\n" unless $me;
115 confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
116  
117 (
118 # new options
119 [
120 # template files: document templates (for files produced *once*)
121 "doc_template=s@",
122  
123 # template files: header contents
124 "header_template=s",
125 "header_idx_template=s",
126 "header_toc_template=s",
127  
128 # template files: body top
129 "top_template=s",
130 "top_idx_template=s",
131 "top_toc_template=s",
132  
133 # template files: body bottom
134 "bottom_template=s",
135 "bottom_idx_template=s",
136 "bottom_toc_template=s",
137  
138 # template files: navigation
139 "nav_template=s",
140 "nav_top_template=s",
141 "nav_bottom_template=s",
142  
143 # template files: supplements
144 "supplement_template=s@",
145 "supplement_idx_template=s@",
146 "supplement_toc_template=s@",
147  
148 # template strings
149 "bot_left_txt=s",
150 "bot_middle_txt=s",
151 "bot_right_txt=s",
152 "contents_header=s",
153 "index_header=s",
154 "label_contents=s",
155 "label_index=s",
156 "label_next=s",
157 "label_prev=s",
158 "top_left_txt=s",
159 "top_middle_txt=s",
160 "top_right_txt=s",
161  
162 # logo
163 "logo_image_filename=s",
164  
165 # links
166 "bootstrapaddress=s", # address of the first page of the site (not necessarily generated);
167 "startaddress=s", # base address of the site, like a servers address - used to build absolute links to our pages;
168  
169 # link navigation
170 "linknavigation",
171  
172 # tree applet support (in the tradition of pp2html)
173 "appletdir|applet_dir=s", # target applet directory (allow "applet_dir" for backwards compatibility with pp2html);
174 "appletref|applet_ref=s", # target applet directory reference (allow "applet_ref" for backwards compatibility with pp2html);
175  
176 "tree_app_hint=s", # tree applet hint text, to be displayed if Java is deactivated;
177 "tree_app_height=s", # tree applet area height;
178 "tree_app_width=s", # tree applet area width;
179 "tree_base=s", # applet code directory;
180 ],
181  
182 # there is no base option that we ignore
183 [],
184 );
185 }
186  
187  
188 # provide help portions
189 sub help
190 {
191 # get and check parameters
192 (my __PACKAGE__ $me)=@_;
193 confess "[BUG] Missing object parameter.\n" unless $me;
194 confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
195  
196 # to get a flexible tool, help texts are supplied in portions
197 {
198 # supply the options part
199 OPTIONS => {
200 # template files: document files
201 doc_template => qq(),
202  
203 # template files: header contents
204 header_template => qq(),
205 header_idx_template => qq(),
206 header_toc_template => qq(),
207  
208 # template files: body top
209 top_template => qq(),
210 top_idx_template => qq(),
211 top_toc_template => qq(),
212  
213 # template files: body bottom
214 bottom_template => qq(),
215 bottom_idx_template => qq(),
216 bottom_toc_template => qq(),
217  
218 # template files: navigation
219 nav_template => qq(),
220 nav_top_template => qq(),
221 nav_bottom_template => qq(),
222  
223 # template strings
224 bot_left_txt => qq(),
225 bot_middle_txt => qq(),
226 bot_right_txt => qq(),
227 contents_header => qq(),
228 index_header => qq(),
229 label_contents => qq(),
230 label_index => qq(),
231 label_next => qq(),
232 label_prev => qq(),
233 top_left_txt => qq(),
234 top_middle_txt => qq(),
235 top_right_txt => qq(),
236  
237 # logo
238 logo_image_filename => qq(),
239  
240 # links
241 bootstrapaddress => qq(),
242 startaddress => qq(),
243  
244 # link navigation
245 linknavigation => qq(),
246  
247 # tree applet support
248 appletdir => qq(),
249 applet_dir => qq(),
250 appletref => qq(),
251 applet_ref => qq(),
252  
253 tree_app_hint => qq(),
254 tree_app_height => qq(),
255 tree_app_width => qq(),
256 tree_base => qq(),
257 },
258  
259 # supply synopsis part
260 SYNOPSIS => <<EOS,
261  
262 In this call, you are using C<Template::Traditional> templates. The Traditional template engine
263 is intended to allow further use of C<pp2html> styles with new Generator based converters. It
264 supports most of the options and keywords of C<pp2html>'s styles, plus a few additional.
265  
266 Compared to other templating systems like the Template Toolkit, PerlPoint::Traditional
267 templates are very straightforward. Simple keywords are replaced by certain replacements.
268 This isn't very sophisticated, but it has the advantage to not require any additional modules
269 installed. If you are not satisfied by this template language, please check out templates
270 using other engines - search CPAN for C<PerlPoint::Template::Xyz> modules.
271  
272 =head3 Template files
273  
274 Following the tradition of C<pp2html>, Traditional templates expect a I<page body> to be
275 described by up to I<four> files which embed the page contents. The layer scheme is shown
276 here:
277  
278 page body: <body>
279  
280 top template
281  
282 optional top navigation template
283  
284 contents
285  
286 optional bottom navigation template
287  
288 bottom template
289  
290 </body>
291  
292 Top and bottom template files are specified by options C<-top_template> and C<-bottom_template>
293 for kernel pages, and C<-top_idx_template> and C<-bottom_idx_template> for index pages, and
294 C<-top_toc_template> and C<-bottom_toc_template> for TOC pages.
295  
296 Navigation template files are specified by C<-nav_top_template> and C<-nav_bottom_template>.
297 These files are optional, the options can be omitted. If top and bottom navigation template
298 are identical, one can use C<-nav_template> to specify them both at once.
299  
300 The C<<body>> and C<</body>> tags are no part of the templates, they are added automatically.
301  
302 While in C<pp2html> the header of a generated page was written automatically, it now became
303 template driven as well. Use option C<-header_template> (or C<header_idx_template> or
304 C<-header_toc_template>, respectively) to specify the appropriate template.
305  
306 A header template is built according to the same rules as body (part) templates, although
307 there are template keywords that are designed for header use only, see below.
308  
309 The following scheme shows the complete layer model, including tags added automatically. Those
310 tags should I<not> be written to the template files.
311  
312 page frame: <html>
313  
314 page header: <head>
315  
316 header template
317  
318 </head>
319  
320 page body: <body>
321  
322 top template
323  
324 optional top navigation template
325  
326 - page contents -
327  
328 optional bottom navigation template
329  
330 bottom template
331  
332 </body>
333  
334 page frame: </html>
335  
336 Additionally, one can produce I<supplementary files> such as frames. These files are templated
337 completely, not in parts, and get specified by C<-doc_template> for files to be produced I<once>
338 and C<-supplement_template> (or C<-supplement_idx_template> or C<-supplement_toc_template>,
339 respectively) for page specific files. The names of those generated files depend on the template
340 names and are composed as a sequence of the C<-prefix> value, the template file basename, a dash,
341 the page number. another dash and the value of option C<-suffix> for page specific files
342 (C<<prefix>-<tfile>-<pagenumber><suffix>>, example: C<doc-baseframe-10.html>). For document
343 specific files templated via C<-doc_template>, the rule is C<<prefix>-<tfile><suffix>>, example:
344 C<doc-frameset.html>. Each of these template options can be specified multiply, to produce as
345 many files as you are in need of.
346  
347 Example: To produce a frameset with three frames
348 (top, contents, bottom), we need a frameset
349 file (one for all pages given we can navigate
350 internally), and three frame files per chapter,
351 which are the usual contents file plus two
352 extra files for the page specific top and
353 bottom frames.
354  
355 These options will do the job:
356  
357 -prefix doc -suffix .${\( lc($me->{generator}{options}{target}) )}
358  
359 -doc_template frameset.tpl
360 -supplement_template topframe.tpl
361 -supplement_template bottomframe.tpl
362  
363 plus the usual options to template the contents
364 page (which is the middle frame here).
365  
366 As a result, we will get
367  
368 - one file doc-frameset.${\( lc($me->{generator}{options}{target}) )}
369 - and three files per page:
370  
371 * doc-topframe-<page>.${\( lc($me->{generator}{options}{target}) )}
372 * doc-<page>.${\( lc($me->{generator}{options}{target}) )}
373 * doc-bottomframe-<page>.${\( lc($me->{generator}{options}{target}) )}
374  
375 Knowing how the filenames are build, all files can be interlinked with ease.
376  
377 =head3 Keywords
378  
379 The keywords supported in Traditional templates are listed in the following.
380  
381 =over 4
382  
383 =item BOT_LEFT_TXT
384  
385 Inserts the text specified by option C<-bot_left_txt>.
386  
387 =item BOT_MIDDLE_TXT
388  
389 Inserts the text specified by option C<-bot_middle_txt>.
390  
391 =item BOT_RIGHT_TXT
392  
393 Inserts the text specified by option C<-bot_right_txt>.
394  
395 =item BOOTSTRAP_ADDRESS
396  
397 Inserts the URL specified by option C<-boostrapaddress>, pointing to the absolute start URL
398 (a page that does not need to be generated, by the way).
399  
400 =item DATE(<format>)
401  
402 This is a I<function> and will be replaced by the current data and time, formatted via
403 C<POSIX::strftime()>. The <format> is required in C<POSIX::strftime()> syntax.
404  
405 Example: DATE(%c)
406  
407 =item DOCAUTHOR
408  
409 The I<document> author, as specified by option C<-docauthor>.
410  
411 =item DOCDATE
412  
413 The document date/time string, as configured by option C<-docdate>.
414  
415 =item DOCSUBTITLE
416  
417 The I<document> subtitle, as specified by option C<-docsubtitle>.
418  
419 =item DOCTITLE
420  
421 The I<document> title, as specified by option C<-doctitle>.
422  
423 =item LABEL_CONTENTS
424  
425 Inserts the text specified by option C<-label_contents>.
426  
427 =item LABEL_INDEX
428  
429 Inserts the text specified by option C<-label_index>.
430  
431 =item LABEL_NEXT
432  
433 Inserts the text specified by option C<-label_next>.
434  
435 =item LABEL_PREV
436  
437 Inserts the text specified by option C<-label_prev>.
438  
439 =item LOGO_IMAGE_FILENAME
440  
441 =item OPT(<option>, <text>)
442  
443 Inserts <text> if <option> is set. The <text> can contain further keywords, except for
444 nested C<OPT()> calls.
445  
446 For reasons of parsing, make sure the closing paren is the last paren in the template
447 line, as the function consumes everything till there.
448  
449 Example: OPT(flavicon, <p>These pages use flavicons.</p>)
450  
451 =item PAGE_CONTENTS
452  
453 The page number of the TOC page.
454  
455 =item PAGE_FIRST
456  
457 The page number of the first page.
458  
459 =item PAGE_HERE
460  
461 The page number of the current page.
462  
463 =item PAGE_INDEX
464  
465 The page number of the index page, if any.
466  
467 =item PAGE_LAST
468  
469 The page number of the last page.
470  
471 =item PAGE_NEXT
472  
473 The page number of the next page, if any.
474  
475 =item PAGE_PATH
476  
477 This inserts the "path" of the current chapter, which is a sequence of (short) chapter titles
478 (being links to the chapters), leading from root to the current page. This is useful for
479 navigation, to allow readers quick jumps to higher level base chapters.
480  
481 The start URL specified by C<-bootstrapaddress> always starts the path. Levels are delimited by
482 slashes.
483  
484 Example: If in the hierarchy of chapters
485  
486 1. Root Level
487  
488 1.1. Sublevel
489  
490 1.2. More about this
491  
492 1.2.1. Example
493  
494 the PAGE_PATH keyword should be replaced on every page,
495 the result would be
496  
497 for 1.: Start URL
498  
499 for 1.1.: Start URL / Root Level
500  
501 for 1.2.: Start URL / Root Level
502  
503 for 1.2.1.: Start URL / Root level / More about this
504  
505 =item PAGE_PREV
506  
507 The page number of the previous page, if any.
508  
509 =item PAGE_UP
510  
511 The page number of the parent page.
512  
513 =item REF(E<lt>separatorE<gt>E<lt>whitespace(s)E<gt>E<lt>address> E<lt>separatorE<gt> E<lt>textE<gt>)
514  
515 A link to a document anchor, described by E<lt>addressE<gt>. Addresses are specified the same
516 way as in the C<name> option of C<\REF> tags, see there for details. The E<lt>textE<gt>
517 is used to set up the link text. Address and text are delimited by a string defined
518 as E<lt>separatorE<gt>. The whitespace after the separator definition is I<mandatory>,
519 more whitespaces can be used at your option.
520  
521 Examples:
522  
523 REF(, An interesting chapter, Chapter)
524  
525 REF(--- Overview | perl, parl and PAR --- A PAR intro)
526  
527 Closing parens within addresses or texts have to be preceeded by a backslash.
528  
529 REF(# Tools (par and parl\) # Tools)
530  
531 =item START_ADDRESS
532  
533 Inserts the URL specified by option C<-startaddress>, pointing to the very first page.
534  
535 =item TREE_APPLET_TOC
536  
537 Inserts code for the free Java navigation applet traditionally provided with C<pp2html>.
538 Different to C<pp2html>, the "Traditional" template engine does not generate applet TOC
539 pages on its own, but it supports styles that build such pages. To do so, just use this
540 wildcard in a TOC template specified by C<-top_toc_template> or C<-bottom_toc_template>.
541  
542 If the wildcard is used, the template engine copies all necessary Java files into the
543 directory specified by option C<-appletdir>. Other related options are C<-appletdir>
544 (or C<-applet_dir>), C<-appletref> (or C<-applet_ref>), C<-tree_app_hint>, C<-tree_app_height>,
545 C<-tree_app_width> and C<-tree_base>.
546  
547  
548 =item TXT_CONTENTS
549  
550 The title of the TOC page.
551  
552 =item TXT_FIRST
553  
554 The title of the first page.
555  
556 =item TXT_HERE
557  
558 The title of the current page.
559  
560 =item TXT_INDEX
561  
562 The title of the index page, if any.
563  
564 =item TXT_LAST
565  
566 The title of the last page.
567  
568 =item TXT_NEXT
569  
570 The title of the next page, if any.
571  
572 =item TXT_PREV
573  
574 The title of the previous page, if any.
575  
576 =item TXT_UP
577  
578 The title of the parent page.
579  
580 =item TOP_LEFT_TXT
581  
582 Inserts the text specified by option C<-top_left_txt>.
583  
584 =item TOP_MIDDLE_TXT
585  
586 Inserts the text specified by option C<-top_middle_txt>.
587  
588 =item TOP_RIGHT_TXT
589  
590 =item TITLE
591  
592 The I<page> title (chapter headline).
593  
594 =item URL_CONTENTS
595  
596 The URL of the TOC page.
597  
598 =item URL_FIRST
599  
600 The URL of the first page.
601  
602 =item URL_HERE
603  
604 The URL of the current page.
605  
606 =item URL_INDEX
607  
608 The URL of the index page, if any.
609  
610 =item URL_LAST
611  
612 The URL of the last page.
613  
614 =item URL_NEXT
615  
616 The URL of the next page, if any.
617  
618 =item URL_PREV
619  
620 The URL of the previous page, if any.
621  
622 =item URL_UP
623  
624 The URL of the parent page.
625  
626 =item VAR(<var>) or VAR_AT_FINISH(<var>)
627  
628 Inserts the value of the PerlPoint variable <var>, with the value available at the I<end>
629 of the chapter.
630  
631 Example: VAR(language)
632  
633 =item VAR_AT_BEGIN(<var>)
634  
635 Inserts the value of the PerlPoint variable <var>, with the value available at the I<beginning>
636 of the chapter.
637  
638 Example: VAR_AT_BEGIN(language)
639  
640 =item CSS_LINKTAGS
641  
642 Inserts tags to load CSS files specified by option C<-css>. The stylesheet specified first
643 will be made the main stylesheet, while all subsequently specified sheets will be included
644 as alternatives, in the order they were declared.
645  
646 According to the specs, this keyword should be used in header templates only. (This will not
647 be checked by the template engine.)
648  
649 =item DOC_METATAGS
650  
651 According to the specs, this keyword should be used in header templates only. (This will not
652 be checked by the template engine.)
653  
654 =item FAVICON_LINKTAG
655  
656 Inserts a favicon link tag referring to the icon specified by option C<-favicon>. If the
657 option was omitted, the keyword will be replaced by an empty string.
658  
659 For details about favicons, please see the description of C<-favicon>.
660  
661 According to the specs, this keyword should be used in header templates only. (This will not
662 be checked by the template engine.)
663  
664 =item LINK_NAVIGATION
665  
666 Inserts navigation link tags as specified by the W3C (C<<link rel="start" ...>> etc.). Most
667 modern browsers translate them into navigation buttons to the first, previous, next etc. page.
668  
669 According to the specs, this keyword should be used in header templates only. (This will not
670 be checked by the template engine.)
671  
672 =item PAGE
673  
674 The number of the current page. Counting starts with 1.
675  
676 =item PAGE_CNT
677  
678 The number of chapters (pages) in the document.
679  
680 Example: to display "page x of y", use
681  
682 PAGE/PAGE_CNT
683  
684 =item TITLE
685  
686 This will insert the document title, as specified by option C<-title>.
687  
688 =back
689  
690 =cut
691  
692 EOS
693 }
694 }
695  
696  
697  
698 # bootstrap
699 sub bootstrap
700 {
701 # get and check parameters
702 (my __PACKAGE__ $me)=@_;
703 confess "[BUG] Missing object parameter.\n" unless $me;
704 confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
705  
706 # don't forget the base method
707 $me->SUPER::bootstrap();
708  
709 # copy CSS and JavaScript files, if necessary
710 my $dir=join('/', $me->{generator}{cfg}{setup}{stylepath}, $me->options->{style}, 'templates');
711 foreach my $file (<$dir/*.css>, <$dir/*.js>)
712 {
713 # get basename
714 my $basename=basename($file);
715  
716 # copy file, if necessary
717 if (
718 not -e "$me->{generator}{options}{targetdir}/$basename"
719 or -M "$me->{generator}{options}{targetdir}/$basename" > -M $file
720 )
721 {
722 warn "[Info] Copying ", $file=~/\.css$/i ? 'CSS' : 'JavaScript', " file $file to target directory $me->{generator}{options}{targetdir}.\n";
723 copy($file, $me->{generator}{options}{targetdir}) or die "[Fatal] Could not copy $file to $me->{generator}{options}{targetdir}.\n";
724 }
725 }
726  
727 # configure applet options as necessary
728 $me->{options}{tree_app_hint}='Please, activate Java.' unless exists $me->{options}{tree_app_hint};
729 $me->{options}{tree_app_height}=400 unless exists $me->{options}{tree_app_height};
730 $me->{options}{tree_app_width}=200 unless exists $me->{options}{tree_app_width};
731 $me->{options}{appletdir}=$me->{options}{targetdir} unless exists $me->{options}{appletdir};
732  
733 if (not exists $me->{options}{appletref})
734 {
735 if ($me->{options}{appletdir} eq $me->{options}{targetdir})
736 {$me->{options}{appletref}='.';}
737 else
738 {
739 if ($me->{options}{appletdir}=~m(^/))
740 {
741 # we got an absolute path, use it
742 $me->{options}{appletref}=$me->{options}{appletdir};
743 }
744 else
745 {
746 # we got a relative path, absolutify it and use the result
747 my ($base, $path, $type)=fileparse($me->{options}{appletdir});
748 $me->{options}{appletref}=join('/', abs_path($path), basename($me->{options}{appletdir}));
749 }
750 }
751 }
752  
753 $me->{options}{tree_base}=$me->{options}{appletref} unless exists $me->{options}{tree_base};
754  
755 # make applet target directory, if necessary
756 if (exists $me->{options}{appletdir} and not -d $me->{options}{appletdir})
757 {
758 warn "[Info] Making tree applet directory $me->{options}{appletdir}.\n" unless exists $me->{options}{noinfo};
759 mkpath($me->{options}{appletdir});
760 }
761 }
762  
763  
764 # check usage
765 sub checkUsage
766 {
767 # get and check parameters
768 (my __PACKAGE__ $me)=@_;
769 confess "[BUG] Missing object parameter.\n" unless $me;
770 confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
771  
772 # don't forget the base class
773 $me->SUPER::checkUsage;
774  
775 # get options
776 my $options=$me->options;
777  
778 # check mandatory options
779 foreach (qw(header_template top_template bottom_template))
780 {die qq([Fatal] "Traditional" templates require option -$_.\n) unless exists $options->{$_};}
781  
782 # check mandatory files
783 foreach (qw(header_template top_template bottom_template))
784 {
785 my $filename="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates/$options->{$_}";
786 die qq([Fatal] Missing "Traditional" "-$_" template file "$options->{$_}".\n) unless -e $filename;
787 }
788  
789 # check files belonging to optional options
790 foreach (
791 qw(
792 doc_template
793  
794 header_idx_template
795 header_toc_template
796  
797 top_idx_template
798 top_toc_template
799  
800 bottom_idx_template
801 bottom_toc_template
802  
803 nav_template
804 nav_idx_template
805 nav_toc_template
806  
807 supplement_template
808 supplement_idx_template
809 supplement_toc_template
810 )
811 )
812 {
813 # skip check if option unused
814 next unless exists $options->{$_};
815  
816 # template options can specify one or multiple files
817 unless (ref $options->{$_})
818 {
819 my $filename="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates/$options->{$_}";
820 die qq([Fatal] Missing "Traditional" "-$_" template file "$options->{$_}".\n) unless -e $filename;
821 }
822 else
823 {
824 # process each file
825 foreach my $template (@{$options->{$_}})
826 {
827 my $filename="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates/$template";
828 die qq([Fatal] Missing "Traditional" "-$_" template file "$template".\n) unless -e $filename;
829 }
830 }
831 }
832  
833 # flag success
834 1;
835 }
836  
837  
838 # the transformator
839 sub transform
840 {
841 # get and check parameters
842 ((my __PACKAGE__ $me), my %params)=@_;
843 confess "[BUG] Missing object parameter.\n" unless $me;
844 confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
845 confess "[BUG] Missing action parameter.\n" unless exists $params{action} and defined $params{action};
846 unless (
847 $params{action}==TEMPLATE_ACTION_DOC
848 or $params{action}==TEMPLATE_ACTION_TOC
849 or $params{action}==TEMPLATE_ACTION_INDEX
850 )
851 {
852 confess "[BUG] Missing page number parameter.\n" unless exists $params{page} and defined $params{page};
853 confess "[BUG] Missing data parameter.\n" unless exists $params{data} and defined $params{data};
854 }
855  
856 # declarations
857 my ($result)=('');
858  
859 # get options
860 my $options=$me->options;
861  
862 # build template directory path
863 my $tdir="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates";
864  
865 # transform source data into a string, if required
866  
867 # act action dependent: generate document pages
868 $params{action}==TEMPLATE_ACTION_DOC and do
869 {
870 # first look if there are supplements to process
871 if (exists $options->{doc_template})
872 {
873 # process each supplement
874 foreach my $template (@{$options->{doc_template}})
875 {
876 # process template (use first page number)
877 my $string=$me->_processTemplate("$tdir/$template", 1);
878  
879 # build file name
880 my $filename=join('', "$options->{targetdir}/$options->{prefix}-", (fileparse($template, qr(\.[^.]+)))[0], $options->{suffix});
881  
882 # write file
883 open(SUPPFILE, ">$filename") or die qq([Fatal] Could not open output file "$filename": $!.\n);
884 print SUPPFILE $string;
885 close(SUPPFILE);
886 }
887 }
888 };
889  
890 # act action dependent: generate a (toc) page
891 ($params{action}==TEMPLATE_ACTION_PAGE or $params{action}==TEMPLATE_ACTION_TOC) and do
892 {
893 # anything to do?
894 return if $params{action}==TEMPLATE_ACTION_TOC and not exists $options->{header_toc_template};
895 my $toc=$params{action}==TEMPLATE_ACTION_TOC;
896  
897 # start page
898 $result.="\n\n<html>\n\n";
899  
900 # begin header
901 $result.="\n\n<head>\n\n";
902  
903 # header contents: this was added to the traditional list of template files
904 $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'header_toc_template' : 'header_template'}), $toc ? 1 : $params{page});
905  
906 # complete header
907 $result.="\n\n</head>\n\n";
908  
909 # begin body
910 $result.="\n\n<body>\n\n";
911  
912 # now the body contents: start with top part
913 $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'top_toc_template' : 'top_template'}), $toc ? 1 : $params{page});
914  
915 # add navigation, if necessary
916 $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'nav_toc_template' : 'nav_template'}), $toc ? 1 : $params{page})
917 if exists $options->{$toc ? 'nav_toc_template' : 'nav_template'};
918  
919 # include data (for TOCs, make sure not to add a standard TOC if the tree applet is used
920 # - this should be more generic in case users use other methods ...)
921 $result.=$toc ? $result=~/<applet code="TreeApp\.class" codebase=/ ? '' : $me->_toc() : $params{data};
922  
923 # add bottom navigation, if necessary
924 $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'nav_toc_template' : 'nav_template'}), $toc ? 1 : $params{page})
925 if exists $options->{$toc ? 'nav_toc_template' : 'nav_template'};
926  
927 # finally, add the bottom part
928 $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'bottom_toc_template' : 'bottom_template'}), $toc ? 1 : $params{page});
929  
930 # close the body
931 $result.="\n\n</body>\n\n";
932  
933 # and complete the page
934 $result.="\n\n</html>\n\n";
935 };
936  
937  
938 # act action dependent: generate supplements
939 $params{action}==TEMPLATE_ACTION_PAGE_SUPPLEMENTS and do
940 {
941 # first look if there are supplements to process
942 if (exists $options->{supplement_template})
943 {
944 # process each supplement
945 foreach my $template (@{$options->{supplement_template}})
946 {
947 # process template
948 my $string=$me->_processTemplate("$tdir/$template", $params{page});
949  
950 # build file name
951 my $filename=join('', "$options->{targetdir}/$options->{prefix}-", (fileparse($template, qr(\.[^.]+)))[0], "-$params{page}$options->{suffix}");
952 warn "= PAGE SUPPLEMENT =====> $filename\n";
953  
954 # write file
955 open(SUPPFILE, ">$filename") or die qq([Fatal] Could not open output file "$filename": $!.\n);
956 print SUPPFILE $string;
957 close(SUPPFILE);
958 }
959 }
960 };
961  
962 # retransform string result into a special data format, if required
963  
964 # supply result
965 $result;
966 }
967  
968  
969  
970 # helper functions ##########################################################
971  
972 # process a template
973 sub _processTemplate
974 {
975 # get and check parameters
976 ((my __PACKAGE__ $me), my ($file, $page))=@_;
977 confess "[BUG] Missing object parameter.\n" unless $me;
978 confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
979 confess "[BUG] Missing template file parameter.\n" unless $file;
980 confess "[BUG] Missing page data parameter.\n" unless $page;
981  
982 # declare variables
983 my (@result);
984  
985 # common preprocessing
986 my $td=$me->preprocessData($page);
987  
988 # get options
989 my $options=$me->options;
990  
991 # stylesheet links
992 my $cssLinkTags=join('', exists $options->{css} ? map
993 {
994 # extract title and filename
995 my ($file, $title)=split(':', $options->{css}[$_], 2);
996 $title="unnamed $_" if $_ and not $title;
997  
998 # add css links
999 join('',
1000 qq(<link href="$file"),
1001 $_ ? qq( title="$title") : '',
1002 ' rel="', $_<2 ? 'stylesheet' : 'alternate stylesheet', '"',
1003 qq( type="text/css"),
1004 qq( />\n),
1005 );
1006 } 0..$#{$options->{css}} : (),
1007 );
1008  
1009 # add favicon link, if necessary
1010 my $faviconLinkTag=exists $me->{options}{favicon} ? qq(<link href="$me->{options}{favicon}" rel="SHORTCUT ICON" type="image/ico" />\n) : '';
1011  
1012 # the "doc..." options are reserved for further data ... stored in meta tags
1013 my $docMetaTags='';
1014 for (sort grep((/^doc/ and not /^doc(_|title)/), keys %$options))
1015 {
1016 /^doc(.+)$/;
1017 my $tag=$me->{generator}->elementName("_$1");
1018 $docMetaTags.=join('', qq( <meta name="$tag" content="$options->{$_}" />\n)) if exists $options->{$_};
1019 };
1020  
1021 # add more meta tags, if necessary
1022 $docMetaTags.=qq( <meta name="ROBOTS" content="NOINDEX, NOFOLLOW" />\n) if exists $options->{norobots};
1023 $docMetaTags.=qq( <meta name="MSSmartTagsPreventParsing" content="true" />\n) if exists $options->{nosmarttags};
1024  
1025 # prepare <link> navigation if required
1026 my $linkNavigation='';
1027 if (exists $options->{linknavigation})
1028 {
1029 # activate available elements
1030 $linkNavigation.=qq( <link rel="start" href="$td->{fFile}" />\n) if $td->{fFile};
1031 $linkNavigation.=qq( <link rel="prev" href="$td->{pFile}" />\n) if $td->{pFile};
1032 $linkNavigation.=qq( <link rel="next" href="$td->{nFile}" />\n) if $td->{nFile};
1033 $linkNavigation.=qq( <link rel="up" href="$td->{uFile}" />\n) if $td->{uFile};
1034 $linkNavigation.=qq( <link rel="last" href="$td->{lFile}" />\n) if $td->{lFile};
1035  
1036 # the contents link is always available
1037 $linkNavigation.=qq( <link rel="contents" href="$td->{tocFile}" />\n);
1038  
1039 # add the index link, if possible
1040 $linkNavigation.=qq( <link rel="index" href="$td->{indexFile}" />\n) if $td->{indexFile} and not exists $options->{no_index};
1041 }
1042  
1043 # prepare the linked page path
1044 my $cPath=join(' / ', map {join('', qq(<a href="$_->[0]">$_->[1]</a>));} @{$td->{cPath}});
1045  
1046 # ok, open template
1047 open(TPL, $file) or die "[Fatal] Can't open template $file: $!\n";
1048  
1049 # replace placeholders
1050 while (<TPL>)
1051 {
1052 # optional parts (evaluate them first, to allow placeholders in substitutions)
1053 s/OPT\((.+?),\s*(.+)\s*\)/exists $options->{$1} ? $2 : ''/ge;
1054  
1055 # process static placeholders
1056 s/\bTITLE\b/$td->{title}/g;
1057 s/\bCSS_LINKTAGS\b/$cssLinkTags/g;
1058 s/\bFAVICON_LINKTAG\b/$faviconLinkTag/g;
1059 s/\bDOC_METATAGS\b/$docMetaTags/g;
1060 s/\bLINK_NAVIGATION\b/$linkNavigation/g;
1061  
1062 s/URL_FIRST/$td->{fFile}/g;
1063 s/TXT_FIRST/$td->{fText}/g;
1064 s/PAGE_FIRST/$td->{fNumber}/g;
1065  
1066 s/URL_HERE/$td->{cFile}/g;
1067 s/TXT_HERE/$td->{cText}/g;
1068 s/PAGE_HERE/$td->{cNumber}/g;
1069  
1070 s/URL_LAST/$td->{lFile}/g;
1071 s/TXT_LAST/$td->{lText}/g;
1072 s/PAGE_LAST/$td->{lNumber}/g;
1073  
1074 s/URL_PREV/$td->{pFile}/g;
1075 s/TXT_PREV/$td->{pText}/g;
1076 s/PAGE_PREV/$td->{pNumber}/g;
1077  
1078 s/URL_NEXT/$td->{nFile}/g;
1079 s/TXT_NEXT/$td->{nText}/g;
1080 s/PAGE_NEXT/$td->{nNumber}/g;
1081  
1082 s/URL_UP/$td->{uFile}/g;
1083 s/TXT_UP/$td->{uText}/g;
1084 s/PAGE_UP/$td->{uNumber}/g;
1085  
1086 # what's this meant to be???
1087 # s/<[\s\w="]*URL_DOWN[\s"]*?>/$url_down/g;
1088 # s/TXT_DOWN/$txt_down/g;
1089  
1090 # addresses of specific pages
1091 s/URL_CONTENTS/$td->{tocFile}/g;
1092 s/URL_INDEX/$td->{indexFile}/g;
1093  
1094 # page data
1095 s/\bPAGE_CNT\b/$td->{pageNr}/g;
1096 s/\bPAGE\b/$page/g;
1097 s/PAGE_PATH/$cPath/g;
1098  
1099 # various straight forward keyword/option translations
1100 s/TXT_CONTENTS/exists $options->{contents_header} ? $options->{contents_header} : ''/geo;
1101 s/TXT_INDEX/exists $options->{index_header} ? $options->{index_header} : ''/geo;
1102 s/BOOTSTRAP_ADDRESS/exists $options->{boostrapaddress} ? $options->{boostrapaddress} : ''/geo;
1103 s/START_ADDRESS/exists $options->{startaddress} ? $options->{startaddress} : ''/geo;
1104 foreach my $keyword (qw(
1105 BOT_LEFT_TXT
1106 BOT_MIDDLE_TXT
1107 BOT_RIGHT_TXT
1108 DOCAUTHOR
1109 DOCDATE
1110 DOCSUBTITLE
1111 DOCTITLE
1112 LABEL_CONTENTS
1113 LABEL_INDEX
1114 LABEL_NEXT
1115 LABEL_PREV
1116 LOGO_IMAGE_FILENAME
1117 PREFIX
1118 SUFFIX
1119 TOP_LEFT_TXT
1120 TOP_MIDDLE_TXT
1121 TOP_RIGHT_TXT
1122 )
1123 )
1124 {s/$keyword/exists $options->{lc($keyword)} ? $options->{lc($keyword)} : ''/ge;}
1125  
1126 # "functions"
1127 s/DATE\((.+?)\)/strftime($1, localtime)/ge;
1128 s/REF\((\S+)\s+(.+)(?:\s*\1\s*(.+))(?<!\\)\)/$me->{generator}->buildAnchorLink($2, defined($3) ? $3 : ())/ge;
1129  
1130 # variables
1131 s/VAR(_AT_FINISH)?\((.+?)\)/exists $td->{cVars}{$2} ? $td->{cVars}{$2} : ''/ge;
1132 s/VAR_AT_BEGIN\((.+?)\)/exists $td->{pVars}{$1} ? $td->{pVars}{$1} : ''/ge;
1133  
1134 # special: tree applet index
1135 if (/TREE_APPLET_TOC/)
1136 {
1137 # copy applet classes, if necessary
1138 my $appletSrcDir="$me->{generator}{cfg}{setup}{stylepath}/$me->{generator}{options}{style}/templates/applet_src";
1139 die("[Fatal] No applet source directory in ", dirname($appletSrcDir), ".\n") unless -d $appletSrcDir;
1140 foreach my $appletfile (sort <$appletSrcDir/*.class>)
1141 {
1142 # get image basename
1143 my $basename=basename($appletfile);
1144  
1145 # copy image, if necessary
1146 if (
1147 exists $me->{options}{appletdir}
1148 and (
1149 not -e "$me->{options}{appletdir}/$basename"
1150 or -M "$me->{options}{appletdir}/$basename" > -M $appletfile
1151 )
1152 )
1153 {
1154 # inform user, unless suppressed
1155 warn qq([Info] Copying tree applet file $appletfile to $me->{options}{appletdir}.\n) unless exists $me->{options}{noinfo};
1156  
1157 # perform action
1158 copy($appletfile, $me->{options}{appletdir});
1159 }
1160 }
1161  
1162 # begin the applet code string
1163 my $applet=<<EOA;
1164  
1165 <applet code="TreeApp.class" codebase="$options->{tree_base}" alt="$options->{tree_app_hint}" name="Tree" width="$options->{tree_app_width}" height="$options->{tree_app_height}">
1166 <param name=bgColor value="FFFFFF">
1167 <param name=font value="Helvetica-plain-14">
1168 <param name="rootTitle" value="$options->{doctitle};book.gif,o_book.gif;;$options->{doctitle}">
1169 <param name="expanded" value="true">
1170 <param name="baseURL" value="./">
1171  
1172 EOA
1173  
1174 # add hints for all pages
1175 foreach my $chapter (1..$td->{pageNr})
1176 {
1177 # get short path in the required format (levels delimited by slashes)
1178 my @apath=@{$me->page($chapter)->path(type=>'spath', mode=>'array')};
1179 my $apath=join('/', @apath);
1180 die "[Fatal] Missing levels in $apath.\n" if grep(not (defined), @apath);
1181  
1182 # update applet string
1183 $applet.=join('', qq(<param name="item$chapter" value="$apath;book.gif,o_book.gif;), $me->buildFilename($chapter), qq(,Data;$apath">\n));
1184 }
1185  
1186 # complete applet code
1187 $applet.="\n</applet>\n\n";
1188  
1189 # ok, replace the wildcard
1190 s/TREE_APPLET_TOC/$applet/g;
1191 }
1192  
1193 # finally, add the transform lines to the result string
1194 push(@result, $_);
1195 }
1196  
1197 # close template file
1198 close(TPL);
1199  
1200 # supply result
1201 join('', @result);
1202 }
1203  
1204  
1205 # build a toc
1206 sub _toc
1207 {
1208 # get and check parameters
1209 my ($me)=@_;
1210 confess "[BUG] Missing object parameter.\n" unless $me;
1211 confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
1212  
1213 # declare variables
1214 my (@result);
1215  
1216 # common preprocessing
1217 my $td=$me->preprocessData(1);
1218  
1219 # add entries for all pages
1220 foreach my $chapter (1..$td->{pageNr})
1221 {
1222 # get short path in the required format (levels delimited by slashes)
1223 my @apath=@{$me->page($chapter)->path(type=>'spath', mode=>'array')};
1224 my $apath=join('/', @apath);
1225 die "[Fatal] Missing levels in $apath.\n" if grep(not (defined), @apath);
1226  
1227 # add string
1228 push(@result, join('', qq(<p class="s), scalar(@apath), qq("><a href="), $me->buildFilename($chapter), qq(">$apath[-1]</a></p>\n)));
1229 }
1230  
1231 # supply result
1232 join('', @result);
1233 }
1234  
1235  
1236  
1237  
1238 # flag successful loading
1239 1;
1240  
1241 # = POD TRAILER SECTION =================================================================
1242  
1243 =pod
1244  
1245 =head1 NOTES
1246  
1247  
1248 =head1 SEE ALSO
1249  
1250 =over 4
1251  
1252  
1253  
1254 =back
1255  
1256  
1257 =head1 SUPPORT
1258  
1259 A PerlPoint mailing list is set up to discuss usage, ideas,
1260 bugs, suggestions and translator development. To subscribe,
1261 please send an empty message to perlpoint-subscribe@perl.org.
1262  
1263 If you prefer, you can contact me via perl@jochen-stenzel.de
1264 as well.
1265  
1266 =head1 AUTHOR
1267  
1268 Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2004-2006.
1269 All rights reserved.
1270  
1271 This module is free software, you can redistribute it and/or modify it
1272 under the terms of the Artistic License distributed with Perl version
1273 5.003 or (at your option) any later version. Please refer to the
1274 Artistic License that came with your Perl distribution for more
1275 details.
1276  
1277 The Artistic License should have been included in your distribution of
1278 Perl. It resides in the file named "Artistic" at the top-level of the
1279 Perl source tree (where Perl was downloaded/unpacked - ask your
1280 system administrator if you dont know where this is). Alternatively,
1281 the current version of the Artistic License distributed with Perl can
1282 be viewed on-line on the World-Wide Web (WWW) from the following URL:
1283 http://www.perl.com/perl/misc/Artistic.html
1284  
1285  
1286 =head1 DISCLAIMER
1287  
1288 This software is distributed in the hope that it will be useful, but
1289 is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or
1290 implied, INCLUDING, without limitation, the implied warranties of
1291 MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.
1292  
1293 The ENTIRE RISK as to the quality and performance of the software
1294 IS WITH YOU (the holder of the software). Should the software prove
1295 defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
1296 CORRECTION.
1297  
1298 IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE,
1299 MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO
1300 ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even
1301 if they arise from known or unknown flaws in the software).
1302  
1303 Please refer to the Artistic License that came with your Perl
1304 distribution for more details.
1305