This is an old revision of the document!
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.
Grammar
The webcit templating engine evaluates html templates at start time. It respects all tokens bordered with <?…>. The Tokentext is replaced.
- 'token' token is looked up
- First in the server global token / callback list
- Second in the session local token / callback list
- tokens may have parameters in braces like token(“some string”, 1337);
- Depending on the token, parameters may be ignored, optional or required.
- there are several special modifiers which change the context of the parameter:
- _”foo” : foo will be looked up in the gettext i18n database
- :“foo” : a string-setting with the name 'foo' will be looked up and be used instead
- ;”foo” : an integer-setting with the name 'foo' will be looked up and be used instead
- B”foo” : an URL/POST Parameter (bstr in citadel notation) will be used as parameter; so if you have '/somecall?foo=bar' bar will be used.
- string tokens may have modifiers as parametersso they're escaped
- Tokens may either trigger special callbacks in webcit or replace it with the content of a previously fed string.
Special Tokens
(tokenvalue in single quotes)
Subtemplates: '='
Parameters | Description |
---|---|
1 | subtemplatename; is is completed by _m.html or .html to be looked up on the template cache |
Gettext: '_'
Parameters | Description |
---|---|
1 | text 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:
(cond)?a:b
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.
Parameters | Description |
---|---|
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 |
Server side Implementation
Iterators may be registered using
RegisterIterator(Hashkey, Keylen, nAdditionalParams, StaticServerHashlist, GetHashCallback, SubTemplCallback, HashDestructorCallback, ContextTypeProvided, ContextTypeRequired)
- GetHashCallback Function to build the hashlist to iterate over
- SubTemplCallback Function to be called before the subtemplate is evaluated; should register tokens
- Destructor Function that may destroy the hashlist (maybe its a list available all server lifetime; may be NULL therefore)
HashList *GetHashCallback(void)
void SubTemplCallback(StrBuf *TemplBuffer, void *Context, Tokens)
- TemplBuffer contains the Stringbuffer with the subtemplate.
- Context holds the pointer to your hashlist entry
void Destructor(HashList *Killme)
- Killme can be deleted.
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? |
DOBOXED
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 |
DOTABBED
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
- Message rendering (SMTP/Mime messages, no vcard/ical/…)
- Room specific Since most of the time your Session is considered to be in a room…