Feature settings

A feature declares a typed schema of its admin-editable settings from init_feature(app), and the settings feature renders one generic admin panel for every schema. The feature then reads typed values with get_config, with no panel or config module of its own.

The admin surface follows the features. Install a feature that registers a schema and its panel appears under /admin/settings, remove it and re-derive the product and the panel goes. Two products with different features get different panels, and nobody writes a settings form per feature.

Declaring a schema

Call register_settings from splent_framework.settings.settings_schema inside init_feature(app). This is the slider’s full schema.

def init_feature(app):
    from splent_framework.settings.settings_schema import register_settings

    register_settings(
        "slider",
        "Slider",
        [
            {
                "key": "scope",
                "type": "select",
                "default": "home",
                "label": "Show on",
                "options": [("home", "Home page only"), ("all", "All pages")],
                "help": "Where the carousel appears.",
            },
            {"key": "autoplay", "type": "bool", "default": "1", "label": "Autoplay"},
            {"key": "interval", "type": "int", "default": "6", "label": "Interval (seconds)"},
            {
                "key": "overlay",
                "type": "bool",
                "default": "1",
                "label": "Shade the bottom half",
                "help": "Darkens the lower half so the white caption stays legible.",
            },
            {"key": "caption_color", "type": "color", "default": "#ffffff", "label": "Caption colour"},
        ],
        icon="image",
    )

Parameter	Required	Description
`feature`	yes	Stable key, such as `"slider"`. Also the panel’s URL segment and the prefix of its setting keys.
`title`	yes	Title in the panel and the sidebar, such as `"Slider"`.
`fields`	yes	A list of field dicts.
`icon`	no	Feather icon name for the sidebar entry. Defaults to `"sliders"`.

Fields

Field key	Required	Description
`key`	yes	Short key, such as `"autoplay"`. Stored as `<feature>_<key>`, so `interval` in two features never collides. You only use the short key.
`type`	yes	`bool`, `int`, `text`, `color` or `select`.
`default`	yes	Used until an administrator saves a value.
`label`	yes	Label in the form.
`help`	no	Help text under the field.
`options`	for `select`	A list of `(value, label)` pairs.
`env`	no	The environment variable, and `app.config` key, the field shadows. Defaults to `<FEATURE>_<KEY>` in uppercase (`SLIDER_INTERVAL`). Set it when the variable is named otherwise, as the theme’s `site_name` shadows `SITE_NAME`. Declare the same variable under `[tool.splent.config]` in the feature’s `pyproject.toml`.

Type	Renders as	Read as
`bool`	checkbox	`True` or `False`
`int`	number input	`int`, else the default, else `0`
`text`	text input	string
`color`	colour picker	a `#rgb` to `#rrggbbaa` hex string, else the default, else `#000000`
`select`	dropdown from `options`	the chosen `value`

Reading values

get_config(feature) returns a dict keyed by the short field keys, each value cast to its type. Each value comes from the first of these that has one.

The stored setting, what an administrator saved in the panel.
app.config[<env key>], what the product’s environment sets (see env above).
The schema’s default.

from splent_framework.settings.settings_schema import get_config

cfg = get_config("slider")
# {"scope": "home", "autoplay": True, "interval": 6,
#  "overlay": True, "caption_color": "#ffffff"}

The slider’s layout.hero hook renders only when cfg["scope"] == "all" or the request is the home page, and passes cfg to the carousel template for its styling.

setting_value(feature, key) returns one value resolved the same way, for a template that would otherwise read config.SOMETHING and miss what the panel changed. When SettingsService is unavailable, get_config returns the declared defaults.

The admin panel

Route	What it shows
`/admin/settings`	Every feature with a schema, by `title` and `icon`
`/admin/settings/<feature>`	A form built from the feature’s `fields`. Saving stores the values through `SettingsService`

Function	Returns or does
`get_schemas()`	Every schema, sorted by title
`get_schema(feature)`	One schema
`clear_settings_schemas()`	Empties the registry

The registry is cleared for each app when features load, as the navigation registry is, so /admin/settings lists only the features installed in this product.

Feature settings

Declaring a schema

Fields

Reading values

The admin panel

See also