Expand description
Per-tenant site settings.
Editor-managed singleton key-value rows. Templates read them via
the {{ site_setting(scope='footer') }} Tera function; admins
manage them under Settings → Site settings.
Each scope (e.g. “footer”, “contact”, “social”) gets exactly one
row with a JSON value column. Two editing modes share that storage:
- Free-form (default): editors type raw JSON in a textarea. Covers ad-hoc scopes with zero host boilerplate.
- Typed: a host crate registers a
SiteSettingSchemafor a scope viacrate::register_site_setting!, declaring a list ofWidgets. The admin then renders a real form (the same_widget.htmlmachinery page-type fields use), validates required fields, and coerces each input back into thevalue_jsonobject keyed by fieldname. Templates read both modes identically:{{ site_setting(scope='footer').site_name }}.
Structs§
- Site
Setting - Site
Setting Schema - A typed schema for one settings
scope: a human label + the list of typed fields editors fill in (instead of raw JSON). Host crates register one per scope viacrate::register_site_setting!. - Site
Settings Guard - RAII guard for the site-settings map. Returned by
install; drop clears the thread-local.
Constants§
- I18N_
KEY - Key inside
value_jsonholding translations:{"fr": {"footer": "…"}}. Kept in the same row so settings need no extra table; templates never see it (seelocalize).
Functions§
- get
- Fetch a setting row by scope. Returns
Nonewhen no row exists — templates should treat absence as “settings haven’t been configured yet” rather than erroring. - install
- Install a pre-fetched
scope → value_jsonmap for the duration of the returned guard. Thesite_setting(scope=…)Tera function reads against this map. - keep_
translations - Carry
old’s translations over tonew— the typed form rebuilds the whole value from its fields and must not drop them. - list_
all - List every setting row in the tenant, sorted by scope.
- localize
- A setting’s value as a template sees it in
locale(a locale code;None= the default language): the translated text fields laid over the original, empty translations ignored, and the_i18nbag removed. - missing_
required - Labels of
requiredfields left blank inform. The submit handler turns a non-empty result into a validation error. Boolean (checkbox) widgets are skipped — “required checkbox” has no settled UX here and a missing key legitimately meansfalse. - prefetch_
for_ render - Pre-fetch every site-setting row + group them into a
scope → value_jsonmap. Public-render installs this map in a thread-local that thesite_setting(scope=…)Tera function reads. Bounded by the count of distinct scopes (typically tens), so one query per render covers every reference. - prefill_
widgets - Clone
fieldsand prefill each widget’svaluefrom the matching key instored(the row’svalue_json). The inverse ofvalue_json_from_form: - register_
tera_ function - Register the
site_setting(scope=…)Tera function. Wired fromcrate::urls::register_tera_helpers. - registered_
schemas - Every registered schema, sorted by scope. The admin list surfaces these even before a row exists, so typed settings are always discoverable in the settings menu.
- schema_
for - The registered schema for
scope, if any. Unregistered scopes fall back to the free-form JSON editor. - set_
translations - Replace the
localetranslations invaluewithfields(empty strings dropped; no fields left → the language is removed). - translations
- The
localetranslations stored invalue, by field key. - upsert
- UPSERT a setting by scope.
- value_
json_ from_ form - Build a
value_jsonobject from a submitted form map, coercing each value by its widget kind: