bengal-add-filter

name	bengal-add-filter
description	Adds a new Jinja/Kida filter to Bengal templates. Use when creating custom filters for formatting, filtering, or transforming template data.

Bengal Add Filter

Add a custom filter to Bengal's Kida template engine.

Procedure

Step 1: Create Filter Function

# python/filters.py

def currency(value: float, symbol: str = "$") -> str:
    """Format a number as currency."""
    if value is None:
        return f"{symbol}0.00"
    return f"{symbol}{value:,.2f}"

Step 2: Type Coercion for Numeric Params

Values from YAML/config can arrive as strings. Coerce numeric params:

from bengal.config.utils import coerce_int

def truncate_words(value: str, length: int = 50, suffix: str = "...") -> str:
    length = coerce_int(length, 50)  # Coerce from YAML string
    if not value:
        return ""
    words = value.split()
    if len(words) <= length:
        return value
    return " ".join(words[:length]) + suffix

Step 3: Register Filter

Uses internal API (may change; plugin API planned for v0.4.0):

# python/filter_registration.py

def register_filters(site) -> None:
    if hasattr(site, '_template_engine') and site._template_engine:
        env = site._template_engine._env
        env.add_filter("currency", currency)
        env.add_filter("truncate_words", truncate_words)

Step 4: Call During Build

Use a custom build script:

# build.py
from pathlib import Path
from bengal.core import Site
from bengal.orchestration.build import BuildOptions
from python.filter_registration import register_filters

site = Site.from_config(Path("."))
register_filters(site)
site.build(BuildOptions())

Step 5: Use in Templates

{{ 1234.56 | currency }}
{{ 1234.56 | currency("€") }}
{{ page.content | truncate_words(20) }}

Type Coercion Rules

• Numeric params (int, float): Use coerce_int(value, default) at filter entry
• YAML/config values: Can be str; filters must handle or coerce
• Avoid arithmetic on raw config/frontmatter values

Checklist

• Filter function with clear signature
• coerce_int() for numeric params from YAML
• env.add_filter() in registration
• Call register_filters before build
• Test with values from frontmatter (may be str)

Additional Resources

See references/add-filter-guide.md for build script options and @template_safe for error-prone functions.