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.
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:
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)!
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 <% response.body %>. These macros refer to parts of a page (head, title, body) that are build by the application on every request.
But be careful: if you delete <% response.body %> 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 ...)
In skins you can use a number of "macros". Some of those macros are simple references to content-pieces (like <% story.title %>), some of them are more complex functionalities (i.e. <% weblog.navigation %> 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.
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:<% handler.macro [parameter="value" ...] %>
This macro will be replaced with the title of the story when the skin "preview" is accessed.<% story.title %>
Inside the default skins you'll probably find a special handler called this, i.e. in a macro-tag like <% this.title %>. 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.
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.
Nearly every macro has two standard parameters, "prefix" and "suffix", you can use them like this:
<% story.title prefix="<B>" suffix="</B><BR>" %>
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:
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.<input type="text" name="title" value="[whatever title the story has]" size="20">
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 ...)
skin
This macro calls another skin for rendering.
<% this.skin name="name of the skin"
[prefix="String"]
[suffix="String"]
%>link
This macro renders a text-link to an external URL or an internal action.
<% this.link to="ext. URL or internal action-name"
[text="String to appear as link"]
[prefix="String"]
[suffix="String"]
%>input
This macro renders an input-element. Use this macro for those inputs that have no initial value (i.e. in user-registration).
<% this.input type="text|textarea|checkbox|button|password|file"
name="Name of form-element"
[prefix="String"]
[suffix="String"]
[width="integer"]
[height="integer"]
[wrap="off|virtual|physical"]
[style="classname defined in stylesheet"]
%>weblog.title
Displays the title of the weblog
<% weblog.title [prefix="String"]
[suffix="String"]
[linkto="ext.URL or action-name title should link to"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.alias
Displays the alias of the weblog
<% weblog.alias [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.tagline
Displays the tagline of the weblog
<% weblog.tagline [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.birthdate
Displays the birthdate of the weblog
<% weblog.birthdate [prefix="String"]
[suffix="String"]
[format="format-pattern"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.bgcolor
weblog.textcolor
weblog.titlecolor
weblog.linkcolor
weblog.alinkcolor
weblog.vlinkcolor
These macros display the different colors of the weblog as defined in the preferences (without '#' as prefix!).
<% weblog.bgcolor [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.textfont
weblog.titlefont
Displays the font-specification as defined in the preferences of the weblog
<% weblog.textfont [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.textsize
weblog.titlesize
Displays the fontsize-specification as defined in the preferences of the weblog
<% weblog.textsize [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.lastupdate
Displays the timestamp when weblog was last updated (this timestamp is only updated when a new story is posted!)
<% weblog.lastupdate [prefix="String"]
[suffix="String"]
[format="format-pattern"]
%>weblog.online
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.
<% weblog.online [prefix="String"]
[suffix="String"]
[as="editor"]
[style="classname defined in stylesheet"]
%>weblog.hasdiscussions
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.
<% weblog.hasdiscussions [prefix="String"]
[suffix="String"]
[as="editor"]
[style="classname defined in stylesheet"]
%>weblog.showdays
Displays the number of days that are displayed on the frontpage of the weblog.
<% weblog.showdays [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>weblog.showarchive
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.
<% weblog.showarchive [prefix="String"]
[suffix="String"]
[as="editor"]
[style="classname defined in stylesheet"]
%>weblog.loginstatus
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!
<% weblog.loginstatus %>
weblog.navigation
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!
<% weblog.navigation %>
weblog.storylist
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!
<% weblog.storylist %>
weblog.calendar
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).
<% weblog.calendar %>
weblog.age
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.
<% weblog.age [prefix="String"]
[suffix="String"]
[format="format-pattern"]
[show="days"]
%>weblog.image
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.
<% weblog.image name="imagename"
[prefix="String"]
[suffix="String"]
[width="integer"]
[height="integer"]
[alttext="String"]
[align="HTML-alignment"]
[valign="HTML-valignment"]
[border="integer"]
[linkto="ext.URL or action-name image should link to"]
%>story.title
Displays the title of the story
<% story.title [prefix="String"]
[suffix="String"]
[linkto="ext.URL or action-name title should link to"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>story.text
Displays the text of the story. You also can place macros inside the text of a story, i.e. to embed an image or create a link.
<% story.text [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[height="integer"]
[wrap="off|virtual|physical"]
[style="classname defined in stylesheet"]
%>story.online
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.
<% story.online [prefix="String"]
[suffix="String"]
[as="editor"]
[style="classname defined in stylesheet"]
%>story.createtime
Displays the timestamp when a story was created. With the optional format-parameter you can modify the display of the createtime
<% story.createtime [prefix="String"]
[suffix="String"]
[format="format-pattern"]
%>story.editlink
Displays a link for editing this story if the current user is the author of the story
<% story.editlink [prefix="String"]
[suffix="String"]
[image="name of image to appear as link"]
[text="text to appear as link"]
%>story.deletelink
Displays a link for deleting the story if the current user is the author of the story
<% story.deletelink [prefix="String"]
[suffix="String"]
[image="name of image to appear as link"]
[text="text to appear as link"]
%>story.commentlink
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.
<% story.commentlink [prefix="String"]
[suffix="String"]
[useskin="name of skin to use"]
%>story.commentcounter
Counts the number of comment-threads of a story and displays it - but only if the owner allowed comments on stories in the preferences.
<% story.commentcounter [prefix="String"]
[suffix="String"]
[no="text to appear if no threads found"]
[one="text to appear if one thread is found"]
[more="text to appear if more than one thread is found"]
%>story.comments
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.
<% story.comments [prefix="String"]
[suffix="String"]
%>story.commentform
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.
<% story.commentform [prefix="String"]
[suffix="String"]
%>story.image
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.
<% weblog.image name="imagename"
[prefix="String"]
[suffix="String"]
[width="integer"]
[height="integer"]
[alttext="String"]
[align="HTML-alignment"]
[valign="HTML-valignment"]
[border="integer"]
[linkto="ext.URL or action-name image should link to"]
%>comment.title
Displays the title of the comment
<% comment.title [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[style="classname defined in stylesheet"]
%>comment.text
Displays the text of the comment. One can also use macros inside a comment-text.
<% comment.text [prefix="String"]
[suffix="String"]
[as="editor"]
[width="integer"]
[height="integer"]
[wrap="off|virtual|physical"]
[style="classname defined in stylesheet"]
%>comment.author
Displays the author of the comment, either as text or as link to the url that the user specified in his/her profile
<% comment.author [prefix="String"]
[suffix="String"]
%>comment.createtime
Displays the timestamp when a comment was posted. With the optional format-parameter you can modify the display of the createtime
<% comment.createtime [prefix="String"]
[suffix="String"]
[format="format-pattern"]
%>comment.editlink
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
<% comment.editlink [prefix="String"]
[suffix="String"]
[image="name of image to appear as link"]
[text="text to appear as link"]
%>comment.deletelink
Displays a link for deleting a comment if the current user is the owner of the weblog and discussions are enabled in the preferences
<% comment.deletelink [prefix="String"]
[suffix="String"]
[image="name of image to appear as link"]
[text="text to appear as link"]
%>comment.replylink
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.
<% comment.replylink [prefix="String"]
[suffix="String"]
[image="name of image to appear as link"]
[text="text to appear as link"]
%>comment.replies
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.
<% comment.replies [prefix="String"]
[suffix="String"]
%>