File Coverage

blib/lib/Text/Merge/Lists.pm

Criterion	Covered	Total	%
statement	124	149	83.2
branch	54	90	60.0
condition	23	53	43.4
subroutine	11	12	91.6
pod	4	9	44.4
total	216	313	69.0

elements respectively. Start your header with

line	stmt	sub	time	code
1				#!/usr/local/bin/perl -Tw
2	6	6	5012	use strict;
	6		13
	6		823
3
4				#
5				# (C) 1997, 1998, 1999 by Steven D. Harris.
6				# This software is released under the Perl Artistic License
7				#
8
9				=head1 NAME
10
11				Text::Merge::Lists - v.0.30 Text/data merge with lists/table support
12
13				=head1 SYNOPSIS
14
15				$filter = new Text::Merge::Lists($template_path);
16
17				$filter->set_max_nesting_depth($intval);
18
19
20				=head1 DESCRIPTION
21
22				The C package is designed to extend the C package with "list styles" in addition
23				to the other formatting methods of fields. This allows the display of fields that contain "lists" of
24				items in addition to the normal "scalar" fields supported by C. See the C package
25				documentation for more information on templates and merging.
26
27				All the features of the C package are supported and invoked in an identical fashion. The only difference
28				in your programs to use the C object instead of the C object is the constructor,
29				which must be invoked with the "Template Path" to the directory containing your various arbitrary lists
30				style directories, described later. See the C object for a description of the publishing methods
31				available to you.
32
33				Lists can be nested, and you can use the C object method to override
34				the default maximum nesting depth of 3. That is to say, you can only have a list of a list of a list
35				by default. If you want to nest further you will need to adjust this value. The depth limit here is to
36				prevent you from clobbering the perl stack (and possibly other memory!) with deep recursion.
37
38
39				=head2 List Structure
40
41				A list variable is a reference to an ARRAY of data HASH references or item HASH references. Basically, the
42				equivalent of the C<$data> or C<$item> argument to the publishing methods. If you apply a list style to a
43				SCALAR it will be treated as a list of one item. Undefined lists are not considered empty, but they are
44				undefined as one would expect. Here is an example list assignment to the variable C<$fruit_list>:
45
46				$apple = { 'Color'=>'Red', 'Size'=>'medium', 'Shape'=>'round' };
47				$pear = { 'Color'=>'Green', 'Size'=>'medium', 'Shape'=>'pear-shaped' };
48				$grape = { 'Color'=>'Purple', 'Size'=>'small', 'Shape'=>'round' };
49				$fruit_list = [ $apple, $pear, $grape ];
50
51
52				=head2 List Style Syntax
53
54				If you have read the C module documentation, which is recommended,
55				then you may be familiar with the syntax for displaying arbitrary fields using different styles,
56				such as this example for a displaying a numerical value, stored in the C field, as a decimal
57				value with two decimal places:
58
59				REF:MyDollars:dollars
60
61				There are many display styles available, some of which only apply to I. These are
62				described in detail in the C module documentation.
63
64				The C object extends the C object with support for list (ARRAY) references. By
65				using the list style designators, you can display lists in various contexts, just as you
66				would any other field value. The templates for the various lists styles are stored in directories corresponding
67				to the list style names. These are located in the path provided to the constructor.
68
69				The individual items stored in the lists should be data or item HASH references as described in the C
70				documentation. These objects have an "ItemType" designator, allowing the individual list styles to display
71				each type differently in that context. These listing templates are plain text files, ending in '.txt' and
72				stored in the style directory. For example, a list style of 'showcase' stored in the templates
73				path C would have all of it's files stored in the path, C. If you
74				had an item type of 'book' to display in a given list, that template would be stored at
75				C. The template will be used for each occurrence of the item type
76				'book' in any list displayed using the 'showcase' style. In most cases, the listing templates will be output
77				"end on end" but that may not always be the case as described later.
78
79				The syntax for a reference to an item list field named, C, for the example list style of 'showcase'
80				would look something like this:
81
82				REF:DisplayItems:list_showcase
83
84				Notice the C portion (that is an 'underscore'). This tells the filter that you want to treat the field
85				C as a list of items and use the 'showcase' list style. The system will then look-up any templates
86				it needs for the list in the 'showcase' directory mentioned above.
87
88
89				=head2 List Style Features
90
91				Each list style has various special features that you can use by providing certain files in the list style directory.
92				These include a C , a C , a C item, and a message to display if the list is C.
93
94				=over 4
95
96				=item List Header
97
98				The list header is an HTML fragment contained in a plain text file that is treated by the filter as if it were part of
99				the original document (as opposed to a list item), it is displayed immediately before the list itself. It is
100				contained in the file C in the list style directory. This file is optional.
101
102
103				=item List Footer
104
105				The list footer is similar to the list header described above. It is displayed immediately following the list itself.
106				It is contained in the file C in the list style directory. This file is also optional.
107
108
109				=item Default Item Type
110
111				You may provide a listing fragment that will be used for any item that does not have a template in the designated
112				list style directory. This could be an error message, or it my display information universal to all of your objects.
113				You can use this item template if all of your items are very similar and you don't want to construct a template for
114				each item in that style.
115
116				The default item template is located in a file called C in the designated list style directory. This
117				file is optional.
118
119
120				=item Empty List Message
121
122				Similar to a header or footer, the empty list message is a file contained in the designate style directory that is
123				treated as part of the parent document for display purposes, if no items exist in your list. If this file is not
124				provided, then empty lists are constructed as empty strings. The file name for the empty list message is
125				C in the designated list style directory and is optional.
126
127				=back
128
129				=head2 Table Style Syntax
130
131				In addition to list styles, C also supports HTML table styles. Table styles are trickier to
132				set up than list styles, but the principle is basically the same, and you get the benefit of having more than one
133				column in your list display. You maintain full control over the styling of the individual cells and the table
134				attributes. All tables are HTML.
135
136				The syntax of a table style is very similar to the syntax of a list style, but you need to specify the number of
137				columns for the table in the tag. For example:
138
139				REF:ItemList:table4_options
140
141				The example listed above would generate a table using the table style defintion, "options", that is four columns
142				wide. The number is required and must be at least 1. Large numbers (>10) are discouraged because they are
143				practically unusable.
144
145				A table generated by a table style is basically a "grid" of the specified width with a "filler" cell at the end
146				of the table if necessary. The filler cell may be one or more cells wide, up to one less than the specified
147				table width. With this in mind, there are more restrictions on the templates required for a table style, as described
148				later.
149
150				Just as is the case with the list styles, individual items stored in the lists should be data or item HASH
151				references as described in the C documentation. These objects have an "ItemType" designator, allowing
152				the individual table styles to display the cell for each type differently in the same context. The cell
153				templates are plain text files, ending in '.txt' and stored in the table style directory.
154
155				For example, a table style of 'options' stored in the templates path C would be located at
156				C. If you had an item of type 'choice' to display in a given list, then the
157				cell template for display of that particular item would be C. Notice
158				that the path was created by stringing together the list-styles/template (C)path, the table
159				styles subdirectory (C), and the directory and path for the individual style and item type
160				(C).
161
162				If you choose to construct a table style, take care to include all the required elements. Start and finish your
163				cell templates with the	and

and end it with

164

. Remember that the Text::Merge::Lists methods will insert the and elements for rows containing 165 your cell templates. Only use and in the header and footer files, and if you do be sure to use 166 only one cell in each row and use the C field to assign the COLSPAN for that table. Observing these 167 few things should keep your tables functional. 168 169 170 =head2 Table Style Features 171 172 Each table style has similar requirements for the files stored in the designated table style directory. 173 The required files include a C

, a C