Document how config flow title is determined (#2343)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Erik Montnemery 2024-09-30 18:53:16 +02:00 committed by GitHub
parent 2e9342582f
commit 2ed21df18a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -31,6 +31,21 @@ class ExampleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
Once you have updated your manifest and created the `config_flow.py`, you will need to run `python3 -m script.hassfest` (one time only) for Home Assistant to activate the config entry for your integration.
## Config flow title
The title of a config flow can be influenced by integrations, and is determined in this priority order:
1. If `title_placeholders` is set to a non-empty dictionary in the config flow, it will be used to dynamically calculate the config flow's title. Reauth and reconfigure flows automatically set `title_placeholders` to `{"name": config_entry_title}`.
1. If the integration provides a localized `flow_title`, that will be used, with any translation placeholders substituted from the `title_placeholders`.
2. If the integration does not provide a `flow_title` but the `title_placeholders` includes a `name`, the `name` will be used as the flow's title.
2. Set the flow title to the integration's localized `title`, if it exists.
3. Set the flow title to the integration manifest's `name`, if it exists.
4. Set the flow title to the integration's domain.
Note that this priority order means that:
- A localized `flow_title` is ignored if the `title_placeholders` dictionary is missing or empty, even if the localized `flow_title` does not have any placeholders
- If `title_placeholders` is not empty, but there's no localized `flow_title` and the `title_placeholders` does not include a `name`, it is ignored.
## Defining steps
Your config flow will need to define steps of your configuration flow. Each step is identified by a unique step name (`step_id`). The step callback methods follow the pattern `async_step_<step_id>`. The docs for [Data Entry Flow](data_entry_flow_index.md) describe the different return values of a step. Here is an example of how to define the `user` step: