hax.htmlLink

Outputs <a ..>..</a>.

In a nutshell

1. Declaration of an |X|hax.htmlLink:myTag:some/rel/base/path: .. directive in a *.haxproj file,
   • further configuring: attr , xmlEscape , uriAutoExt
2. Usage anywhere: {X|myTag:rel-to-base/path/no/whitespace and then the link text text |}

Stage:

Early — this X-renderer does not require a page context for rendering: therefore many hax.htmlLink-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).

Purpose

In a similar spirit to hax.miniTag and hax.htmlImage, this one is for saving precious keystrokes with <a ..>-rich HTML contents requiring repetetive use of quickly-becoming-too-verbose markup.

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

|X|hax.htmlLink:lb: {P|/basics|}

|X|hax.htmlLink:lt: /tags:
	attr = [ ("class",
	"foo-sitelink")],
	xmlEscape =
	(True , False),
	uriAutoExt = ".html"

|X|hax.htmlLink: lx:
	../xtypes/

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.htmlLink)
• followed by  : colon and the desired X-tag name to be used to invoke it (here lx),
• followed by  : colon and now hax.htmlLink-specific configuration:
• The relative base path for all links from this X-tag (here ../xtypes),
• followed by a  : colon if an optional syntax-sensitive properties block follows, comprised (if present at all) of all the following properties in this very order:
  1. attr = [ .. ] — a List of all the tag attributes (each denoted in a ("name","value") pair) to always append (in addition to automatic href) to the <a> output by all instances of this X-tag
  2. xmlEscape = (.. , ..) — a tuple of 2 toggles (the first for the href and the second for the inner content of the <a> output by all instances of this X-tag) indicating whether to auto-HTML/XML-escape (True) or not (False)
  3. uriAutoExt = ".." — either  "" (empty) or a file name extension to always append (if missing) to the part of href prior to  # of the <a> output by all instances of this X-tag

Usage for the 2nd example from above: {X|lt:x#Delaying%20X-tags Delaying X-tags |} would output <a class="foo-sitelink" href="/tags/x.html#Delaying%20X-tags">Delaying X-tags</a> — it follows that:

• the (X-tag-)relative URI path comes first, followed by
• a white-space and the link element's inner content;
• any white-space in the URI path is to be replaced, as is standard, with %20;
• if xmlEscape is False for href, take care that the combined URI will be HTML-escaped