Home Download News FAQ / Knowledge Base Screenshots Documentation Support Site map
philosophical imaginary
Table of Contents

Webcit Templating Engine

Developing Templates

If you run webcit with -T1, it will re-parse your template on every call, so you can instantly check back your edits. Note that it won't find new template files without a restart.

In general an URL of the format http://yourcitadel/do_template?template=yourtemplate will load yourtemplate.html from the static/t/ directory.

Most errormessages regarding the templates are rendered into your template on output, so if you find it jammed (because of for example your token is inside of quotes or so) viewing the page source will show you the full text; however, some errors can't be printed into the HTML. All errors are printed to webcits log facility, so running it from the commandline makes sense while developing templates.


The webcit templating engine evaluates html templates at start time. It respects all tokens bordered with <?>. The Tokentext is replaced.

Special Tokens

(tokenvalue in single quotes)

Subtemplates: '='

1 subtemplatename; is is completed by _m.html or .html to be looked up on the template cache

Gettext: '_'

1text to display in the users tongue; its retrieved via Gettext

Conditionals '?', '!' or '%'

The '?' and '!' Conditionals consist of two tokens, which span a part of the template. All texts and tokens between the pair are skipped if the conditional snaps in. '?' and '!' Conditionals are paired by their second parameter, which has to be an identical number. The enclosed text is skipped if the condition is true *(?) or false (!).
'%' Conditionals don't span over a pair. They choose between two short texts, like you would do with an implicit if in c:


You can use implicit parameters on the 'a'/'b' tokens, so their content is i18n'able or loadable from settings / url parameters… you name it. Their Signature is compatible to '?' and '!', plus the two possible strings; Pad Param 2, 3 and 4 with '1' if not needed.

1 (string) Name of the conditional; the second conditional token may just be 'X', its ignored.
2 (integer) Identifier is a number pairing two tokens to a conditional.
3,4 Parameters for the individual conditional; documented with the detaildescription
5 (% conditional only) String to put in if result is true
6 (% conditional only) String to put in if result is false
Conditionalname Context repquired? Description
concerning this webcit
COND:IS_HTTPS none is the current template requested via HTTPS?
COND:BSTR none does this http-parameter say “yes”?
concerning this server
COND:SERV:OPENID none is the Serverside openid facility enabled?
COND:SERV:NEWU none does the Server allow self service account creation?
COND:SERV:SUPPORTS_GUEST none does this server allow guest logins?
COND:SERV:FULLTEXT_ENABLED none does this server have a fulltext indexer?
COND:SERV:LDAP_ENABLED none does this server authenticate against an ldap server?
COND:SERVCFG creates servcfg checks for a specific server config being set
COND:EXPIRE:MODE none which expiry mode is set for this server/floor/room
concerning this user
COND:LOGGEDIN none is this a logged in user?
COND:AIDE none Checks whether the user has AIDE privileges or not.
COND:ROOMAIDE none Checks whether the user has ROOM AIDE privileges or not.
COND:MAY_CREATE_ROOM none is the current user allowed to create new rooms?
COND:USERACCESS USERLIST compares the user accesslevel to parameter
COND:USERNAME USERLIST Checks whether the contexts userlists UID is the one specified by 'usernum' or the Username is the same as specified by 'username'.
COND:USER:PIC none does this user have an avatar set?
COND:USERLIST:FLAG:USE_INTERNET USERLIST does the context user have access to internet email?
concerning this users preferences
COND:PREF none Checks against the users preferences
COND:PREF:SET none Checks against the users preferences
COND:ICONBAR:ACTIVE none whether the user has configured this part of the iconbar to be active
COND:ROOM:SET none does the user have this setting for the current room enabled?
concerning this users session
COND:ICONBAR:WHOLISTEXPANDED none whether the user has opened the list of currently online users
COND:ICONBAR:ROOMLISTEXPANDED none whether the users has opened the room selection list
COND:PAGE:WAITING none is there an instant message waiting for this user?
COND:IMPMSG none do we have a status update for the user from some of his recent actions?
concerning the current room, or a room in the list iterated
COND:ACCESS:DELETE none does the user have delete rights in the current room?
COND:ALLOWED_DEFAULT_VIEW none is this view allowed as default view for this room?
COND:THISROOM:DEFAULT_VIEW none is this the default view for this room?
COND:ROOM:TYPE_IS none is this the type of this room?
COND:THISROOM:HAVE_VIEW none is this view allowed as view for this room?
COND:THISROOM:CURR_VIEW none is this view allowed the view for this room?
COND:ROOM:EDITACCESS none is the user allowed to change at least some of this rooms properties?
COND:THISROOM:FLAG:QR none is this flag set in the bitflag properties vector for this room?
COND:THISROOM:FLAG:QR2 none is this flag set in the bitflag properties vector for this room?
COND:THISROOM:EDIT none are we allowed to edit all the properties of this room?
COND:THISROOM:ORDER none sort direction for tihs room; 0=unsorted, 1=asc 2=desc TODO
COND:THISROOM:HAVE_PIC none does this room have a special image associated with it?
COND:THISROOM:HAVE_INFOTEXT none is there an info text set in this room?
COND:UNGOTO none do we have a room to go back to?
COND:FILE:ISPIC CTX_FILELIST is the current file an image?
COND:ROOM:dav_CONTENT CTX_DAVNS WIP; whether this room has groupdav'eable content

Server Side implementation

Conditionals may be registered using

RegisterConditional(Hashkey, Keylen, 
                    int ContextTypeRequired)

If your conditional doesn't require a prepared context, put in CTX_NONE, else define your Context-type and put it there. The templating engine will refuse to evaluate this token, if the Context doesn't match; CTX_NONE tokens will be evaluated even if there is a context.
Callbackhook has to be like this:

int Callbackhook(WCTemplateToken *Tokens, 
                 void *Context, 
                 int ContextType)


Iterators are used to represent lists into the templates. They create a subcontext with a subtemplate, after evaluating all tokens of the subtemplate, the subtemplate is pasted to the main template.

ParametersSet To if unused/optionalDescription
1%name of the iterator to evaluate
2%Subtemplate for each iteration
30StartAt; set to != 0 if you want to skip values
40StepWidth; set to != 0 if you want to jump forward in bigger steps
5-1StopAt; set to != -1 if you want to stop before the end

the iterator itself provides the following list of tokens to the subtemplate:

Token Type Description
ITERATE:ODDEVEN String contains 'odd' or 'even' alternating.
ITERATE:KEY String contains the key to this hash-value
ITERATE:N int which place of the list are we?
ITERATE:LASTN int 0/1 if you're the last in the list
WHOLISTiterates over the list of logged in users; currently used in the iconbar at left; the overview; the who is online page
USERLISTloads the list of users available on this system and their basic settings for verification through the aide

Server side Implementation

Iterators may be registered using

RegisterIterator(Hashkey, Keylen, 
HashList *GetHashCallback(void)
void SubTemplCallback(StrBuf *TemplBuffer, 
                      void *Context, 
void Destructor(HashList *Killme)

Global Replacers

Tokenname Content
ROOMNAME The name of the room you're in
SERV:PID The process id of the server
SERV:NODENAME The name of this citadel
SERV:HUMANNODE The nicer readable human node name
SERV:FQDN The Full Quallified Domainname
SERV:SOFTWARE The Server Revision
SERV:REV_LEVEL The Server SVN Revision
SERV:BBS_CITY Where does this citadel live
CURRENT_USER Who is logged in here?
CURRENT_ROOM where are you?


Renders a Box, with a subtemplate

Parameters Type Description
1 String Subtemplate to render into the box
2 String (optional) Render another Subtemplate into the Boxtitle


Renders tabbed dialogs. Takes Pairs of values:

Parameters Type Description
1 String Render another Subtemplate into the Tabtitle
2 String Subtemplate to render into the box

Application specific codes

Copyright © 1987-2014 Uncensored Communications Group. All rights reserved.     Login (site admin)