An introduction to STE
Here I will explain you the basics of STE, the template engine, that Ratatöskr uses.
If you already know HTML (you should, if you plan to write your own temlates), this should not be that difficult.
Basically, STE adds variables and special tags to HTML, although STE does not really understand HTML itself. We will discuss this in the section about tags.
Variables
A variable is a construct, that will be replaced by a text at the time, the template will be executed by STE. Imagine it as a placeholder.
A variable is either prefixed by a $ sign, or is enclosed in ${ and }. So this $foo is equivalent to ${foo}. The later form is useful if you want to write something like this: ${foo}ish. If you wolud use the first form ($fooish) this would beinterpreted as a single variable called fooish and not as a variable named foo plus the text ish.
Variable names can contain numbers, letters (lower and upper case) and underscores (_).
If you need a literal $ sign, you can write \$.
Variables can also have sub-variables. This is called an array. If you want to access the array field bar of the variable foo you would write this: $foo[bar] or ${foo[bar]}. The array field baz of this construct would then be: $foo[bar][baz].
Tags
STE's tags look almost like regular HTML tags. Tags are also replaced by some text but are more powerful than variables since they can have parameters and can have text, variables and other tags as sub-elements. Here is a tag called foo with the parameter bar set to baz and containing some text:
<ste:foo bar="baz">
some text
</ste:foo>
As you can see, tags can come in an opening (<ste:foo bar="baz">) and a closing (</ste:foo>) version and their names are always prefixed with ste:. Parameter values can also be enclosed in single quotes instead of double quotes: (<ste:foo bar='baz'>). Self-closing tags are also allowed:
<ste:another_tag test="test" />
Allowed tag names can have numbers, letters (upper and lower case) and underscores. The same rules apply to parameters.
You can mix STE tags in HTML at every position, so this is allowed (and that explains why I said, that STE does not understand HTML):
<img src="<ste:get_cool_image />" alt="test" />
Tag parameter values can contain variables, but can not contain other STE tags.
If you need a literal " in a tag parameter, write \" instead.
Comments and raw text:
If you want to write a comment, you can use the pseudo-tag <ste:comment>. It's content will be ignored completely.
If you want a large passage of raw text, that might include text that STE would interpret, but should not, you can use the <ste:rawtext> pseudotag. Everything within this will be written out without processing it at all.
Builtin tags and the standard library
Now you know, how this system works, but it is not really useful yet.
Before I will show you Ratatöskr's specific tags for articles, comments and more, you should read about the tags, that STE already uses, since you will need at least some of these.