Docs for SchemaConfigFlowHandler (#2801)

Co-authored-by: Joost Lekkerkerker <[email protected]>
Co-authored-by: Abílio Costa <[email protected]>

Author: 3 people

docs/config_entries_config_flow_handler.md

@@ -522,6 +522,75 @@ class ExampleFlow(ConfigFlow):
         )
 ```
 
+## Use SchemaConfigFlowHandler for simple flows
+
+For helpers and integrations with simple config flows, you can use the `SchemaConfigFlowHandler` instead.
+
+Compared to using a full config flow, the `SchemaConfigFlowHandler` comes with certain limitations and needs to be considered:
+
+- All user input is saved in the `options` dictionary of the resulting config entry. Therefore it's not suitable to use in integrations which uses connection data, api key's or other information that should be stored in the config entry `data`.
+- It may be simpler to use the normal config flow handler if you have extensive validation, setting unique id or checking for duplicated config entries.
+- Starting the flow with other steps besides `user` and `import` is discouraged.
+
+```python
+
+from homeassistant.helpers.schema_config_entry_flow import (
+    SchemaCommonFlowHandler,
+    SchemaConfigFlowHandler,
+    SchemaFlowError,
+    SchemaFlowFormStep,
+)
+
+async def validate_setup(
+    handler: SchemaCommonFlowHandler, user_input: dict[str, Any]
+) -> dict[str, Any]:
+    """Validate options."""
+    if user_input[CONF_SOME_SETTING] == "error":
+      # 'setup_error' needs to be existing in string.json config errors section
+      raise SchemaFlowError("setup_error") 
+    return user_input
+
+DATA_SCHEMA_SETUP = vol.Schema(
+    {
+        vol.Required(CONF_NAME, default=DEFAULT_NAME): TextSelector()
+    }
+)
+DATA_SCHEMA_OPTIONS = vol.Schema(
+    {
+        vol.Optional(CONF_SOME_SETTING): TextSelector()
+    }
+)
+
+CONFIG_FLOW = {
+    "user": SchemaFlowFormStep(
+        schema=DATA_SCHEMA_SETUP,
+        next_step="options",
+    ),
+    "options": SchemaFlowFormStep(
+        schema=DATA_SCHEMA_OPTIONS,
+        validate_user_input=validate_setup,
+    ),
+}
+OPTIONS_FLOW = {
+    "init": SchemaFlowFormStep(
+        DATA_SCHEMA_OPTIONS,
+        validate_user_input=validate_setup,
+    ),
+}
+
+class MyConfigFlowHandler(SchemaConfigFlowHandler, domain=DOMAIN):
+    """Handle a config flow."""
+
+    config_flow = CONFIG_FLOW
+    options_flow = OPTIONS_FLOW
+    options_flow_reloads = True # Reload without a config entry listener
+
+    def async_config_entry_title(self, options: Mapping[str, Any]) -> str:
+        """Return config entry title from input."""
+        return cast(str, options[CONF_NAME])
+
+```
+
 ## Testing your config flow
 
 Integrations with a config flow require full test coverage of all code in `config_flow.py` to be accepted into core. [Test your code](development_testing.md#running-a-limited-test-suite) includes more details on how to generate a coverage report.