Module

templating.fragment_target_registry

App-level fragment target registry for HTMX content-region block selection.

Maps target IDs (e.g.page-root) to fragment_block config. When HX-Target matches a registered target, Chirp uses the registry's fragment_block instead of composition.page_block. Apps can group related targets into a page shell contract so app-level layout expectations are explicit and contract-checkable. The registry is mutable during setup and frozen at runtime.

4Classes

Classes

PageShellTarget 7 ▼
A single target participating in a page shell contract.

A single target participating in a page shell contract.

Attributes

Name Type Description
target_id str —
fragment_block str —
triggers_shell_update bool —
required bool —
description str —
scope_name str | None —
omit_outer_layouts bool —
PageShellContract 4 ▼
Named group of fragment targets defining an app shell contract.

Named group of fragment targets defining an app shell contract.

Attributes

Name Type Description
name str —
targets tuple[PageShellTarget, ...] —
description str —

Methods

required_fragment_blocks 0 frozenset[str] ▼
property
def required_fragment_blocks(self) -> frozenset[str]
Returns
frozenset[str]
FragmentTargetConfig 7 ▼
Block config for a single fragment target. **Layers (see UI layers guide):** targets that swap **p…

Block config for a single fragment target.

Layers (see UI layers guide): targets that swap page content inside #page-content may still set triggers_shell_updateso shell regions (topbarshell_actions, title, etc.) refresh via OOB after the primary swap.

fragment_block: Block to render when HX-Target matches (e.g. page_root_inner). triggers_shell_update: When True, this swap participates in shell negotiation (e.g.shell_actionsOOB). Use False for narrow in-page swaps (e.g.#page-content-inner) that must not refresh the app shell. omit_outer_layouts: When True, boosted responses for this HX-Target skip composing filesystem layouts (page HTML only). Use for marketing shells where the outlet wraps the whole{% block content %}and re-applying the root layout would duplicate header/footer inside the outlet.

Attributes

Name Type Description
fragment_block str —
triggers_shell_update bool —
contract_name str | None —
required bool —
description str —
scope_name str | None —
omit_outer_layouts bool —
FragmentTargetRegistry 12 ▼
App-level registry mapping target IDs to fragment block config. Mutable during setup, frozen at ru…

App-level registry mapping target IDs to fragment block config.

Mutable during setup, frozen at runtime (same lifecycle as routes).

Attributes

Name Type Description
_targets dict[str, FragmentTargetConfig] —
_contracts dict[str, PageShellContract] —
_frozen bool —

Methods

registered_targets 0 frozenset[str] ▼
property
def registered_targets(self) -> frozenset[str]
Returns
frozenset[str]
registered_contracts 0 tuple[PageShellContract,… ▼
property
def registered_contracts(self) -> tuple[PageShellContract, ...]
Returns
tuple[PageShellContract, ...]
required_fragment_blocks 0 frozenset[str] ▼
property
def required_fragment_blocks(self) -> frozenset[str]
Returns
frozenset[str]
register 8 ▼
def register(self, target_id: str, *, fragment_block: str, triggers_shell_update: bool = True, contract_name: str | None = None, required: bool = False, description: str = '', scope_name: str | None = None, omit_outer_layouts: bool = False) -> None
Parameters
Name Type Description
target_id —
fragment_block —
triggers_shell_update — Default:True
contract_name — Default:None
required — Default:False
description — Default:''
scope_name — Default:None
omit_outer_layouts — Default:False
register_contract 1 ▼
Register a named page shell contract and all of its targets. Multiple contract…
def register_contract(self, contract: PageShellContract) -> None

Register a named page shell contract and all of its targets.

Multiple contracts are allowed (e.g. primary app shell plus a section shell). Target ids must be unique across the registry; later registrations override earlier ones for the same target id.

Parameters
Name Type Description
contract —
freeze 0 ▼
def freeze(self) -> None
get 1 FragmentTargetConfig | N… ▼
def get(self, target_id: str) -> FragmentTargetConfig | None
Parameters
Name Type Description
target_id —
Returns
FragmentTargetConfig | None
is_content_target 1 bool ▼
Return True when target expects fragment response (not full page_block).
def is_content_target(self, target_id: str) -> bool
Parameters
Name Type Description
target_id —
Returns
bool
external_url 2 str ▼
Resolve ``(route_path, block_name)`` to its block-fetch URL. Thin wrapper arou…
staticmethod
def external_url(route_path: str, block_name: str) -> str

Resolve(route_path, block_name)to its block-fetch URL.

Thin wrapper aroundfragment_url(). Lives on the registry so code holding a registry reference doesn't need to import the server module just to build a URL.

Parameters
Name Type Description
route_path —
block_name —
Returns
str