Contents:

• List basics
• The [list ] ini file sections
• List source configuration
• General parameters
• Appearance of list pages
• Generation of list item pages
• Lists of items defined by ini file sections
• The %[ls: ] macro
• The %[li: ] macro
• The %[listinfo: ] macro

List basics

First things first. Relatively detailed introduction to lists is given in our review of objects Thalassa can generate. Make sure you read it beforehand. We'll assume you already understand what lists are and what they are for.

Let's recall that list, as Thalassa object, consists of items, placed in some order. Every item is, basically, a piece of text, but, besides of that, a separate html page can be generated for each item of the list. These pages are calles “list item pages”; they can even have comment sections, which means several physical HTML files may appear for a single list item. However, generation of item pages may be turned off for a particular list.

Normally, one or more pages will be generated to display items of the list, one by one; macros are provided to build obvious navigation in such a page array. These pages are called list pages and they are not to be confused with list item pages: obviously, list item pages are generated (unless disabled) one per item, while list pages contain items. Typically, for the case when both list pages and list item pages are generated, every item has a shorter version (description, or teaser) for inclusion in the list pages, and a longer version (full text) used for the item page.

List pages generation can be disabled for a particular list as well. A list that has no list pages is called embedded list; it is generated during expansion of a macro call %[embedlist:NAME] (where NAME is the list ID).

For every list, there must be a place the items actually come from. It is called list source. There are two possibilities:

• a section group placed in one of your ini files can serve as a list source;
• a page set or a certain part of it can become a list source with a help of an additional file, in which the set items that form the list are enumerated.

A single list source can serve several lists, should this is needed for some reason.

List item pages, in case they are generated, can have their own comment sections. This, as well as list item pages theirselves, is mostly useful for lists that use section groups as their source, because pages from page sets can have comments on their own, without any help from lists.

The [list ] ini file sections

Lists are defined with ini file sections of the list group, e.g.

  [list news]

The section name (news in this example) identifies the list as a whole and serves as a default for some parameters.

List source configuration

The source parameter determines what will be used as the source for the list items. The value consists of two or three words, delimited by any amount of whitespace; the first word must be either ini, meaning the items will be taken from a designated section group in one of your ini files, or set, meaning a page set will act as the list source.

For ini, there must be the second word which indicates the section group name. For example,

  [list crocodiles]
  src = ini croco

means the items will be taken from sections [croco gavial], [croco saltwater], [croco caiman] and the like.

For set, two additional words must be given, the first for the name of the page set (exactly as in the respective pageset section head), and the second for the so-called tag. Please note that in the present version of Thalassa the tag has nothing to do with the tags: header field (although such a connection may appear in the future). What the tag determines is the name of the file that enumerates the list of page set item IDs, thus turning an (unordered) page set into an ordered list. The name of the file is computed by prepending an underscore “_” to the tag. Hence,

  [list dogbreeds]
  src = set dogs breeds

means the page set defined by [pageset dogs] section will be used as the item source, and a file named _breeds, containing the actual list of set IDs, is expected to exist within the set source directory.

For example, in your page set source directory for the set named dogs you can create headed text files named, e.g., terrier, spaniel, shepherd, pointer, beagle, rottweiler and the like, and along them place a file named _breeds containing something like this:

  beagle
  pointer
  rottweiler
  shepherd
  spaniel
  terrier

General parameters

The reverse parameter specifies if the items should be placed in the native (same as in the source) or reverse order. The value should be “yes” or “no”; “no” is the default, and, actually, anything not equal to “yes” is considered “no”.

The reverse_source parameter allows to declare that the items in the source are placed in reverse order. The value must be “yes” or “no”; in fact, “yes” is the only one that makes sense, otherwise the parameter should perhaps be simply omitted.

If you change both reverse and reverse_source to their opposite values, your resulting order of items will remain the same; impression can occur that it is senseless to have both parameters, but such impression is wrong because of the next parameter, named last_items_only.

The last_items_only parameter's value, if specified, must be an integral number; Thalassa will only handle that many last items of the list, completely ignoring all the rest. This is useful for creating lists like latest news, last added photos etc., specially if it is an additional list based on the same source with a “main” list (like, may be, “news” or “photos”).

The embedded parameter declares the list to be embedded; technically this means Thalassa will not generate list pages for it. The list will be generated as a result for a call to embedlist macro, like %[embedlist:latestnews].

The aux_params parameter only makes sense for ini-sourced lists; its value is a comma-separated list of additional parameters to be extracted from each item's ini section. These parameters are accessible by calling %[li:hf:NAME] (see the hf function of the li macro).

Appearance of list pages

For both list pages and HTML code returned by the embedlist macro (for embedded lists), the actual content is controlled by the same set of parameters: list_header, list_footer and list_item_template.

The list_header and list_footer define what to place at the head and at the tail of every list page, that is, before the list items and after them. For embedded lists, these parameters define how to start and how to end the HTML fragment returned by the embedlist macro; for example, you can use them to start (and to end) a numbered/unnumbered list, or a table, or whatever HTML construction you like.

The list_item_template parameter defines how each list item is generated. For example, a very basic embedded list may be configured as follows:

  [list lastnews]
  embedded = yes
  last_items_only = 15
  source = ini news
  reverse = yes
  list_header = <ul>
  list_footer = </ul>
  list_item_template = <li><a href="/news/%li:id%.html">%li:title%</a>
  +   %li:descr%</li>
  pages = no

The items_per_listpage parameter sets the number of items to display per page; the value must be a non-negative integer, 0 (the default) means to display the whole list on a single page. This parameter, as well as the following two, are ignored for embedded lists.

Names of the files to be generated as list pages are set with main_listpage_name and listpage_name_templ parameters. The main_listpage_name parameter parameter's value is simply a file name, relative to your site's tree root, for the “main” page of the list (containing first items for a normal-order list, last items for a reverse list). The listpage_name_templ parameter sets a template for names of additional pages, in which index macros (%idx%, %_idx% and %idx0%) are expanded. In case main_listpage_name is omitted, listpage_name_templ is used for the main (zeroth) page as well.

Generation of list item pages

List item pages (once again, not to be confused with list pages) are enabled by setting the pages parameter to “yes”. Any other value, as well as omitted parameter, are considered equal to “no”, which means not to generate the pages.

File names for the item pages are controlled with the itempage_name parameter, whose value is effectively a template in which index macros are available. The index macros are only used in case the page to be generated contains a comment section and there are so many comments that more than one physical page is to be generated.

The actual content of list item pages is controlled by two parameters: itempage_template and itempage_tail_template. Their values are passed through the macroprocessor; then, the generator concatenates the processing result for page_template, the comment section (if it exists for the page being generated) and the processing result of page_tail_template.

The comments parameter sets the comment sections style, the path to the comment tree (the part of the “database” that holds comments for the particular page) and some additional parameters available in comment-related templates by macro calls. This parameter is closely discussed along with comment sections. By default this parameter's value is empty, which means no comment section to be generated.

For list item pages that, because of comments, are generated in more than one instance, comment map files need to be generated, just like for page set items (use the link for the discussion). The commentmap parameter is used to set the comment map file name.

Lists of items defined by ini file sections

In case your list is configured to use ini sections as a source, e.g.,

  [list mylst]
  source = ini myitem

— effectively this means you defined a custom section group; in this example it is named “myitem”, so it can have sections with heads [myitem foo], [myitem bar], [myitem bad.example], [myitem 237] and the like, each representing an item of the list. From every such section Thalassa expects certain parameters to be defined, and additional parameters may be given as well.

Actually, the parameters Thalassa always expects from every list item don't depend on your choice of source. Having said this and recalling that the only alternative to ini sections is page set items, we'll be well-prepared to the fact that some of parameters in an ini file section representing a list item play exactly the same role as header fields in a page set item source file. These parameters are:

• unixtime (the date and time as a number of seconds “since Epoch”),
• date (the date in a human-readable form),
• title (the title, or, if you like so, subject),
• descr (description, or a teaser — a shorter version of the text for inclusion in lists),
• comments (the comments mode for the item page if one exists; may be one of enabled, disabled or readonly),
• tags (the list of tags).

Please note there's no parameter resembling that teaser_len field of page set items. For ini-based list items, there's only one way to set the description/teaser — with the descr parameter.

Values of these parameters are available via the accordingly-named functions of the li macro. The same is true for the text function of the same macro: for ini-based list items, %[li:text] returns the text parameter's value. This means that the text parameter plays a very important role: the main text, which is taken from the source file's body for set-based list items, in ini-based lists is taken from this parameter.

Thalassa doesn't recognize any other parameters of list item sections on its own, but you can declare more parameters for your particular list using the aux_params parameter in the [list ] section.

The %[ls: ] macro

The ls macro provides access to list properties. In the present version, only a few functions are available with this macro:

• %[ls:id] is the list ID (the name of the [list ] section);
• %[ls:srctype] returns either ini, or set, according to the source type configured for the current list;
• %[ls:srcname] (or just %[ls:name]) is the source name, that is, the second word from the source parameter;
• %[ls:tag] only makes sense for set-based lists; returns the tag value (the third word of the source parameter);
• %[ls:first] and %[ls:last] return the item IDs for the first and the last item of the list, respectively; for an empty list, the functions return an empty string.

The %[li: ] macro

The %[li: ] macro provides access to list item properties. We already introduced it as a part of the discussion related to page sets; in particular, we explained the following functions of the li macro: title, unixtime, date, descr, tags, hf, ifcomenabled and iffile. Be sure to use the link above to read that text if you didn't do that already.

Besides the functions we already discussed, there's a handful of li macro functions that are hard to explain without list-related background; we postponed the discussion on these functions until a better moment, and now the time comes.

The iflong and ifmore functions are conditional checkers; they both take two arguments: the then value and the else value, and return the former in case the condition is true and the latter if it is false. For iflong, the condition is simple: whether the list item text is not empty. For ini-based lists, the text will be empty if the text parameter of the item section is omitted or left blank, and for set-based lists, the text will be empty if in the item source file, only the header is given and there's no body. For ifmore, the condition is whether the text is longer than the teaser (description). This doesn't make much sense for ini-based lists (although still can be used), but for set-based lists, in case you use the teaser_len header field, the ifmore function allows to check whether the item is fully displayed in the list, or the reader must go to the item page to read its full text. It is useful for adding, as needed, links like read more, click for more and so on.

The prev and next functions return list item IDs for the previous item of the list and for the next one accordingly. If there's no previous/next item, an empty string is returned. The tricky matter here is that sometimes these two functions accept an additional argument, which must be the list ID, but sometimes they don't. Well, the trick is simple: the functions need to know which particular list they are called for, and within a page set context they can't know that for sure until the list is explicitly specified. Indeed, a particular page set can have more that one list files, and these files may introduce different order for the same items. So, if you use %[li:prev: ] and %[li:next: ] in parameter values of a [pageset ] section, you must specify the list ID explicitly. When the two functions are used within a [list ] section (or even a list item section, which is possible but not normally needed), any extra arguments are ignored.

The ifprev and ifnext functions take exactly three arguments: the list ID, the then value and the else value. If the previous/next item in the list exists, the then value is returned, otherwise the else value is returned. The list ID is only used in a page set context (that is, within a [pageset ] section); within a [list ] section, as well as list item sections, it is ignored and should be left empty.

The listarraynum function only makes sense for lists that span on more than one page; the function returns a 1-based decimal number that corresponds to the index of the list page on which the (current) item is displayed. The function is useful to make links from list item pages back to the corresponding list pages. The function returns an empty string if there's no number to return, e.g., the list is not multipage, or the item doesn't actually belong to the list. In the page set context, the function accepts the list ID as its argument; for ini-based lists, the argument is ignored and should be omitted.

The iflistarraynum function is a conditional checker intended to be used together with listarraynum; it accepts exactly three arguments: the list ID, the then value and the else value. In case listarraynum would return a non-empty value, iflistarraynum returns its then value, otherwise the else value is returned. The list ID is only used in a page set context; within a [list ] section, as well as list item sections, it is ignored and should be left empty.

In the present version of Thalassa, there are also listidx and iflistidx functions, but their usefulness is doubtful and they can be removed from the future versions. Let's leave them undocumented for now.

The %[listinfo: ] macro

The %[listinfo: ] macro allows to retrieve some information about a list from outside of the list, that is, when you are not generating the list or any of its parts. Unlike the ls macro, the listinfo macro accepts the list ID as its second argument (while the first argument must be the name of the desired function).

In the present version, only two functions, first and last, are supported. The calls %[listinfo:first:ID] and %[listinfo:last:ID] expand to the item IDs of the first and the last item for the given list, respectively.