Bloks: sections-of-pages

A collection of related pages sharing a common path prefix can be associated together via the notion of the "Blok": a lightweight set of a handful of shared meta-data and processing properties. For example, in this site the Bloks are Basics, haXtags and X-renderers.

Bloks are identified by a name that is exactly equivalent to the common path prefix of the related pages to be associated under this umbrella. This name must be connected to a number of properties via a *.haxproj |B|name: .. directive, as this "live" example (for this site's Blok named basics) easily demonstrates.

With such a directive in place:

• The content source pages associated with the Blok will all have a relative path pattern of either name/*.html or name.*.html
• Named B-tags (using the name) will work anywhere to output any given one of that Blok's shared meta-data and processing properties (that were just defined in the above *.haxproj |B|name: .. directive)
• Unnamed B-tags (for querying the "current" Blok) that end up (directly or indirectly) inside Blok-associated pages will work for the same purpose
• Inclusion/exclusion of the associated Blok pages in/from output XML files (*.atom and sitemap.xml) is precisely specified
• All of the above equally applies to the auto-generated Blok index page, if any:

If the above |B| directive defines a blokIndexPageFile, then 1 additional output page will be generated for the Blok that has no direct counterpart among the project's input content sources: this can be used as an umbrella page for the Blok's pages — dressed as a table-of-contents, a section home, an "article archive", etc. Each Blok in this site has its own such auto-generated /<name>/index.html as set in its corresponding |B| directive in default.haxproj.

Content from a snippet, not a source page

During generation of that page, when the outer template invokes {P|:content:|}

• the content of the tmpl/_hax_blokindex.haxsnip.html snippet file is applied in-place by
• invoking an (on-the-fly in-memory) X-tag of the form {X|_hax_blokindex: vars=[ ("bname","<blok-name>") ], content="" |}.
  • The "factory-default" (auto-generated whenever missing) tmpl/_hax_blokindex.haxsnip.html, as a starter template by way of example,
  • dynamically embeds the so-bnamed Blok's title and desc properties
  • via {B|title:{%bname%}|} and {B|desc:{%bname%}|} respectively.

Auto link lists to Blok pages

For seeing how to actually generate (in this auto-generated Blok index page or elsewhere) an acceptable hyperlinked listing of some or all of the Blok-associated pages —the original default tmpl/_hax_blokindex.haxsnip.html lacks this— it pays to inspect the project-directory from which this site was generated: specifically how a (minimally) customized tmpl/_hax_blokindex.haxsnip.html invokes an additional (project-specific) tmpl/dox-topicitem.haxsnip.html via a custom X-tag defined in the |X|hax.feedView:doxtopicindex: directive (in default.haxproj). This interplay may appear slightly confusing at first during experimentation, unless and until the (ultimately trivial) rendering logic of both the hax.snippet and especially the hax.feedView X-renderers are absorbed first.