vibe.functions

Jinja template helper functions for VIBE.

ComponentSetup

Consolidated setup data for component processing (insert/appendix).

render_component_default 

render_component_default(template_string: str | object, host_context: NestedValue, track_access: bool = False) -> str | object | tuple[str | object, set[str]]

Render a component_defaults template string using host context.

Parameters:
  • template_string (str | object) –

    The Jinja template string (e.g., "{{ client_name }}" or "USD"), or a non-string value that will be returned as-is.

  • host_context (NestedValue) –

    The host template's current state as NestedValue

  • track_access (bool, default: False ) –

    Whether to return referenced variables for access tracking
Returns:
  • str | object | tuple[str | object, set[str]] –

    The rendered string value, or the original value if not a string.

need 

need(variable_value: object) -> str

Mark a variable as required in authoring context.

Used in templates to indicate that a value is needed for a coherent preview without affecting runtime rendering. Returns an empty string so it is safe to call inline during static validation or preview rendering.

defined 

defined(variable_path: str) -> bool

Check if a variable has a non-None value in the session's 'answers' NestedValue structure.

Designed to be used as a Jinja function like {% if defined('a.b.c') }}.

Parameters:
  • variable_path (str) –

    The name of the variable as a string (including the

  • path from the top-level NestedValue –

    s)
Returns:
  • bool( bool ) –

    True if the variable exists and its value is not None, False otherwise.

show_message 

show_message(block_variable: object) -> str

Provide placeholder Jinja function {{ show(block_id) }}.

Execution during template evaluation triggers access tracking of 'block_variable' by the NestedValue context when probing. Return an empty string to avoid rendering anything itself.

insert 

insert(ctx: Context, component_id: str, **params: object) -> str | Subdoc

Handle component insertion during Jinja processing.

Workflow: 1. Initialize (handled by _initialize_component_call): - Parse arguments and validate context - Locate and load component - Setup component processing infrastructure 2. Prepare component context from multiple sources 3. Execute phase-specific logic: - PROBING: Run recursive probe, track dependencies, propagate needs - RENDERING: Render component with full context, handle format conversions

Assumes static analysis has validated the insert() call and component, and populated _host_template with component_instances_ast and loaded_components_map.

appendix 

appendix(ctx: Context, component_id: str, alias: str, parent: AppendixReference | None = None, **params: object) -> AppendixReference

Handle appendix registration during Jinja processing.

Workflow: 1. Initialize (handled by _initialize_component_call): - Parse arguments and validate context - Locate and load component (with dynamic loading fallback) - Setup component processing infrastructure 2. Prepare component context from multiple sources 3. Execute phase-specific logic: - PROBING: Run recursive probe, track dependencies, register with manager - RENDERING: Return AppendixReference for later document generation

Unlike insert(), appendix() creates separate documents and returns AppendixReference objects for hierarchical numbering and delayed rendering.

Parameters:
  • ctx (Context) –

    Jinja context (automatically passed)

  • component_id (str) –

    The ID of the component to use as an appendix

  • alias (str) –

    Unique alias for this appendix instance (required for namespacing)

  • parent (AppendixReference | None, default: None ) –

    Optional parent AppendixReference for hierarchical numbering

  • **params (object, default: {} ) –

    Explicit parameter mappings for the appendix component
Returns:
  • AppendixReference –

    AppendixReference object that can be used to access appendix properties
Raises:
  • ValueError –

    If required arguments are missing or invalid

komma_eller 

komma_eller(*args: object, **kwargs: object) -> str

Swedish typography helper: join items with comma and 'eller' (or).

Provided for legacy template content; implemented as a no-op in Python and handled in authoring-facing filters elsewhere. Safe to call during static validation.

komma_och 

komma_och(*args: object, **kwargs: object) -> str

Swedish typography helper: join items with comma and 'och' (and).

Provided for legacy template content; implemented as a no-op in Python and handled in authoring-facing filters elsewhere. Safe to call during static validation.