body { font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 10pt;
font-weight: normal;
color: #000000;
}
// -->
</style>
</head>
<bodybgcolor="#ffffff">
<h1>Documentation of macros used in Antville</h1>
<h2>Table of Contents</h2>
<ul>
<li><ahref="#general">About skins and macros</a>
<ul>
<li><ahref="#syntax">Syntax of macros</a></li>
<li><ahref="#params">Macro-parameters</a></li>
</ul>
</li>
<li><ahref="#all">Macros for all prototypes</a></li>
<li><ahref="#weblog">Macros for weblog</a></li>
<li><ahref="#story">Macros for story</a></li>
<li><ahref="#comment">Macros for comment</a></li>
</ul>
<h2>About skins and macros</h2>
<p>The whole way a weblog is displayed in Antville is determined by "skins". Whenever you create a new weblog, it will start with the default set of skins, but the nice thing with Antville is that you can easily overwrite each of those default skins to give your weblog a totally new look. Think of skins as snippets of HTML-code with special tags called "macros" embedded.</p>
<p>The whole set of skins is divided by "prototypes". Nearly everything in Antville belongs to a "prototype", and those prototypes have a number of skins you can use for all objects belonging to these prototyes. I'll give you an example:</p>
<p>Whenever you create a story, you actually create a new object of the prototype "story". This new story will be displayed on the frontpage of your weblog if you set it online. And the way this story is displayed is controlled by a skin called "preview" that belongs to the prototype "story". And every change inside the one skin "preview" will change the appearence of all stories on the frontpage (or wherever this skin might be used)!</p>
<p>There are some skins that do not belong to a prototype, i.e. the global skin "main" that is used for every page, no matter if frontpage, story detail, form for posting comments or whatever. Think of this skin as the surrounding HTML-code for all your pages. Inside this skin you'll find some special macros like <tt><% response.body %></tt>. These macros refer to parts of a page (head, title, body) that are build by the application on every request.</p>
<blockquote><i><b>But be careful:</b> if you delete <tt><% response.body %></tt> in the global skin "main" you won't be able to see or edit your weblog anymore (because the whole body of the pages will be generated but not displayed anymore ...)</i></blockquote>
<p>In skins you can use a number of "macros". Some of those macros are simple references to content-pieces (like <tt><% story.title %></tt>), some of them are more complex functionalities (i.e. <tt><% weblog.navigation %></tt> actually checks if the current user viewing a page is the owner of the weblog or not and chooses between displaying the navigation for owners or for "normal" users). You do not have to think a lot about this, just bear in mind that some of the macros listed below call other skins that you will have to modify too if you want to give your weblog a whole new layout.</p>
<aname="syntax"></a>
<h3>Syntax of macros</h3>
<p>All macros that can be used in skins have the following syntax:
The term "handler" refers to the type of object this skin is valid for, so i.e. if you have a skin called "preview" for "story", and inside this skin you want to display the title of the story, the appropriate macro would look like this:
This macro will be replaced with the title of the story when the skin "preview" is accessed.</p>
<p>Inside the default skins you'll probably find a special handler called <i>this</i>, i.e. in a macro-tag like <tt><% this.title %></tt>. To find out which title will be displayed just look to wich prototype this skin belongs to, so if you found this macro-tag in a skin of "story", you'll know that the tag will be replaced with the title of the story.</p>
<aname="params"></a>
<h3>Macro-parameters</h3>
<p>Some parameters are mandatory, but most of them are optional. In this documentation, everything in square brackets means it's optional, everything else is mandatory.</p>
<p>Nearly every macro has two standard parameters, "prefix" and "suffix", you can use them like this:
<p>Nearly every "piece of content" can easily be switched into "editing mode" with a special parameter, i.e. <% story.title as="editor" %> will display the following:
<blockquote><pre><input type="text" name="title" value="[whatever title the story has]" size="20"></pre></blockquote>
Depending on the type of content you want to switch to edit-mode, this could also appear as a checkbox, a textarea, a password-input and so on. Of course there are parameters (width, height, style, wrap ...) with which you can modify the appearance of the input.</p>
<p><blockquote><i>You can only use those parameters that are defined for each macro, everything else you try to use will be ignored. There is no way to nest macros, i.e. something like <% story.title prefix="story.author" %> won't work (instead, it will display "story.author" as the prefix ...)</i></blockquote></p>
<aname="all"></a>
<h2>Macros for all prototypes</h2>
The following macros are useable within every prototype, so if you want to place a link inside the text of a story, you just have to type <tt><% story.link to="http://helma.org" %></tt>
<p><b>skin</b><br>
This macro calls another skin for rendering.<br>
<blockquote><pre><% this.skin name="name of the skin"
[prefix="String"]
[suffix="String"]
%></pre></blockquote></p>
<p><b>link</b><br>
This macro renders a text-link to an external URL or an internal action.<br>
<blockquote><pre><% this.link to="ext. URL or internal action-name"
If you don't specify a text to appear as link, the macro will display the url instead. If you want to link an image to somewhere else, you should use the image-macro of <i>story</i> or <i>weblog</i> described below.</p>
The default format of this timestamp is "yyyy.MM.dd HH:mm". For a list of valid format-patterns please refer to <ahref="http://java.sun.com/products/jdk/1.2/docs/api/java/text/SimpleDateFormat.html">http://java.sun.com/products/jdk/1.2/docs/api/java/text/SimpleDateFormat.html</a></p>
<p><b>weblog.bgcolor</b><br>
<b>weblog.textcolor</b><br>
<b>weblog.titlecolor</b><br>
<b>weblog.linkcolor</b><br>
<b>weblog.alinkcolor</b><br>
<b>weblog.vlinkcolor</b><br>
These macros display the different colors of the weblog as defined in the preferences (without '#' as prefix!).<br>
The default format of this timestamp is "yyyy.MM.dd HH:mm". For a list of valid format-patterns please refer to <ahref="http://java.sun.com/products/jdk/1.2/docs/api/java/text/SimpleDateFormat.html">http://java.sun.com/products/jdk/1.2/docs/api/java/text/SimpleDateFormat.html</a></p>
<p><b>weblog.online</b><br>
If the weblog is online, this macro displays "yes", otherwise "no". Of course you can call the macro with the parameter as="editor" which will then display a checkbox.<br>
If the discussion-boars of the weblog are enabled, this macro displays "yes", otherwise "no". Of course you can call the macro with the parameter as="editor" which will then display a checkbox.<br>
If the archive of the weblog is enabled, this macro displays "yes", otherwise "no". Of course you can call the macro with the parameter as="editor" which will then display a checkbox.<br>
This macro calls two other skins defined in "membership": if the user is logged in, it calls the skin "statusloggedin", otherwise "statusloggedout". This macro does NOT accept prefix and suffix!<br>
If the current user is the owner of the weblog, this macro calles the skin "adminnavigation", otherwise "usernavigation". This macro does NOT accept prefix and suffix!<br>
If the weblog contains stories, this macro loops over them and calls the skin "preview" for each story. It refers to the number of days to display defined in preferences. If a story is offline, it will only be displayed if the current user is the owner of the weblog. If this weblog doesn't contain any stories, it calls the skin "welcome". This macro does NOT accept prefix and suffix!<br>
This macro renders a calendar. It uses the following skins: calendar (the main skin), calendarday (a skin used for rendering a day in the calendar), calendarselday (used for highlighting the selected day), calendarweek (used for displaying a week of the month).<br>
This macro renders a chronological list of most recently modified stories and comments. It will render for each listitem the corresponding "historyview" skin. The default number of 5 displayed items can be overridden by passing the argument "show" to this macro.<br>
This macro calculates the age of the weblog, but only if a birthdate was specified in the preferences. If a format-pattern is given, it displays the formatted birthdate, if the special parameter show="days" is given, it calculates the age of the weblog in days.<br>
This macro looks for an image with the given name and displays it if found. You can override nearly every parameter, and images also can link to external URLs or internal actions.<br>
If the story is online, this macro displays "yes", otherwise "no". Of course you can call the macro with the parameter as="editor" which will then display a checkbox.<br>
Calls a skin named "commentlink" (if not overruled by parameter "useskin") that contains a link to the form for posting comments to this story - but only if the owner allowed comments on stories in the preferences.<br>
[more="text to appear if more than one thread is found"]
%></pre></blockquote></p>
<p><b>story.comments</b><br>
Loops over threads and displays the toplevel-postings (by calling a "comment"-skin named "toplevel"). This macro is disabled if discussions are disabled in the preferences of the weblog.<br>
If the user was blocked, this macro displays nothing. If the user is not logged in, it displays a link to the login-page. If the user is logged in, it displays the form for entering a new posting. This macro does nothing if comments were disabled in the preferences of the weblog.<br>
This macro looks for an image in the image-pool of the weblog with the given name and displays it if found. You can override nearly every parameter, and images also can link to external URLs or internal actions.<br>
Displays a link for editing a comment if the current user is the author of the comment and if discussions are enabled in the preferences of the weblog<br>
Displays a link for posting a comment to a comment. Only valid for toplevel-postings. This macro does nothing if discussions were disabled in the preferences of the weblog.<br>
Loops over the replies to a comment and displays them by calling the skin "reply". This macro does nothing if discussions were disabled in the preferences of the weblog.<br>
