FIXME

Using the layout handler to define colors everywhere in your skins makes changing the appearance of your site according to the four seasons a piece of cake. Use the following macros to refer to the color values as set in your layout preferences:

<% layout.bgcolor %>
<% layout.textcolor %>
<% layout.titlecolor %>
<% layout.linkcolor %>
<% layout.alinkcolor %>
<% layout.vlinkcolor %>
<% layout.smallcolor %>

please note that you do not have to care about whether the color value is a string or a hexadecimal number. antville will add a hash (#) whenever it is necessary.

not enough, there are macros for fonts and font sizes, too. every font definition in the preferences can be expressed by an appropriate macro:

<% layout.textfont %>
<% layout.textsize %>
<% layout.titlefont %>
<% layout.titlesize %>
<% layout.smallfont %>
<% layout.smallsize %>

certainly, you have to include the color and font macros at the right place, ie. inside a valid html tag or a correct cascading style sheet definition.

This macro displays a link to the comments's reply form. To override the default action the "to" parameter can be set, e.g. if you want to provide the reply form directly below the comment:

<% comment.replylink to="#replies" %>

The "text" parameter is available to set a custom link text:

<% comment.replylink text="place your reply" %>

Depending on where you use this macro (by default it is used in the full story skin and in the toplevel comment skin) it will loop over the toplevel comments of a story or the replies to a comment.

For displaying the comments this macro will use two different skins: toplevel and reply. You can find them in the skin editor of your weblog in the section "comments".

this macro creates a "breadcrumb-navigation" based on the requested page (if you are curious about what this might look like click on topics and have a look at the top of the page).

to define a different separator between the items (the default is >) use the attribute "separator" like this:

<% linkedpath separator=" | " %>

This macro can be used to display the topic a story belongs to: either as text, link or image. As a minimum you need the following:

<% story.topic %>

This will display the name of the topic as link to the main page of the topic.

<% story.topic as="text" %>

will display the name of the topic just as plain text. Now using the attribute as="image" is a bit more complex:

<% story.topic as="image" %>

What will happen now? Assuming you have a story that belongs to the topic "topicmaps", Antville will search in the imagepool of your weblog for an image with the name "topic_topicmaps". The prefix "topic_" is added by default, but you can customize this too:

<% story.topic as="image" imgprefix="icon_" %>

Antville will then search for an image named "icon_topicmaps". If it finds one it will display it as link to the main page of the topic.

This macro renders by default a link to the form for adding a new comment.

<% story.commentlink %>

Now this might appear a bit useless since you could also use the link-macro to do the same:

<% story.link to="comment" %>

The main reason for this special macro is that it checks if comments are enabled for a story or not: if comments are disabled it won't display anything. There are two attributes for customizing the result:

<% story.commentlink to="comment" text="place your comment!" %>

to means the page this macro should link to, and text defines what should appear as link. The above example shows the defaults (so you can omit them if that's what you want).

Another macro that can be used for quite a lot of items:

<% story.url %>
<% comment.url %>
<% site.url %>
<% image.url %>
<% file.url %>

The result of these macros is - surprise! - the url to the story, comment, site, image or file.

Additionally, you can use the "action" parameter to append a specific action name after the url:

<% site.url action="referrers" %>

The creator-macro can be used for nearly every asset in Antville: stories, comments, images, files, polls and shortcuts. The usage is always the same (the following example shows the usage for stories):

<% story.creator %>

will display the name of the creator of a story. If you want the name appear as link to the personal URL the user has specified in the profile use the following:

<% story.creator as="link" %>

Now try this:
<% story.creator as="link" prefix="this story was created by " %><% story.modifier as="link" prefix" and modified by" %>

This macro is also available as <% comment.content %>.

Now this is probably one of the most interesting (and flexible) macros of Antville. Using this macro you can not only display story- or comment-content but also customize the basic structure of stories and comments in your weblog! But let's start with the basics (the following examples show you the usage for both stories and comments):

<% story.content part="title" %>

will display the title of a story - if it has one. Normally nothing would be displayed, but if you use the fallback-attribute you can tell Antville what content-part it should use if no title is available:

<% story.content part="title" fallback="text" %>

This would display the text of the story or comment if it doesn't have a title. If you want to display just the first part of the text you can also do that:

<% story.content part="title" fallback="text" limit="20" %>

will use the text of the story, but display it only 'til the first whitespace after the 20th character (neat, innit? ;-) Additionally the desired part can also link to the main page of the story (this only works with stories as comments do not have a main page!), eg.

<% story.content part="title" fallback="text" limit="20" as="link" %>

will render the title (or the text limited to around 20 characters) as a link to the main page of the story.

Customizing the structure of stories and comments

Let's assume you need stories that not only consist of a title and a text, but you also need a lead-text that should be displayed in all storylists (eg. the frontpage of your weblog, the frontpage of a single day and the main page of a topic).

All you have to do is to modify the skin for editing/creating a new story (you can find it in the "advanced" skins of the skinmanager). Simply add the following to the skin:

<% story.content part="lead" as="editor" cols="30" rows="5" wrap="virtual" %>

Now what will happen? Antville will display a new textarea in the form, and in the moment you save the first story with a lead-text it will be stored. To display it simply edit eg. the story-"preview" skin and use the content-macro again, this time slightly different:

<% story.content part="lead" fallback="text" %>

This will display the lead-text of a story if available, otherwise display the whole text of it. Got the idea? But we're not finished 'til now:

<% story.content part="image" as="editor" %>
and
<% story.content part="image" as="image" linkto="main" %>

will do something else: the first macro - if embedded in the skin for creating/editing a story - will render a simple text-inputfield where you could type in the name of an image out of the imagepool. The second macro will read the name of the image, look in the imagepool if there is an image with this name and - if found - display it as a link to the main page of the story.

This macro takes a defineable number of images out of the image pool (beginning with the latest one) and displays them as a list, where each item either appears as fullsize-image or thumbnail (which itselft can link to the fullsize-image either in the same browser window or in a popup). To choose what the macro should display use the attribute as

<% imagelist as="popup" %>
or
<% imagelist as="thumbnail" %>

Omitting as will result in a list of fullsize images. If you choose "popup" or "thumbnail" and one of the images in the imagepool doesn't contain a thumbnail (i.e. because the image-width is smaller than 100px) the macro will ignore the image and proceed with the next one having a thumbnail. Similar to the ubiquitous macro-attributes "prefix" and "suffix" you can also define itemprefix and itemsuffix which will be places before and after each image in the list.

<% imagelist as="popup" itemsuffix="<br />" %>

You can also use the attribute linkto which will force the macro to link every item to the URL you specified. And of course you can limit the number of items:

<% imagelist limit="1" prefix="this is my newest one:" linkto="http://myfirstweblog.com" %>

This macro displays all topics of your weblog as links to themselves. Besides the ubiquitous macro-attributes "prefix" and "suffix" you can also define itemprefix and itemsuffix that will be placed before and after each topic. So it's easy to generate an unordered list of topics:

<ul>
<% topiclist itemprefix="<li>" itemsuffix="</li>" %>
</ul>

This macro displays the archive of your weblog as a list of months. Every item will appear as link to the first story of the appropriate month. By using the attribute format you can change the appearance of the items, eg.

<% site.monthlist format="MMMM yyyy" %>

This will give you each month as "April 2002", "May 2002" (this is the default formatting). The language used by this macro is depending on the language you defined in the preferences of your weblog.

Besides the ubiquitous macro-attributes "prefix" and "suffix" you can define "itemprefix" and "itemsuffix" which are placed before and after each item, so you can eg. construct a typical unordered html-list:

<ul>
<% site.monthlist itemprefix="<li>" itemsuffix="</li>" %>
</ul>

With the last optional attribute, limit, you can define the number of months that should appear in your list.

Of course this macro will only display anything if the weblog contains at least one story (which is online) plus the archive is enabled in the preferences.

(a.k.a. "recently modified"-list) This macro displays a defineable number of stories and comments that have changed in the recent history of your weblog. To change the number of items in the list use the option "show", eg.:

<% site.history limit="10" %>

will give you a list of the 10 most recent modified stories or comments of your weblog.

This macro calculates the number of days that have passed by since a weblog was created (it doesn't matter how long the weblog has been offline).

displays just a calendar. nothing more? well ... yes, nothing more :-)

Please don't forget that this macro will only display a calendar if your weblog contains at least one story that is online AND you enabled the archive in its preferences. The calendar will also change its language depending on what you defined in the preferences, and it also will change the first day of the week.

To change the outfit of the calendar in your weblog have a look at the section "calendar" in the skin editor.

This macro displays a complete list of stories of a weblog. The only parameter you can define is the number of days this list should include, but you can't do it directly in this macro, you must change that in the preferences of your weblog. To change the way stories are displayed by this macro you must edit the skins "preview" and/or "display" (the latter skin is included in the former one).

The following list contains simple macros that just display what was defined in the preferences of a site:

<% site.title %>
<% site.alias %>
<% site.tagline %>
<% site.email %>
<% site.lastupdate %>
<% site.modifytime %>

<% site.url %>

Update: The color and font macros went into the recently added layout handler.

This macro displays the basic system URL which is defined in the system preferences.

This macro is just a placeholder for the title of the antville-installation that was defined in the system preferences.