Menus

Menu is effectively a list of web links, in which one item may be current and therefore to be displayed differently, usually in different color and without the active link. In Thalassa, this is achieved with so-called labels. Each menu item has an associated label, and the current label is passed as an argument to the macro that builds the menu, so it can handle the item with the same label in a way other than for all the other items.

Menus are configured with ini file sections of the menu group, headed like this:

  [menu NAME]

— where NAME is a distinct identifier you'll use to reference the menu. The menu itself is defined by the items parameter's value. The first non-whitespace char in the value is used as the field delimiter; every menu item occupies four fields: the first defines the menu item's text, the second is the link (as it will appear in the a href attribute), the third is assumed to be the value for the title attribute of the link (typically it is displayed as a tooltip when the user points the mouse to the menu item), and the last (fourth) is the label. For example, your menu definition might look like this:

  [menu topmenu]
  items =
    | News      | /news.html     | The site's news feed | pg.news
    | Docs      | /docs.html     | Documentation        | pg.docs
    | Books     | /books.html    | Books on topic       | pg.books
    | Download  | /download.html | Files to download    | pg.download
    | FAQ       | /faq.html      | Frequently asked questions | pg.faq
    | Feedback  | /thalcgi.cgi/email
                   | Send a message to the site's owner | feedback
    | Guestbook | /guestbook     | The guestbook        | guestbook

For every field, all leading and trailing whitespace is stripped off.

There are two special cases. If the second field (the link) is left empty, but the first (the item's text) is not empty, such item defines a tag, that is, a piece of text inserted into the menu for descriptive purposes. Tag is not intended to be a link, to become a current item etc., it is there for informational purposes only, not as a navigation element. If both the first and the second fields are left empty, this means a break, which may appear as an additional space between items, or as a rule between them, or the like.

For tags and breaks, the third and fouth fields (the tooltip and the label) are typically ignored and should be left empty (but make sure they actually still there, meaning that exactly four field delimiter chars are there for each item). However, they are still passed to the macroprocessor just like for link items, so in theory you can use them for your own purposes.

Besides the items parameter, a menu ini section should contain the following parameter:

begin — defines the HTML code snippet that starts the menu;
end — defines the HTML code snippet that ends the menu;
link — template used to display menu items in their normal (active) state;
curpos — template used to display the current (disabled) menu item;
tag — template used to display tag items (the items for which the link field is left empty;
break — template used to form a break (empty space or the like).

Within the link, curpos, tag and break parameters' values, positional macros are available to access properties of the menu item being processed: %0% expands to the item's text, %1% expands to the link, and %2% expands to the title text.

The %3% macro call expands to the label field just as you could expect, but you shouldn't need this; if you think you do, perhaps you're doing something wrong.

For example, your menu can be configured as follows:

  begin = <ul class="menu">
  end = </ul>
  link = <li><a href="%1%" %[if:%2%:title=%[q:%2%]:]
                class="menu_link">%0%</a></li>
  curpos = <li><span class="menu_curr">%0%</span></li>
  tag = <li><span class="menu_tag">%0%</span></li>
  break =

In this example, break items, if any, will have no effect; actually we can't have breaks within <ul> correctly. This is though not the only possible approach to menu rendering, and if you use something different, like a sequence of paragraphs, or of strings enclosed in smth. like <span>, or even of table cells, there are lots of ways to implement a break there.

Refer to various CSS manuals on how to define these menu, menu_link and menu_curr classes properly.

Menus are inserted into your pages by calling the menu macro, which accepts two arguments: the menu ID and the label. If the page you compose doesn't correspond to any of the menu items, the second argument should be left blank.

For the example above, it is natural to assume that pages news.html, docs.html, books.html, download.html and faq.html are generated as page set items, with pg being the set ID and news, docs, books, download and faq being the item IDs; at the same time, the pages corresponding to the feedback form and to the guestbook are created in some other manner. In this setting, the macro call within the pg's page template might look like this:

  %[menu:topmenu:pg.%[li:id]]

If we suppose that the guestbook page is created as a list item page (please note it can't be a stand-alone page because stand-alone pages can't have comment sections, which is obviously needed for the guestbook), in its template the macro should be called as follows:

  %[menu:topmenu:guestbook]

The “Feedback” page in our example looks like a page provided by the CGI part of Thalassa. Displaying menus from the main configuration on such a page is tricky, it requires to generate the CGI program configuration file as a “stand-alone page”. We won't discuss it here.

Thalassa CMS

Menus