Contents:

• What blocks and block groups are and what they are for
• The [blockgroup ] section
• The [block ] section
• The %[blocks: ] macro

What blocks and block groups are and what they are for

When a site has a lot of pages, there almost always are some little things you want to display on every page, like a common header, and actually that's what static generators are all about. With Thalassa, this is achieved easily because all pages are generated using a limited number of templates, and, furthermore, these templates, despite they may differ, may be (and usually are) built on common HTML snippets. So, it is easy to insert some content into all your pages.

Things become a little more complicated when you've got some content to display on many pages but not on all of them. This is what blocks are for.

First of all, define one or more block groups, each one corresponding to a place in your page layout where you want some common pieces of content to appear. For example, you can define a group for your side panel (well, should you have both left and right side panels on your site, you'll need two block groups, but you don't have two side panels, do you?), another group for your ceiling, one more group to have some microblocks within your site's header — well, you've got the idea. Technically a block group is a named object that consists of three templates: for the begin and the end of the code that displays the group, and for blocks themselves.

Once your groups are ready, insert them into your templates that define layout of your pages; this is done by calling the %[blocks: ] macro.

The next step is to define your blocks. Each block has a name, consists of a title and a body, and may also have a tag; you can assign weight values to your blocks to arrange them within their block group (the more the weight is, the later that block appears within its group).

Finally, take care about what blocks appear on each of your pages. If a block has no tag, it will appear in every existing instance of the group it belongs to. If the tag is set, the block will only appear on pages where this tag is either specified for the page itself (by the tags: header field of a page set item source, or by the tags parameter within a list item ini section), or given in the third argument passed to the %[blocks: ] macro call.

The [blockgroup ] section

Block groups are defined by ini file sections of the blockgroup section group, with section headers like

  [blockgroup NAME]

— where NAME is the block group name. The name is used in block definitions to bind blocks to groups, and as the second argument in %[blocks: ] macro calls to identify the group.

Three parameters are recognized within these sections:

• begin — defines the HTML code snippet that starts the block group;
• end — defines the HTML code snippet that ends the block group;
• block_template — defines the template used to generate HTML code for every block in the group.

All parameters are passed through the macroprocessor; within the block_template parameter's value, an additional macro named blk is available to provide access to the title and the body of the block being generated. In the present version of Thalassa this macro has four functions:

• %[blk:title] returns the block's title;
• %[blk:body] is replaced with the block's body;
• %[blk:id] returns the block's ID (the name of the corresponding [block ] section);
• %[blk:tag] returns the tag set for the block, or empty string if the block has no tag.

The [block ] section

Ini file sections of the block section group are used to define individual blocks; so, a block definition starts with a header of the form

  [block ID]

Be sure to give each block a distinct ID. Being distinct is in fact the only role for these IDs; they can be accessed from within the block_template parameter of the corresponding blockgroup ini section, but it is not necessary to use them this way, and there are no other ways at all.

The following parameters are recognized:

• title — the title of the block (the text to be returned by %[blk:title]);
• body — the body of the block (the text to be returned by %[blk:body]);
• group — the name of the block group this block is to belong to;
• tag — the tag; may be omitted or left empty, which means the block will be displayed in all instances of its group;
• weight — the integral number (negatives are okay), which determines the position of the block within its group (the more the weight is, the later the block appears).

Only the values of title and body are passed through the macroprocessor; the rest of the parameters aren't.

The %[blocks: ] macro

The %[blocks: ] macro is intended to be used within templates that form your pages' layout. The macro accepts two arguments; first of them is the name of the block group to be displayed, and the second is a comma-separated list of tags, possibly empty.

Being called, the macro composes the requested block group and returns the resulting HTML code. Each block of these belonging to the given group is displayed if either its tag is empty, or it is found in the list passed as the third parameter, or the macro is being called from within a context where a list item is available (that is, the page being generated is either a page set item, or a list item page for an ini-sourced list), and the block's tag is in the list item's array of tags.