Routes

FastHTML route handlers for settings interface

Configuration

Module-level configuration that can be customized by users before importing the router.

---

source

RoutesConfig

 RoutesConfig ()

Configuration for settings routes behavior.

Configuring Settings

The configure_settings() function is a convenience helper that sets all configuration options at once, providing a cleaner alternative to setting config attributes individually.

This is the recommended way to configure the settings system before adding the router to your app.

---

source

configure_settings

 configure_settings (config_dir:pathlib.Path=None,
                     wrap_with_layout:Callable=None, plugin_registry=None,
                     default_schema:str='general',
                     menu_section_title:str='Settings')

Configure the settings system with a single function call.

	Type	Default	Details
config_dir	Path	None	Directory for storing configuration files
wrap_with_layout	Callable	None	Function to wrap full page content with app layout
plugin_registry	NoneType	None	Optional plugin registry (must implement PluginRegistryProtocol)
default_schema	str	general	Default schema to display
menu_section_title	str	Settings	Title for the settings menu section
Returns	RoutesConfig		Configured RoutesConfig instance

Error Handling Integration

When the cjm-error-handling library is installed, settings routes use structured errors for better error tracking:

• ConfigurationError: Raised for config load/save failures, missing config files, or parse errors
• ValidationError: Raised for invalid configuration data or schema validation failures

These structured errors provide: - User-friendly messages for alerts - Debug information for logging - Rich context (schema_id, operation, config_path, etc.) - Error serialization for API responses

Without the library: Falls back to returning error alert components directly

Usage:

try:
    if save_config(schema_id, config_data, config_dir):
        # Success
        pass
except ConfigurationError as e:
    # Handle structured error
    return create_error_alert(e.get_user_message())

Helper Functions

API Router and Routes

The module-level settings_ar router can be directly imported and attached to your FastHTML app.

---

source

index

 index (request, id:str=None)

Main settings page.

	Type	Default	Details
request			FastHTML request object
id	str	None	Schema ID to display (defaults to config.default_schema)
Returns	FT		Settings page content

---

source

save

 save (request, id:str)

Save configuration handler.

	Type	Details
request		FastHTML request object
id	str	Schema ID to save
Returns	FT	Response with form or error

---

source

reset

 reset (id:str)

Reset configuration to defaults handler.

	Type	Details
id	str	Schema ID to reset
Returns	FT	Response with form or error

Plugin Routes (Optional)

These routes are only active if config.plugin_registry is set.

---

source

plugin_reset

 plugin_reset (id:str)

Reset plugin configuration to defaults handler.

	Type	Details
id	str	Plugin unique ID
Returns	FT	Response with form or error

---

source

plugin_save

 plugin_save (request, id:str)

Save plugin configuration handler.

	Type	Details
request		FastHTML request object
id	str	Plugin unique ID
Returns	FT	Response with form or error

Usage Example

# Example: Using the settings router in your app
from cjm_fasthtml_settings.core.schemas import registry
from cjm_fasthtml_settings.core.config import get_app_config_schema

# First, register your schemas
registry.register(get_app_config_schema(app_title="My App", include_theme=False))
registry.register({
    "name": "database",
    "title": "Database Settings",
    "type": "object",
    "properties": {
        "host": {"type": "string", "title": "Host", "default": "localhost"}
    }
})

# NEW WAY: Use the configure_settings helper (recommended)
from cjm_fasthtml_settings.routes import configure_settings
from pathlib import Path

configure_settings(
    config_dir=Path("my_configs"),
    default_schema="general",
    menu_section_title="Settings"
)

# OLD WAY: Direct config attribute setting (still works)
# from cjm_fasthtml_settings.routes import config
# config.config_dir = Path("my_configs")
# config.default_schema = "general"

# Then import and use the router
from cjm_fasthtml_settings.routes import settings_ar, config

print(f"Settings router prefix: {settings_ar.prefix}")
print(f"Registered schemas: {registry.list_schemas()}")
print(f"Config directory: {config.config_dir}")

Settings router prefix: /settings
Registered schemas: ['general', 'database']
Config directory: my_configs