Templates and snippets in tmpl/

When processing a content source file to generate its corresponding output file, HaXtatic's first step is always determining the appropriate tmpl/*.haxtmpl.* file to apply.

Output templates: *.haxtmpl.*

For files that are deemed HTML files,

in new projects, this will select tmpl/default.haxtmpl.html, with the first part (here default) derived from the current setup name (which obviously defaults to default) and .html being hardcoded to always be chosen for "files that are deemed HTML files".

• If tmpl/<setup-name>.haxtmpl.html doesn't exist, HaXtatic always looks for tmpl/default.haxtmpl.html next.
• If that doesn't exist, a pre-authored default version is re-created in that location and used.
• Which files are deemed HTML files? Always those with file extensions .html, .htm and   (none at all), plus any custom _hax_htmlequivexts explicitly listed in a currently loaded *.haxproj.

What about files not "deemed HTML"?

For those HaXtatic will select tmpl/<setup-name>.haxtmpl.<ext> with  .<ext> being the actual file extension of the current input file. So one may author various file-type-specific templates such as tmpl/<setup-name>.haxtmpl.js, tmpl/<setup-name>.haxtmpl.css tmpl/<setup-name>.haxtmpl.xml and so forth.

• If tmpl/<setup-name>.haxtmpl.<ext> doesn't exist, HaXtatic always looks for tmpl/default.haxtmpl.<ext> next.
• If that doesn't exist, HaXtatic assumes in memory a default "template" with an entire content of just {P|:content:|}, equivalent to a "template" that really adds nothing but simply refers directly to the current content source being processed.

Authoring *.haxtmpl.* files

These templates may contain whatever content is desired. For each processed input file, the corresponding generated output file will first and foremost contain exactly the template content, with every haXtag occurrence substituted in-place for its own dynamically rendered output. In this process, wherever the {P|:content:|} haXtag is encountered in the template content, it is substituted in-place for (finally) the current input file's actual original source content — again with each haXtag substituted likewise.

These provide similar functionality to what is elsewhere variously called "controls", "components", "sub-templates", or "somesuchlets" — that is the repeat reuse predefined blocks of content/markup in a parameterized manner, ie. with them including named, variable values passed to them from the call-site.

For example,

the created-by-default tmpl/_hax_blokindex.haxsnip.html illustrates the simplicity of HaXtatic's implementation of this powerful concept:

• Variable values that are declared in the vars=[] list at the top (each allowing a default value if the caller does not supply a dynamic one to use) are
• then, at processing time (of an X-tag anywhere that's invoking this snippet), replacing any references to themselves inside content=> that are enclosed within {% and %}.

Directives first, then *.haxsnip.html files

These tmpl/*.haxsnip.html files are really no different from bog-standard |X|hax.snippet:<some-name>: directives in a *.haxproj, so best to start with those at first (and delaying out-"sourcing" them to individual tmpl/*.haxsnip.html files) until correct results are achieved with ease.

In fact, this is how all the tmpl/*.haxsnip.html files are loaded: exactly right after loading the current *.haxproj files during start-up, with every such tmpl/some-name.haxsnip.html being appended (in memory, on-the-fly, to the entire combined loaded *.haxproj source) as one individual |X|hax.snippet:some-name: directive.

So the support for separate tmpl/*.haxsnip.html files is really just icing on the |X|hax.snippet:my-component: cake.