The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Merge-0.36
River stage zero No dependents
++
/ Text::Merge::Lists

NAME

Text::Merge::Lists - v.0.30 Text/data merge with lists/table support

SYNOPSIS

        $filter = new Text::Merge::Lists($template_path);

        $filter->set_max_nesting_depth($intval);

DESCRIPTION

The Text::Merge::Lists package is designed to extend the Text::Merge package with "list styles" in addition to the other formatting methods of fields. This allows the display of fields that contain "lists" of items in addition to the normal "scalar" fields supported by Text::Merge. See the Text::Merge package documentation for more information on templates and merging.

All the features of the Text::Merge package are supported and invoked in an identical fashion. The only difference in your programs to use the Text::Merge::Lists object instead of the Text::Merge object is the constructor, which must be invoked with the "Template Path" to the directory containing your various arbitrary lists style directories, described later. See the Text::Merge object for a description of the publishing methods available to you.

Lists can be nested, and you can use the set_max_nesting_depth() object method to override the default maximum nesting depth of 3. That is to say, you can only have a list of a list of a list by default. If you want to nest further you will need to adjust this value. The depth limit here is to prevent you from clobbering the perl stack (and possibly other memory!) with deep recursion.

List Structure

A list variable is a reference to an ARRAY of data HASH references or item HASH references. Basically, the equivalent of the $data or $item argument to the publishing methods. If you apply a list style to a SCALAR it will be treated as a list of one item. Undefined lists are not considered empty, but they are undefined as one would expect. Here is an example list assignment to the variable $fruit_list:

        $apple = { 'Color'=>'Red', 'Size'=>'medium', 'Shape'=>'round' };
        $pear = { 'Color'=>'Green', 'Size'=>'medium', 'Shape'=>'pear-shaped' };
        $grape = { 'Color'=>'Purple', 'Size'=>'small', 'Shape'=>'round' };
        $fruit_list = [ $apple, $pear, $grape ];

List Style Syntax

If you have read the Text::Merge module documentation, which is recommended, then you may be familiar with the syntax for displaying arbitrary fields using different styles, such as this example for a displaying a numerical value, stored in the MyDollars field, as a decimal value with two decimal places:

        REF:MyDollars:dollars

There are many display styles available, some of which only apply to particular types of data. These are described in detail in the Text::Merge module documentation.

The Text::Merge::Lists object extends the Text::Merge object with support for list (ARRAY) references. By using the list style designators, you can display lists in various contexts, just as you would any other field value. The templates for the various lists styles are stored in directories corresponding to the list style names. These are located in the path provided to the constructor.

The individual items stored in the lists should be data or item HASH references as described in the Text::Merge documentation. These objects have an "ItemType" designator, allowing the individual list styles to display each type differently in that context. These listing templates are plain text files, ending in '.txt' and stored in the style directory. For example, a list style of 'showcase' stored in the templates path /usr/templates/ would have all of it's files stored in the path, /usr/templates/showcase/. If you had an item type of 'book' to display in a given list, that template would be stored at /usr/templates/showcase/book.txt. The template will be used for each occurrence of the item type 'book' in any list displayed using the 'showcase' style. In most cases, the listing templates will be output "end on end" but that may not always be the case as described later.

The syntax for a reference to an item list field named, DisplayItems, for the example list style of 'showcase' would look something like this:

        REF:DisplayItems:list_showcase

Notice the list_ portion (that is an 'underscore'). This tells the filter that you want to treat the field DisplayItems as a list of items and use the 'showcase' list style. The system will then look-up any templates it needs for the list in the 'showcase' directory mentioned above.

List Style Features

Each list style has various special features that you can use by providing certain files in the list style directory. These include a header, a footer, a default item, and a message to display if the list is empty.

List Header

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 the original document (as opposed to a list item), it is displayed immediately before the list itself. It is contained in the file header.txt in the list style directory. This file is optional.

The list footer is similar to the list header described above. It is displayed immediately following the list itself. It is contained in the file footer.txt in the list style directory. This file is also optional.

Default Item Type

You may provide a listing fragment that will be used for any item that does not have a template in the designated list style directory. This could be an error message, or it my display information universal to all of your objects. You can use this item template if all of your items are very similar and you don't want to construct a template for each item in that style.

The default item template is located in a file called default.txt in the designated list style directory. This file is optional.

Empty List Message

Similar to a header or footer, the empty list message is a file contained in the designate style directory that is treated as part of the parent document for display purposes, if no items exist in your list. If this file is not provided, then empty lists are constructed as empty strings. The file name for the empty list message is empty.txt in the designated list style directory and is optional.

Table Style Syntax

In addition to list styles, Text::Merge::Lists also supports HTML table styles. Table styles are trickier to set up than list styles, but the principle is basically the same, and you get the benefit of having more than one column in your list display. You maintain full control over the styling of the individual cells and the table attributes. All tables are HTML.

The syntax of a table style is very similar to the syntax of a list style, but you need to specify the number of columns for the table in the tag. For example:

        REF:ItemList:table4_options

The example listed above would generate a table using the table style defintion, "options", that is four columns wide. The number is required and must be at least 1. Large numbers (>10) are discouraged because they are practically unusable.

A table generated by a table style is basically a "grid" of the specified width with a "filler" cell at the end of the table if necessary. The filler cell may be one or more cells wide, up to one less than the specified table width. With this in mind, there are more restrictions on the templates required for a table style, as described later.

Just as is the case with the list styles, individual items stored in the lists should be data or item HASH references as described in the Text::Merge documentation. These objects have an "ItemType" designator, allowing the individual table styles to display the cell for each type differently in the same context. The cell templates are plain text files, ending in '.txt' and stored in the table style directory.

For example, a table style of 'options' stored in the templates path /usr/templates/ would be located at /usr/templates/tables/options/. If you had an item of type 'choice' to display in a given list, then the cell template for display of that particular item would be /usr/templates/tables/options/choice.txt. Notice that the path was created by stringing together the list-styles/template (/usr/templates)path, the table styles subdirectory (tables/), and the directory and path for the individual style and item type (options/choice.txt).

If you choose to construct a table style, take care to include all the required elements. Start and finish your cell templates with the <TD> and </TD> elements respectively. Start your header with <TABLE> and end it with </TABLE>. Remember that the Text::Merge::Lists methods will insert the <TR> and </TR> elements for rows containing your cell templates. Only use <TR> and </TR> in the header and footer files, and if you do be sure to use only one cell in each row and use the TableColumns field to assign the COLSPAN for that table. Observing these few things should keep your tables functional.

Table Style Features

Each table style has similar requirements for the files stored in the designated table style directory. The required files include a header, a footer, a filler template, a default cell template, and the optional template to use if the list is empty. The header, footer, and empty templates will all have access to the data of the calling template, in addition the header and footer templates will also have the additional field TableColumns set. Likewise, the filler template will have the FillerColumns field set, and that must be used to set the COLSPAN of the last table cell as described later.

Table Header Template

The table header is contained in a file named header.txt in the table style directory. This file must contain the <TABLE ...> element defintion. It may also contain full table rows to start off the table. Because table styles may be invoked with a variable column count, the field TableColumns is provided to use for a cell in these table rows, and while limited, it does allow the insertion of header rows. For example, this might be the contents of a common header.txt file:

        <TABLE BORDER=1>
                <TR NOSAVE><TD ALIGN=CENTER 
                        COLSPAN="REF:TableColumns"><B>Title</B></TD></TR>

Notice the REF:TableColumns portion of the code, which will be replaced with the number of columns in the table when the table is created. This allows for a "variable width" header that covers all columns.

The table footer is contained in a file named footer.txt and is very similar to the header.txt file described above. The footer.txt file must contain the </TABLE> element closing out the table. Before that element, any number of optional footer rows can be listed, and they too can use the TableColumns field to span the table columns as well. For example:

            <TR><TD COLSPAN="REF:TableColumns">This 
                        is the last table row.</TD></TR></TABLE>

Notice the REF:TableColumns field used in the the last cell definition, just as is done with the header rows. Also notice the </TABLE> listed at the very end. This basically closes out the table and is required. You can also include other HTML after this element if you wish, but it will not be included in the table itself.

Table Filler Template

The table filler cell is contained in a file named filler.txt in the table style directory. This is the template used for the last cell of a table to fill the empty spaces that may be left if the number of items in the list is not evenly divisible by the number of columns in the table. A field named FillerColumns is provided to this template and it must be used to specify the COLSPAN of the cell. This template, as with all other cell templates, must contain the <TD ...> and </TD> elements of the cell. This is a simple example filler cell template:

        <TD COLSPAN="REF:FillerColumns"><I>this is filler</I></TD>

The filler cell will be created with a single non-blocking space character (&nbsp;) as content if no filler.txt template file exists.

Item Type Cell Template

Each item in the list can be displayed based on its ItemType attribute if a cell template exists in the table style directory that is named with the item type followed by the '.txt' suffix. If such a template exists, it will be used to display the cell using the item data and actions. Every cell template must contain the <TD...>...</TD> elements to work properly in the table style.

Default Cell Template

The default cell template will be used if there is no cell template for the item type to be displayed. That is to say, if no file as described above exists for the item type in question, a file called 'default.txt' will be used to display the item. The 'default.txt' file is required if your table style definition is be robust.

Empty Table Template

The empty table template is used if the list exists but contains no items. The empty table template is contained in a file in the table style directory named 'empty.txt'. This template will have access to all the data and actions of the calling template. Note that if the 'empty.txt' template is used, then none of the other templates will be used for that table style and the results of processing 'empty.txt' will be the only thing displayed.

Methods

These are the methods that extend the basic functions of the Text::Merge object. Note that we overload convert_value() in order to insert our list style format recognition and interpretation. This is very elegant and easy to do.

new($liststyles)

This method constructs a Text::Merge::Lists object. It basically grabs a new Text::Merge object and then assigns the liststyles directory (which is required). If the template path is omitted, an the call is treated as a normal Text::Merge object request.

convert_value($dataref, $name, $style, $item)

This method catches list styles and handles them, otherwise the Text::Merge method is used.

set_max_nesting_depth($intval)

This method assigns the maximum nesting depth for lists. The default maximum depth is 3.

sort_method($methodstr, $listref)

This method returns the sorted list by processing the $methodstr for each item in the list. A common $methodstr might look something like:

        $method = 'REF:SomeField reverse numeric';

Which would perform a reverse numeric sort on the list. Basically a merge is performed on the $methodstr and the sort algorithm is sensitive to the keyword designators: reverse and numeric, which must appear at the end of the sort method string.

These must be items, where the data is contained in the 'Data' field. For instance:

        $item = { 'ItemType' => 'someitem',
                  'Data' => { 'field1' => 'val1',
                              'field2' => 'val2' } };

PREREQUISITES

This module inherits and extends the Text::Merge module by this author. This module was written and tested under perl 5.005 and runs with -Tw set and use strict.

AUTHOR

This software is released under the Perl Artistic License. Modify as you please, but please attribute releases and include all derived source code. (C) 1997, 1998, 1999, by Steven D. Harris, sharris@nullspace.com