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.