Skip to main content

Module site_setting

Module site_setting 

Source
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 SiteSettingSchema for a scope via crate::register_site_setting!, declaring a list of Widgets. The admin then renders a real form (the same _widget.html machinery page-type fields use), validates required fields, and coerces each input back into the value_json object keyed by field name. Templates read both modes identically: {{ site_setting(scope='footer').site_name }}.

Structs§

SiteSetting
SiteSettingSchema
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 via crate::register_site_setting!.
SiteSettingsGuard
RAII guard for the site-settings map. Returned by install; drop clears the thread-local.

Constants§

I18N_KEY
Key inside value_json holding translations: {"fr": {"footer": "…"}}. Kept in the same row so settings need no extra table; templates never see it (see localize).

Functions§

get
Fetch a setting row by scope. Returns None when no row exists — templates should treat absence as “settings haven’t been configured yet” rather than erroring.
install
Install a pre-fetched scope → value_json map for the duration of the returned guard. The site_setting(scope=…) Tera function reads against this map.
keep_translations
Carry old’s translations over to new — 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 _i18n bag removed.
missing_required
Labels of required fields left blank in form. 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 means false.
prefetch_for_render
Pre-fetch every site-setting row + group them into a scope → value_json map. Public-render installs this map in a thread-local that the site_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 fields and prefill each widget’s value from the matching key in stored (the row’s value_json). The inverse of value_json_from_form:
register_tera_function
Register the site_setting(scope=…) Tera function. Wired from crate::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 locale translations in value with fields (empty strings dropped; no fields left → the language is removed).
translations
The locale translations stored in value, by field key.
upsert
UPSERT a setting by scope.
value_json_from_form
Build a value_json object from a submitted form map, coercing each value by its widget kind: