hax.htmlLinks

Helps with site navigation: outputs a sequence of <a href=".."> .. </a> or  <outerhtmltag ..><a href=".."> .. </a></outerhtmltag> in a uniform manner.

In a nutshell

1. Declaration of an |X|hax.htmlLinks:myTag:outerhtmltag: .. directive in a *.haxproj file,
   • further configuring: attr, itemsFirst, itemsLast, wrapHref
2. Usage anywhere: {X|myTag: items = [..] , attr = [..] |}

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 or Page — this X-renderer determines dynamically (documented further below) whether or not it requires a page context for rendering, so depending on each hax.htmlLinks-invoking X-tag's configuration and/or parameters:

• some encountered during pre-templating (at start-up time) may be eagerly processed immediately in-place (for overall-reduced per-page processing loads),
• and others will be skipped over, thus only process per-page, once present.

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

|X|hax.htmlLinks:mysidenav:li

|X|hax.htmlLinks:mytopnav:div:
	attr= [ ("class","my-nav") , ("&class","my-nav-sel") ],
	itemsFirst =[ ("","Home") ],
	itemsLast = [("blog/","{T|myBlog|}")],
	wrapHref = ("/" , "index.html")

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.htmlLinks)
• followed by  : colon and the desired X-tag name to be used to invoke it (here mytopnav),
• followed by  : colon and now hax.htmlLinks-specific configuration:
• The output outer markup-tag name (can be empty to skip such) to contain every output <a> element
• 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 = [("name","value") , ..] — the output outer-tag's markup attributes as name-value pairs
     • Attribute names starting with  & ampersand are only output (without it, of course) for path-wise "current/selected/active" links with respect to the current page-context (see below paragraph for the approximate logic used here)
     • use of any such dynamic  & attribute names switches this X-tag's stage from Early (the default) into Page.
  2. itemsFirst = [("uri","text") , ..] — the links to always render first
  3. itemsLast = [("uri","text") , ..] — the links to always render last
  4. wrapHref = ("","") — the prefix-to-prepend & suffix-to-append to every rendered <a> element's href attribute value
  5. No HTML/XML/etc.-escaping of inputs is performed, provide correct values for the intended output format.

For example, {X|mysidenav: items=[("foo","Foo"),("bar","Bar")] , attr=[("class","my-foo")] |} to output:

<li class="my-foo"><a href="foo">Foo</a></li>
<li class="my-foo"><a href="bar">Bar</a></li>

For example, {X|mytopnav|} to render in all generated /blog/* output files:

<div class="my-nav"><a href="/index.html">Home</a></div>
<div class="my-nav my-nav-sel"><a href="/blog/index.html">My Blog</a></div>

— whereas all others would see the same, minus the my-nav-sel appendum.

No HTML/XML/etc.-escaping of inputs is performed, provide correct values for the intended output format.