Thalassa CMS logo

Thalassa CMS

Comment sections


Introductory stuff

We already mentioned comment sections along with page set items and list item pages; those two are the only two kinds of pages generated by Thalassa that can have comments. Please use the two links, specially the former, to refresh your impressions.

It is essential to know that Thalassa stores comments for a particular page in a separate directory, where each comment is represented as a headed text file. Comments written in response to other comments store their parent comments' IDs, so logically comments for a page form a forest of trees, each tree having a root comment which was posted as a response for the original page content as such (not as a response to another comment). However, Thalassa is able to display comments both as a tree and as a flat sequence.

From the thalassa program's point of view, comments are just one kind of content to be converted to HTML. Typically, they are created, edited, deleted and otherwise handled with the Thalassa CGI program (thalcgi.cgi) using web-based interface, but it is certainly possible to manage them manually, by creating, editing and deleting the files.

How comments are stored

Comments for a page are stored in a separate directory as headed text files. Every comment has its numeric ID, starting with 1 (zero is a reserved value). In the present version of Thalassa, there's a hardcoded limit of 50'000 comments for a single page (within a single directory); if this eventually becomes a problem for you, please contact the author (well, I've never seen more than 3000 comments for a single article or post). File names for comments normally consist of four digits, that is, 0001, 0002, 0237 etc. In (highly unlikely) case there are more than 9999 comments in a directory, the files for comments with IDs exceeding 9999 will be named according to their IDs without leading zeroes, like 13476.

In every comment-storing directory there's also a file named _hints; despite its name, which is plural, in the present version it only stores one number: the maximum numerical ID of the existing comments. The file is advisory in the sense that if it is lost, corrupted or even just outdated, this will cause no failure: Thalassa CGI program always uses the O_EXCL flag when it creates new comment files, so if, despite the hint, a file with the supposed next free ID already exists, Thalassa CGI will try subsequent numbers, one by one. The only case when inconsistent value of the “hint” can cause a problem is when it is actually higher than the maximal ID of an existing comment, but this can't happen in the course of normal operations (although one can create this situation by manually editing the file).

The set of header fields recognized by Thalassa in comment files is slightly different from that of page set items. First of all, the fields encoding: and format: are used exclusively by the parser and aren't accessible from Thalassa templates. The id: field is handled in special manner; actually, in the present version the comment ID is fully determined by its file name, and is the number, but with no leading zeroes (e.g., for a file named 0021, the comment ID will be 21). In future versions a check for correctness of the id: header field may be implemented, so be prepared to that.

Besides these three, Thalassa recognizes the following header fields in comment files: parent, unixtime, user, flags, date, from and title. You can add any other fields if you need. The fields parent, unixtime, user and flags are not passed through any converters; all the other fields, including any custom fields added by the user, are passed through the encoding converter if necessary. None of the header fields are passed through the format converter, only the body is.

The recognized header fields are supposed to contain the following:

Styling comment sections

There are different ways for visualizing a set of comments. They can be displayed as a flat sequence, one by one, with replies having some kind of reference to their parent comments; they can also be displayed as a tree, with replies right under their parents, indented to show the parent-child relationship. All comments may be placed on a single physical page, or on a sequence of pages, each holding a number of comments up to a certain maximum value. The comments may be displayed in the native order as well as in the reverse order. The last but not least, whatever approach you choose, it still needs to be implemented as HTML code, and there are a lot of choices on this step, too.

In Thalassa, a particular way of comment section generation is configured with an ini section [commentstyle ID]. Within ini sections of this group, the following parameters are recognized:

The cmt macro is available within the templates to provide access to the comment's properties and some additional data.

Comment display configuration

Ini sections of both [pageset ] and [list ] groups can have the comments parameter, which defines where to get the comments from and how to display them.

The value of this parameter may be (and usually is) a multiline text. The first line must consist of two words: the first word (of the first line) is the comment style, that is, the name of the desired [commentstyle ] section, and the second word is the comment directory path (usually a template). Additional lines form a dictionary, the first word being the key, and the rest of the line (leading and trailing whitespace stripped) being the value; these values are available within comment templates through the cmt macro with its aux function. This makes it possible to use a single set of macros for different comment 'realms'.

For example, the comments parameter may look as follows:

  comments = tree1 db/comments/page%[li:id]
      cgi_reply_path  /thalcgi.cgi/comment/page/%[li:id]/
      cgi_view_path   /thalcgi.cgi/cmta/page/%[li:id]/

The %[cmt: ] macro

The %[cmt: ] macro is available within comment style templates to provide access to comments' properties and some additional data. The macro accepts one or more arguments, first of them being the function name; e.g., %[cmt:title] expands to the current comment's title. The following functions are supported:

© Andrey V. Stolyarov, 2023, 2024