Skip to content

Commit

Permalink
feat-support-action-option-for-service-calls
Browse files Browse the repository at this point in the history
  • Loading branch information
EdLeckert authored and daringer committed Dec 13, 2024
1 parent 969f2de commit 3e19be8
Show file tree
Hide file tree
Showing 5 changed files with 40 additions and 39 deletions.
19 changes: 10 additions & 9 deletions docs/config-ref.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ The `flex-table-card` aims for more flexibility for tabular-ish visuallization n

- unlimited columns / rows
- various different data-sources may be used in a single table
- lots of possibilities for configuration: entity selection (include, exclude), service call responses **[NEW]**, (hidden-)column-sorting, js-based content manipulation, row limiting and more...
- lots of possibilities for configuration: entity selection (include, exclude), action (formerly service) call responses, (hidden-)column-sorting, js-based content manipulation, row limiting and more...

Flex Table gives you the possibility to visualize any tabular data within Lovelace. Especially overviews with high data densities can be easily realized.

Expand All @@ -24,32 +24,33 @@ Flex Table gives you the possibility to visualize any tabular data within Lovela
| `display_footer` | boolean | optional | Display additional summary row at end for column totals, averages, etc. (default: `false`, see column options below)
| `css` | section | optional | Modify the CSS-style of this flex-table instance [(css example)](https://github.com/custom-cards/flex-table-card/blob/master/docs/example-cfg-css.md)
| `- ...` | item(s) | optional |
| `entities` | section | **required** | Section defining the entities, either as the *data sources* or for use by a service (see below). If no entities are required for a service, use [] and omit `include/exclude`
| `entities` | section | **required** | Section defining the entities, either as the *data sources* or for use by an action (see below). If no entities are required for an action, use [] and omit `include/exclude`
| `- ...` | item(s) | **required** |
| `service` | string | optional | Service to act as *data source* instead of entities. Use `entities` to define entities for the service.
| `service_data` | section | optional | Section defining `data` required by the service, if any (see below)
| `action` | string | optional | Action* to act as *data source* instead of entities. Use `entities` to define entities for the action.
| `action_data` | section | optional | Section defining `data` required by the action, if any (see below)
| `- ...` | item(s) | optional |
| `columns` | section | **required** | Section defining the column(s) and its contents (see below)
| `- ...` | item(s) | **required** |

* `Actions` were formerly called `Services`. For backward compatibility, `service` and `service_data` options will continue to be supported for several releases.

***`entities` options (2nd level): selection / querying / filtering***

| option | Type | Required? | Description
| ---- | ---- | ------------- | -----------
| `include` | regexp | **required** | Defines the initial entity data source(s), or initial entities for a service (not required if entities not used by service) [basics](https://github.com/custom-cards/flex-table-card/blob/master/docs/example-cfg-basics.md)
| `include` | regexp | **required** | Defines the initial entity data source(s), or initial entities for an action (not required if entities not used by action) [basics](https://github.com/custom-cards/flex-table-card/blob/master/docs/example-cfg-basics.md)
| `exclude` | regexp | optional | Reduces the *included* data sources(s)

[auto-entities](https://github.com/thomasloven/lovelace-auto-entities) are also supported, see the
[examples](https://github.com/custom-cards/flex-table-card/blob/master/docs/example-cfg-autoentities.md).

***`service_data` options (2nd level)***
***`action_data` options (2nd level)***

| option | Type | Required? | Description
| ---- | ---- | ------------- | -----------
| depends on service | string | optional | Defines any data used by the service. Same format as the `data` section of the service call.
| depends on action | string | optional | Defines any data used by the action. Same format as the `data` section of the action call.

[Service call examples](example-cfg-services.md).
[Action call examples](example-cfg-services.md).

***`css` options (2nd level): [css adaptations](https://github.com/custom-cards/flex-table-card/blob/master/docs/example-cfg-css.md)***

Expand Down
4 changes: 2 additions & 2 deletions docs/example-cfg-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,8 @@ columns:
```
### Complex attribute examples
If an attribute or the result of a service call is a complex structure, dotted notation may be used to identify the desired data to display.
See [Loading from Services](https://github.com/custom-cards/flex-table-card/blob/master/docs/example-cfg-services.md) for examples.
If an attribute or the result of an action call is a complex structure, dotted notation may be used to identify the desired data to display.
See [Loading from Actions](https://github.com/custom-cards/flex-table-card/blob/master/docs/example-cfg-services.md) for examples.
<!-- [example image section] -->
<!-- use issue #29 for dumping images and link them here -->
Expand Down
2 changes: 1 addition & 1 deletion docs/example-cfg-footers.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ The following is a complete example card that demonstrates the use of footer opt
``` yaml
type: custom:flex-table-card
title: Bottles per Country
service: wine_cellar.get_countries
action: wine_cellar.get_countries
entities:
include: sensor.member_wine_inventory
sort_by: Country-
Expand Down
30 changes: 15 additions & 15 deletions docs/example-cfg-services.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Examples - Services
# Examples - Actions

## Convert from attributes to service
## Convert from attributes to action
<!-- [full text section] -->
### Demonstration of converting a flex-table-card from using `weather` entity attributes to using a service call response
### Demonstration of converting a flex-table-card from using `weather` entity attributes to using an action call response

Home Assistant is moving away from large attribute structures in favor of using service call responses. As a result, you may find yourself needing to convert from using
attributes to using service calls to populate your `flex-table-card`. Fortunately, the process is usually very simple. Consider this card definition that gets the weather
Home Assistant is moving away from large entity attribute structures in favor of using `action` (formerly `service`) call responses. As a result, you may find yourself needing to convert from using
attributes to using action calls to populate your `flex-table-card`. Fortunately, the process is usually very simple. Consider this card definition that gets the weather
forecast from a `weather` entity's attributes.

<!-- [listing section] -->
Expand All @@ -30,28 +30,28 @@ columns:
suffix: " mph"
```
To convert from using a `weather` entity's attributes to using the `get_forecasts` service call, simply add these lines (adjust `type` as needed):
To convert from using a `weather` entity's attributes to using the `get_forecasts` action call, simply add these lines (adjust `type` as needed):

``` yaml
service: weather.get_forecasts
service_data:
action: weather.get_forecasts
action_data:
type: twice_daily
```

This will work if the `get_forecasts` service returns information in the same format as the `weather` entity's attributes did. Adjustments must be made if this is not the case.
This will work if the `get_forecasts` action returns information in the same format as the `weather` entity's attributes did. Adjustments must be made if this is not the case.

<!-- [example image section] -->
<img src="../images/WeatherServiceExample.png" alt="Weather service example result" width="500px">
<img src="../images/WeatherServiceExample.png" alt="Weather action example result" width="500px">

## Using multiple entities
<!-- [full text section] -->
### Example configuration to populate flex-table-card with service call response from multiple `todo` entities
### Example configuration to populate flex-table-card with action call response from multiple `todo` entities

<!-- [listing section] -->
``` yaml
type: custom:flex-table-card
title: Multiple Entity Example
service: todo.get_items
action: todo.get_items
entities:
- todo.first_list
- todo.second_list
Expand All @@ -74,15 +74,15 @@ columns:

## Using a script as the source
<!-- [full text section] -->
### Example configuration to populate flex-table-card with service call response from a script
### Example configuration to populate flex-table-card with action call response from a script

Note that `entities`, while not needed for the service, still must be present:
Note that `entities`, while not needed for the action, still must be present:

<!-- [listing section] -->
``` yaml
type: custom:flex-table-card
title: Script Example
service: script.test_response
action: script.test_response
entities: []
columns:
- name: Name
Expand Down
24 changes: 12 additions & 12 deletions flex-table-card.js
Original file line number Diff line number Diff line change
Expand Up @@ -530,10 +530,10 @@ class FlexTableCard extends HTMLElement {
throw new Error('Please provide the "columns" option as a list.');
}

if (config.service) {
const service_config = config.service.split('.');
if (service_config.length != 2) {
throw new Error('Please specify service in "domain.service" format.');
if (config.action || config.service) {
const action_config = config.action ? config.action.split('.') : config.service.split('.');
if (action_config.length != 2) {
throw new Error('Please specify action in "domain.action" format.');
}
}

Expand Down Expand Up @@ -800,12 +800,12 @@ class FlexTableCard extends HTMLElement {
}
this.#old_rowcount = rowcount;

if (config.service) {
// Use service to populate
const service_config = config.service.split('.');
let domain = service_config[0];
let service = service_config[1];
let service_data = config.service_data;
if (config.action || config.service) {
// Use action to populate
const action_config = config.action ? config.action.split('.') : config.service.split('.');
let domain = action_config[0];
let action = action_config[1];
let action_data = config.action_data || config.service_data;

let entity_list = entities.map((entity) =>
entity.entity_id
Expand All @@ -814,8 +814,8 @@ class FlexTableCard extends HTMLElement {
hass.callWS({
"type": "call_service",
"domain": domain,
"service": service,
"service_data": service_data,
"service": action,
"service_data": action_data,
"target": entity_list.length ? { "entity_id": entity_list } : undefined,
"return_response": true,
}).then(return_response => {
Expand Down

0 comments on commit 3e19be8

Please sign in to comment.