Support content selection using meta tags

[traut]

Background

In some cases, the structure of a produced document must slightly differ based on requirements. To avoid creating multiple templates for slightly different use cases, it should be possible to configure the rendering of the same template during execution.

Fabric already supports a version of this with no results condition and it should also be possible to mutate the template structure by runtime configuration.

Design

A straightforward way of achieving the reconfigurability of the template structure is to support tag filtering of the target blocks.

• the document / section / content blocks already support embedded meta blocks with tags attributes (PR TBD)
• Fabric CLI render subcommand should accept one or more tag values with --with-meta-tag argument
• during the evaluation, only the document/section/content blocks that contain all provided tags in meta.tags are added to the output.

Note

The nesting nature of the templates requires the leaves-first filtering, meaning that if the parent block does not match the tag filter, but any of its descendants do match, the parent block is included in the output with all its descendants that match.

It also means all its descendants are included by default if the parent block matches the filter.

• the document to be rendered (set as target in the render command) is also evaluated:
  • if only document block matches the provided tags but none of its descendants do, it is fully rendered
  • if document block does not match the provided tags but some of its descendants do, the document is rendered only with the descendants included in the output

Note

To simplify the logic that figures out what to render, keeping in mind the depends_on dependencies, the filtering can happen post rendering, meaning the whole tree is evaluated but only the matching blocks are included in the output.

For example, with the template

document "test_doc" {

  meta {
    name = "Test Template"
    tags = ["foo", "bar"]
  }

  data inline "x" {
    items = ["aaa", "bbb", "ccc"]
  }

  content text {
    meta {
      tags = ["bar", "qux"]
    }
    query = ".data.inline.x.items | length"
    text = "There are {{ .query_result }} items"
  }

  content text {
    meta {
      tags = ["qux", ]
    }
    text = "Other static text"
  }
}

The results will differ depending on the CLI command:

• if foo tag is set:

  $ fabric render document.test_doc --with-meta-tag foo
  There are 3 items
  
  Other static text

• if bar tag is set:

  $ fabric render document.test_doc --with-meta-tag bar
  There are 3 items
  
  Other static text

• if qux tag is set:

  $ fabric render document.test_doc --with-meta-tag qux
  There are 3 items
  
  Other static text

[traut]

moved to milestone 0.5 to wait for #159 as it is an enabler for this issue