Contents:
A web site generated with Thalassa CMS is almost entirely static (it can even be fully static if you don't use interactive features), and a static web site is essentially a directory tree with files. Some of these files are text, primarily the web pages themselves, represented with HTML; but your site can contain (and serve upon requests via the HTTP(S) protocol) binary files as well, and most of existing sites contain at least images (photos, pictograms and the like) represented as binaries.
The thalassa program can basically do three kind of things:
thalassa only makes them available within the web tree;For publishing existing files, not too many variants exist: you can instruct
thalassa to publish a single file (this is called
binary, but certainly you can publish a text file this way as
well) or to publish an entire directory (a collection). For a
“collection”, you can choose to publish subdirectories recursively or to
ignore them, to follow symlinks, ignore symlinks or make exactly the same
symlinks, to ignore “hidden” files (that is, files with names starting
with a dot “.”) or to publish them as well. Actually, it
doesn't seem a lot of other things can be invented for the purpose of
verbatim publishing (use the link to
learn more).
For text files' generation, there are a lot of different features, and it's
clear why: actually, that's what thalassa is made for.
The simplest thing you can do is just to generate a single stand-alone HTML
page, or even an arbitrary text file. BTW, we actively “abuse” this
feature to generate these .htaccess files for Apache;
sometimes we even generate configuration files for the
thalcgi.cgi program. Also it is relatively easy to make an
RSS feed (which is technically just an XML file) with what Thalassa is
capable of, and the stand-alone page facility fits this need the best.
A page (or, generally, a file) to
generate may be entirely defined by a single [page] section in
ini files, or you can create a
[template] section and then let several [page]
sections use it. The detailed description is found on the page devoted to
creating simple pages.
Besides that, thalassa features generation of arbitrary text
files outside of your web tree. This may be useful, e.g., to create
configuration files for some third-party software, using options and other
values defined in your ini files written for thalassa.
This feature is called genfile (for generic file), and is
configured with a [genfile] section. See the
generic files page for the description.
A more advanced approach to HTML pages generation is so called
page sets. In your source tree, a page set is
essentially a directory containing one object per each page you
want to generate; the object may be either a text file in the headed text format, or a directory containing
such a file (in this case, additional files, like images, may be added).
Within ini files, a set is defined by a [pageset] section; to
add more pages, you just place more files or directories into the set
source directory, and on the next run of the generator they all become
pages of your site.
It is useful to remember that sets as such are unordered. From the other hand, a set can serve as a source for a so-called list, or even for several lists.
The lists are perhaps the hardest-to-explain concept behind Thalassa, but they are extremely useful and, surprisingly, are in fact quite easy to use, once you understood what they are.
To start the explanation, let's say that a list is, well, a list — an
ordered list of items. Every item may (but not necessarily do) correspond
to a page to be generated; if this is the case, adding another item to your
list causes thalassa to generate one more HTML file, called
list item page (not to be confused with list pages). The
list item itself (in contrary to the item page) is (intended to
be) a relatively small piece of text, usually HTML.
List items (again, not to be confused with list item pages) can be put together in either direct or reverse order, thus forming, well, the list as such. You can choose to generate a single list page (and once again, not to be confused with list item pages), or an array of list pages, having your choosen amount of items per page. Furthermore, you can mark the list as embedded; in this case no list pages will be generated at all, and the list itself will be available wherever you want via a macro call.
If you need to understand better what is this all about, imagine a classic blog (not a microblog, it's important) or a news line. Every item, be it a blog entry or a news article, is represented both as its own page and as a short summary made for inclusion in various lists so that people can take a look and find the items interesting for them. These lists often tend to grow rapidly so a clear need arises to break the single very long list down to pages, showing a certain amount (say, 20 or the like) items per page. Such a blog or a news line is exactly what Thalassa lists are designed for (but they can be used for other purposes as well).
A list is defined by a [list ] section in the ini files, but
this is only the very beginning of the story, because such a section only
defines the list as a whole object, and one needs some way to define the
items as well. In the present version, there are two
possibilities.
First, you can introduce your own
section group in your ini
files for this purpose; for example, if you want to create a blog, the word
blog may serve as a good name for such a section group, so
individual entries in your blog will be defined by sections whose headers
have the form [blog ENTRY_ID], like
[blog 20230207_my_birthday],
[blog 20230401_fools] etc; well, actually you can have
any IDs you want, and they will turn into file names, like
20230207_my_birthday.html, 20230401_fools.html
and so on.
The second possibility is that you can use an existing page set, or any subset of it, as the source for your list; actually one page set can serve as a source for several different lists. Page sets are by their nature unordered, so using them as list sources involves additional files that explicitly enumerate page set items to be included into a particular list, in the order they should appear in the list.
Besides the main intended use (for blogs, news lines and other similar things), lists can be conveniently used for some other purposes. For instance, if you need to create some similar pages, but don't want to have a separate file for each of them (or, may be, you just want to use Thalassa macroprocessor in their source texts, which is impossible within headed text files used for page sets), you can use for this purpose a list with ini file sections as its source. List item pages will serve your need, while the list itself in this case is most probably unneeded. To suppress generation of the list pages (you don't confuse them with list item pages, do you?), the list may be declared “embedded”.
In contrast, lists that use page sets as their item sources usually don't have item pages, because pages are in fact already there — they get generated as pages of the page set. So, likely for such a list you'll need only the list itself, not item pages. However, Thalassa list facility allows even this: you can instruct it to generate for your list its own item pages, which may look different from those generated for the set.
One more interesting thing about lists is that a single source can serve more than one lists. For example, if you have a news line on your site, but it has its own page, not the main page of your site, then you might want to have something like “last news” list on the main page. This can be done easily just by creating another list on the same source as your news. And one more list for the same source can be used to generate an RSS feed (which is technically just an XML file) for your news.
As usual, see the page devoted to lists for more information.
If you don't need these bloody aliases, you can easily skip this section. This must be true if you are going to create a new site from scratch; we strongly recommend not to involve any aliases until you absolutely have to.
Aliases are used when a single HTML page (or other object served via
HTTP(S) from your site) for any reason should be accessible with more than
one local URI. For example, suppose you have a real (that is, existing)
file named foo/drink/drive.html within your web tree, so it
has a full URL like http://www.example.com/foo/drink/drive.html,
and (for any reason we don't want to know) you want it also to be
accessible as foo/smoke/fly.html, which means the full URL
http://www.example.com/foo/smoke/fly.html should return the
same content.
For a static site there are basically two approaches to achieve this. The
simpler one is just to create foo/smoke directory and put
there the appropriate symbolic link, which for this example would be named
fly.html and must point to ../drink/drive.html.
This is exactly what Thalassa CMS aliases do.
Objects configured for this purpose are known as “alias groups”; you can
have several of them, although more than one is rarely needed. An alias
group is defined by an [aliases ID] section in your
ini files. In the simplest case, such a section will have just one
parameter, which is also named aliases and contains a list of
pairs <alias + original>. For every pair, Thalassa will
compute the shortest possible symbolic link and create it.
Unfortunately, sometimes this is not sufficient to do what you need, specially when you're moving an existing and well-established site from a “traditional” CMS like Drupal or Joomla, and want to keep all your URIs working so that no links on third party sites get broken. Such sites are usually served in a fully-dynamic manner, which effectively means you don't have any real files nor directories there, hence your visible URIs are not bound by any filesystem-related reality. When there are no bounds, the so-called “webmasters” often create URI trees very difficult to reproduce with a filesystem path tree.
Suppose you need foo/smoke/fly.html to point to one (real)
document, and foo/smoke to point to another one.
Well, do your best to avoid such nonsense as long as you can.
However, if you really have no other choice, then the second approach to aliases has to be involved, and it is to instruct your HTTP server (e.g. Apache) to do some alchemy on URIs before actually serving the request.
It is possible to put an .htaccess file into your web root
directory and place there as many RewriteRules as you need to
fully match what is needed. Well, you can even generate this
.htaccess file as a stand-alone page, but
Thalassa will not help you to generate the appropriate “rules”, you'll
have to do it on your own. But you can end up with such an amount of
“rules” that you'll have to decide this is not the way to go.
What Thalassa can actually help is to try hybrid approach, using symbolic links as mush as possible and only leaving unresolvable cases to your HTTP server. In the example above, you can still add two pairs to your list of aliases:
foo/smoke/fly.html:foo/drink/drive.html
foo/smoke:foo/bur/buzz.html
— but, knowing perfectly this can't work, you can in the same
[aliases ] section specify explicitly that
foo/smoke contains other links and hence has to be a real
directory, not a symbolic link. After that you can also instruct Thalassa to
generate a file inside each of such directories, set the name for the file,
and specify a template for its content, where a local macro will be
substituted with the target URI (taken from the list). Most probably the
name will be .htaccess, and the file will contain the
appropriate redirect directive.
Detailed instructions are found at the page devoted to aliases. If you really need them, well, we wish you good luck.
Additional objects are something which is not generated as separate files within your site's tree; instead, they are certain pieces of HTML code inserted here and there in your generated files.
Of what we have discussed already, embedded lists make a good example of additional objects. Besides that, Thalassa supports blocks, menus, index bars and user comment sections.
Block is simply an HTML code snippet; it doesn't even have to look like a “block”; in most cases it does, but generally it may be anything you want. Every block belongs to a block group, and each block group is a thing accessible via a macro call. The idea behind a block group is to represent something you want to appear on all (or many) of your pages, like a side panel, bottom or even something within or near the header of every page. Each block may have an associated tag, and the macro which generates a block group accepts an additional argument, allowing to pass a list of tags; a particular block will appear on the particular page (within the group) either if the block has no tag (which effectively means “show me everywhere”), or its tag is found in the set passed to the macro, or among the tags the page itself has. See the blocks and block groups page for more info.
Menu is effectively a list of links you want to appear in more than one place of your site (up to the case of every page). This could be achieved by already existing instruments, e.g., embedded lists, blocks or even simply html snippets, but there's one property specific for menus: if a menu is displayed on a page to which one of its items points, that particular item should be displayed differently (e.g., “disabled”). Menus provided by Thalassa involve associating a label with every menu item, and the macro, which generates the menu, also accepts a label as its argument; if the label matches, the corresponding menu item is displayed using alternative template. More information, including detailed instructions, is provided at the page devoted to menus.
Index bars are used for arrays of pages, which means there are several automatically generated pages, ordered and, more importantly, numbered. In the present version of Thalassa, there are exactly two cases of such arrays:
Appearance of index bars is configurable, and the result if available by calling a macro. For details, see the page devoted to index bars.
The last type of an “additional object” is a user comment section. Only list item pages and page set items may have comments; stand-alone pages in the present version of Thalassa are not suitable for publishing comments. In contrast with all the other types of additional objects, comment sections are not available through macro calls; instead, templates for pages suitable for comments are broken down to two parts, first for the page itself, and the second for the “page tail”; the comment section, if it exists, is placed between the page segments expanded from those template parts. Additional pages (with the same content, but containing other portions of the comments) are generated automatically, as appropriate.
Comments are configured by comment style ini file sections; page lists and page sets support configurable parameters to reference one of the existing configured styles and to set some additional options. Detailed description is on the page devoted to comment sections.