HaXtatic Docs

P-tags: page-specific outputs

{P| .. |} tags refer to the current page context during rendering; outputting pre-computed values (page title, page date, etc.), custom per-page variables, or correct relative paths from the current location.

Built-in

  • {P|title|} → current page content source's first <h1>'s entire inner markup (if any)
    — eg. for this page: P-tags: page-specific outputs
  • {P|1st:htmltagname|} → current page content source's first <htmltagname>'s entire inner markup (if any)
    — eg. for this page for {P|1st:b|}: current page context
  • {P|:content:|} → current page's entire content source markup (only works in your *.haxtmpl.* files)
  • {P|date|} and {P|date:mydtformatname|} → current page date
    — eg. for this page: 2016-12-17
  • {P|fileName|} → the current page's output file name
    — eg. for this page: p.html
  • {P|fileBaseName|} → the current page's output file name without file extensions
    — eg. for this page: p
  • {P|fileUri|} → the current page's URI path relative to the site root
    — eg. for this page: /tags/p.html
  • {P|filePath|} → the current page's file path relative to the output directory
    — eg. for this page: tags/p.html
  • {P|dirName|} → name of the current page's directory
    — eg. for this page: tags
  • {P|dirUri|} → URI path (relative to the site root) for the the current page's directory
    — eg. for this page: /tags/
  • {P|dirPath|} → relative path of the current page's directory
    — eg. for this page: tags/
  • {P|srcPath|} → full path to the content source of the current page
    — eg. for this page: /home/rox/c/hs/haxtatic/dox-demo/pages/tags/2016-12-17.p.html
  • {P|srcRelPath|} → project-directory-relative path to the content source of the current page
    — eg. for this page: pages/tags/2016-12-17.p.html
  • {P|outBuild|} → full path to the current page's output file
    — eg. for this page: /home/rox/c/hs/haxtatic/dox-demo/default-build/tags/p.html
  • {P|outDeploy|} → full path to the current page's output file in the secondary output directory, if any
  • {P|srcTime|} and {P|srcTime:mydtformatname|} → the current page source's actual modification date/time (which may differ from the page date if that was set explicitly)
    — eg. for this page: 2017-10-23

Custom

Define those like {%P|name=value|%} in a page; then while that page is being processed, this value will replace all encounters of {P|name|} anywhere in the page output (including portions coming from the outer template, snippets or *.haxproj definitions).

Any characters are acceptable for the name in between {%P| and  =, as well as the value in between  = and  |%}. Name and value will each be stripped of all leading and trailing white-space. Later re-defines of an already defined variable are ignored.

Of note: you can overwrite all the built-ins listed above with this feature! Possibly useful for setting page title / date that way, probably useless otherwise — but possible.

If a P-tag such as {P|foo|} fails to resolve to any result, as a last resort (before re-emitting itself in the generated output) it attempts to lookup a T-tag named (such as) P|foo — use this to define a "fallback default" value for accessing any custom P-tags (eg. occurring in templates or snippets) that only some pages set but not others.

Parameterizing

Supported for up to 6 (in total) occurrences in value of  %s or  %v (the former should technically be minimally faster, but both functionally equivalent). For accesses then occurring anywhere not simply via {P|name|}, but via {P|name:my value #1|}, {P|name:value1:value2|}, {P|name:val1:val2:val3|}, {P|name:v1:v2:v3:v4|}, {P|name:v1:v2:v3:v4:v5|}, or {P|name:v1:v2:v3:v4:v5:v6|} the appropriate in-place value substitutions will be effected. (For any more expressive substitution requirements, use of a snippet would be called for either instead of or combined with the custom P-tag.)

If any such parameterized accesses are to be employed anywhere, to avoid faulty outputs be sure to self-escape all other occurrences of  % in the original value (not in the accessing P-tags) by doubling each to  %%.

Page-relative URLs

Useful when your machine isn't running a local web server / HTTP daemon: use {P|/ your/uri/here |} to rewrite that site-root-relative path such that it will correctly point to the destination from the current page without a leading  /.
— eg. linking to /index.html and /basics/index.html from this page via {P|/index.html|} and {P|/basics/index.html|} respectively outputs in-place: ../index.html and ../basics/index.html.

If all pages exist next to each other at the site-root level anyway (micro-sites etc.), this isn't of course even needed.

Delaying X-tags

Except for rare intricate edge-cases, this is typically neither necessary nor desirable, but in any event always worth a try (to be undone later if possible) when investigating unexpected X-tag outputs.

By default, the built-in X-renderers readily detect and decide autonomously whether to process an X-tag as early as possible, or only once a page context is current (and each expressly documents this behavior).

However, any X-tag can be forced to delay rendering until page time by wrapping it inside a P-tag, ie. turning {X| .. tag content .. |}

  • into this: {P|X| .. tag content .. |}
  • not this: {P|{X| .. tag content .. |}|}