diff --git a/docs/dev_101_services.md b/docs/dev_101_services.md index 009ea38a..4f2f7053 100644 --- a/docs/dev_101_services.md +++ b/docs/dev_101_services.md @@ -79,6 +79,14 @@ set_speed: description: Sets fan speed. # If the service accepts entity IDs, target allows the user to specify entities by entity, device, or area. If `target` is specified, `entity_id` should not be defined in the `fields` map. By default it shows only targets matching entities from the same domain as the service, but if further customization is required, target supports the entity, device, and area selectors (https://www.home-assistant.io/docs/blueprint/selectors/). Entity selector parameters will automatically be applied to device and area, and device selector parameters will automatically be applied to area. target: + entity: + domain: fan + # If not all entities from the service's domain support a service, entities + # can be further filtered by the `supported_features` state attribute. An + # entity will only be possible to select if it supports at least one of the + # listed supported features. + supported_features: + - fan.FanEntityFeature.SET_SPEED # Different fields that your service accepts fields: # Key of the field @@ -103,7 +111,43 @@ set_speed: - "low" - "medium" - "high" +``` +### Filtering service fields + +In some cases, entities from a service's domain may not support all service fields. By +providing a `filter` for the field description, the field will only be shown if at least +on selected entity supports the field. + +The filter supports filtering on `supported_features` as well as on state attribute values +in general. + +This is a partial example of a field which is only shown if at least one selected entity +has the needed `supported_features`: + +```yaml + fields: + temperature: + name: Temperature + description: New target temperature for HVAC. + filter: + supported_features: + - climate.ClimateEntityFeature.TARGET_TEMPERATURE +``` + +This is a partial example of a field which is only shown if at least one selected entity's +`supported_color_modes` attribute includes either `light.ColorMode.COLOR_TEMP` or +`light.ColorMode.HS`: + +```yaml + color_temp: + name: Color temperature + description: Color temperature for the light in mireds. + filter: + attribute: + supported_color_modes: + - light.ColorMode.COLOR_TEMP + - light.ColorMode.HS ``` ## Entity Services