This directory contains templates, their wrappers and attachments used in various cases. They follow the same principle as sidebars or tag descriptions:
  * .wiki files create templates in HTML and plain text formats;
  * .html files add HTML format and also text format which is created by stripping HTML tags;
  * .txt files add text-only format;
  * .php - this is an extension - see below.

For e-mail templates this means that if you create only a .txt template that message will only be sent in plain text format and won't have an attached HTML version.

You can create templates with multiple formats - for example, Template.wiki and Template.txt. Formats override each other in order (.txt < .html < .wiki) - for example:
  * .wiki (HTML, text) + .txt (text) = text part of .wiki is discarded.

Combining .wiki and .html doesn't make sense and the latter fully overrides .wiki. You can, however, combine .html and .txt.

== Template wrappers ==
In some cases templates are not used alone but wrapped in some form. For example, when sending an e-mail in HTML form a template can contain all the necessary <html>, <body>, etc. tags but this isn't possible for all formats (e.g. for .wiki) and will also produce duplicated code.

Wrappers are .html and .txt files containing just one variable - $body - that is replaced by the template contents. Wrappers are very similar to attachments - they're named as:
  [TEMPLATE ](html|txt).tpl
...and follow usual scope overriding (e.g. "html.tpl" is a default global template but "email html.tpl" will override it for all "email *.*" templates).

If there's no corresponding wrapper template is used as it is on its own.

== Attachments ==
Some templates or their form make use of attachments: for example, e-mail notifications can contain stylesheets or images when corresponding HTML template is created (in form of .html, .wiki or .php).

Attachments are linked with a template if attachment file name starts with one of the components of the template (divided by spaces) name plus extra space. This makes it possible to have global attachments and those with a lower scope. If names collide more specific attachment overrides more "global".

Attachments can be of two types:
  * attachments used in HTML messages - correspond to multipart/related; each such file gets Content-ID equivalent to its name (without prefix, e.g. "email styles.css" becomes "cid:styles.css"). Such files are usually hidden by e-mail clients.
  * normal attachments visible in the mail client as such - correspond to multipart/mixed MIME type. Files must start with "!" following the prefix (e.g. "email !EULA.txt" - but not "!email EULA.txt").

Attachments are accessible inside e-mail body by name following last space (e.g. "email logo.png" transforms to "logo.png" when formatting "email - new comment.wiki" template).

MIME type of attached files is autodetected by the EMail class bassed on their extension and is set to application/octet-stream for unrecognized types.

Example attachments and template names (all files are assumed in config/templates):
  * styles.css - global stylesheet added to all HTML templates if target facility (e.g. e-mail) supports attachments;
  * email - new comment.wiki - template for e-mail notifications on new comments;
  * email - new comment reply.html - new comment as a reply to another comment, not blog post itself;
  * email logo.png - picture used in some or all "email *.*" template;
  * email - new comment.css - stylesheets that are added to "email - new comment.wiki" and "email - new comment reply.wiki";
  * other template.php - this template if it contains a HTML format will only have styles.css as an attachment.

== PHP templates ==
PHP templates might be less convenient to edit but they're more flexible - you can use conditions, call functions, etc. - i.e. run normal PHP code. This is not possible in other template formats.

They might also have better performance - PHP often works faster on compiled code then running Search & Replace (like strtr()), especially if server runs bytecode caching extension (such as XCache).

PHP templates are formatted using include() after formatting all other templates (.wiki, etc.) which are placed in the preset array variable $TPL. This var is of form array('html' => '...', 'text' => '...', ...) - this allows convenient usage of output buffering:

  <?ob_start?>
  <p>HTML template for <?=$pageTitle?></p>
  <?$TPL['html'] = ob_get_clean()?>

Note that the first ob_start() can be omitted as one level of output buffering is already created before including the script. Also, excessive buffers that were left after the script returns are removed using ob_end_clean().

PHP templates may also contain short PHP tags (<? and <?=) that are expanded to "<?php" and "<?php echo" - when this happens normalizaed .php file is stored in cache/templates. Note that this only occurs if short_open_tag is disabled in php.ini so there's no performance drop on most servers because short_open_tag is usually turned on.
Normalized template cache is automatically refreshed if the template file was changed.

== Template directives ==
=== Conditions ===
All templates apart from .php can contain conditional output - a simple means to avoid outputting certain piece of code. They have this form:

  {?[!]$var1 [$var2 [...]]
    <p>Paragraph using $var1 and $var2.</p>
  [$]?}

Rules:
  * in current implementation directives cannot be nested ("{?$var {?$another ?} ?}" won't work);
  * ending token can be either "$?}" or just "?}";
  * line feeds after opening token and before closing can be replaced with spaces as long as conditioned content is separated from directive tokens with at least one whitespace from both sides;
  * negated condition can be specified by using "{?!" for the opening token;
  * any number of variables is allowed (space-separated list); AND condition is implied.

Short notation of this form (with omitted variables) is allowed: {?[!] ... [$]?}
In this case:
  * the first occurring variable name is taken from the template contents;
  * or, if there's no variable inside last used variable name is taken;
  * if there was none either an error occurs.

Example that outputs a wiki link if commenter has an e-mail specified or just his name otherwise:

  {?$ [[$commentAuthorEMail== $?}$commentAuthor{?$ ]] $?}

...is equivalent to:

  {?$commentAuthorEMail [[$commentAuthorEMail==$?}$commentAuthor{?$commentAuthorEMail ]] $?}

All of the above rules apply to short conditions as well.

== Template variables ==
Template variables are case-sensitive, usually named in English and starting with a dollar symbol ($). Variables are replaced before rendering .wikis into target format (HTML or text) - this, for example, makes it possible to "pass" them to {{Actions}}.

Some variables contain already formatted value (e.g. time string in $commentTime). At the same time, templates receive all the same variables but with underscore (_) prefix that contain original value (e.g. $_commentTime containing timestamp). This is mostly useful in .php templates where you can format them on your own and in .wiki where you can call actions to do the same (e.g. {{DateFmt d#my, $commentTime}}).

Values are formatted using strings from blog lang.conf for the following types:
  * boolean (e.g. commentIsByPostAuthor) - using "template: bool 0" (False) and "template bool 1" (True);
  * Time/date (e.g. postTime) - using "template time", which is a format string for DateFmt;
  * Arrays (e.g. postTags) - are joined using "template: joiner: VAR"; if not found the value of "template: joiner" is used.

The above settings can be overriden per each template by defining key named like "TPL_NAME template TYPE" - e.g. "email new comment template: joiner: postTags" overrides joiner for postTags for "email new comment.*" template files.

In .html templates all variables except original ("_"-prefixed) have quoted <, >, & and " symbols. Other vars might also be replaced with more appropriate value - e.g. commentSignature is in HTML for .html templates, in text for .txt and in original wiki syntax for .wiki and .php.

=== Common variables ===
Recepient info:
  * recepientName
  * recepientEMail

Site info:
  * siteAdminEMail
  * siteAdminName
  * siteCopyright
  * siteDesc
  * siteHome
  * siteKeywords
  * siteLicenseName
  * siteLicenseURL
  * siteLogo128
  * siteLogo16
  * siteLogo24
  * siteLogo32
  * siteLogo48
  * siteLogo64
  * siteName
  * siteTopmostImage

=== E-mail templates ===

==== email - unlock ====
This is template of e-mail sent when a user has chosen to blacklist his address so that this blog won't send him any messages until he unlocks it. It has just one variable (apart from common ones):
  * link                    - page URL to unlock the e-mail address

==== email - new comment ====
Post info:
  * postAuthor
  * postCategory            - joined with "»"
  * postCommenting          - boolean, if commenting is enabled or disabled
  * postImage
  * postImage250
  * postImage500
  * postIsTruncated         - boolean, indicates if postShortened isn't a full post text
  * postLastChanged         - time
  * postPermalink
  * postShortened           - as appears on post list page
  * postSynopsis            - {{Synopsis}} or {{Nutshell}} - small text for <meta description>
  * postTags                - comma-separated
  * postText
  * postThumbnail           - image URL
  * postTitle
  * postTime

Comment info:
  * commentAuthor
  * commentAuthorEMail
  * commentAuthorHome
  * commentText
  * commentSignature
  * commentTime
  * commentIsByAnonymous
  * commentIsByPostAuthor
  * commentFormatter
  * commentId
  * commentURL

==== email - new comment reply ====
This template is identical to "email - new comment" but it's used when a comment is made to another comment instead of directly to the original post. It has the same variables plus a set of "parentCommentXXX" variables (parentCommentAuthor, parentCommentURL, etc.).