Webcit Templating Engine

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.

• '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.

(tokenvalue in single quotes)

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.

Conditionals may be registered using

RegisterConditional(Hashkey, Keylen, 
                    NParameters, 
                    Callbackhook, 
                    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)

• Token contains the pre-evaluated tokens for analysis
• Context may contain information of the execution status
• the return value provides the condition to the template parser.

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.

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

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.

Renders a Box, with a subtemplate

Renders tabbed dialogs. Takes Pairs of values:

• Message rendering (SMTP/Mime messages, no vcard/ical/…)
• Room specific Since most of the time your Session is considered to be in a room…