Custom Partials¶

Supply a KbPartialLoader when building the environment to resolve {{> key }} tags (see Partials for the tag syntax itself, the context-argument form, inline partials, and partial blocks). The loader is invoked lazily — only when a key is first encountered — and the resolved template is cached on the environment, so the loader is asked at most once per distinct key across every render that reuses that environment.

val env =
  kbEnvironment.create(context) {
    onLoadPartial { key -> partialsByKey[key]?.let { kbTemplate.create(it) } }
  }

// Each bullet's content is defined by the "memberInfo" partial:
val template = kbTemplate.create("{{#each member}}- {{> memberInfo }}\n{{/each}}")

Failure behavior¶

Partials follow the kBars rule of thumb — mistakes knowable when the template or app is written fail hard, data-driven mistakes fail soft:

Set the recursion ceiling with maxPartialDepth(n) in the builder.

Template location on soft/hard failures¶

When a soft failure occurs inside a partial, the KbSoftFailEvent carries a location: KbSourceLocation with a templateStack: List<KbTemplateOrigin> property (outermost-first) identifying the full chain of templates active at the point of failure — KbTemplateOrigin.Root for the root template, KbTemplateOrigin.Partial(key) for each loaded partial, e.g. [Root, Partial("header"), Partial("logo")]. Hard failures throw KbRenderException, which carries the same stamped templateStack in its location, so an exception message names the innermost partial when applicable.

Where to next¶

• Partials — the {{> key }} tag, context arguments, inline partials, and partial blocks from the template author's side.
• Error Handling — the full exception surface KbRenderException and KbSourceLocation belong to.
• Environment Properties and Scoped Variables — other environment-builder configuration alongside onLoadPartial.