hax.snippet

Renders the named "snippet" (aka. "controls" / "components" / "sub-templates") substituting the specified named-parameter values.

In a nutshell

1. Declaration of an |X|hax.snippet:myTag: .. directive in a *.haxproj file,
   • further configuring: vars, content
2. Usage anywhere: {X|myTag: vars = [..], content = ".." |}

This topic is in a compact format for users already familiar with the essentials of declaring X-tags and invoking them. If found challenging, try the more-elaborate-and-introductory topics first to form a better grasp on the basics and overall mechanisms.

Stage:

Early — this X-renderer does not require a page context for rendering: therefore many hax.snippet-invoking X-tags encountered during pre-templating (at start-up time) may be eagerly processed immediately in-place (for overall-reduced per-page processing loads).

To demonstrate valid *.haxproj directives declaring hax.snippet X-tags:

|X|hax.snippet:greeting:
	vars = [("greetname","Mr. No-Name")],
	content=>
Hello, <b>{%greetname%}</b>!

To elaborate, for example the last one of the above, as all |X| directives declaring X-tags do:

• begins with |X| followed by the X-renderer identifier (here hax.snippet)
• followed by  : colon and the desired X-tag name to be used to invoke it (here greeting),
• followed by  : colon and now hax.snippet-specific configuration:
• a mandatory and syntax-sensitive properties block, comprised of all the following properties in this very order:
  1. vars — a list of 0 or more name-value pairs declaring the names and default values of placeholders contained in content to be substituted as instructed by the calling {X|greeting ..|} X-tag during rendering
  2. content — the principal content that this X-tag renders; other than any haXtags this may also contain special placeholder notation referencing the so-declared vars

Any such hax.snippet declaration may also be stored in its own external file (specifically tmpl/*.haxsnip.html), in which case the |X| directive header (up to and including the X-tag name) is omitted and hence that file is to begin directly with the properties block.

Those {%varname%} placeholders that content may contain are no proper haXtags with their typical versatile processing pipeline. On the contrary, these notations just signal very simple rudimentary text-for-text (or value-for-name) substitutions, as such must not have extraneous white-space and indeed must consist of nothing-but: the variable-parameter name (correct case/spelling with respect to its above declaration in vars) inside the delimiters.

Of course, their values (or default values) can contain anything including other placeholder references or haXtags. Just be careful to ensure properly escaped outputs of anything that might produce quote marks in such scenarios.

Special inner-content placeholder: in addition to those custom ones declared in vars there is a special predefined placeholder, {:c:}, which outputs in-place the content specified and passed by the calling X-tag:

For example: {X|greeting: vars = [ ("greetname" , "Mr. Curry") ], content=> |} to output as per the above example |X| declaration directive: Hello, <b>Mr. Curry</b>!

The properties block after the X-tag name is (once again) syntax-sensitive. The vars supply any named variable-parameter values for placeholder substitution and content defines the value of the snippet's {:c:} special-placeholder (as described further above, required whether the snippet's own content uses it or not, may be empty of course).