tap_multi_calls - a new community contribution

[dcapslock]

All button-card *_action sections are processed at time of action. This means you can hack into an action to do some extended features. In the past there has been the multi_calls hack that has been misunderstood as a feature. It has it's limitations. Here I show how to extended the premise of that hack into somthing a bit more templatable.

Supports:

• Implements tap-multi-calls as a button-card template.
• Provides config via tap_multi_calls variable which is an object including actions array/list and confirmation object.
• Standard actions as an array/list. These are fired off async with no futher sequence control, nor delay etc.
• Standard confirmation section (optional) which works the same as usual button-card confirmations, which are passed to Home Assistant.
• As button-card variables are recursively evaluated for templates, you can template actions at any level. Your action may be, for example, a Browser Mod popup with a button-card with nested templates (extra [] pair).
• NOTE: as toggle action actually gets its entity for the card config, and this template only passes a tap_action, action: toggle will not work. Instead use action: perform-action with perform_action: switch.toggle, perform_action: light.toggle etc. and a target (see example).
• This template should work for hold_action etc. If anyone is interested I will provide (pretty much change any reference to 'tap' to 'hold'.

Important

• I am providing this as a community contribution, not as a contributor to button-card development. Please do not raise button-card issues about this hack. Rather, ask any questions here in this discussion which I will answer here. 🙏
• I have not tested edge cases like including the template but not the variable 🤷‍♂️ I am assuming if you include the template you will know to include the variable. Just follow the example.

Template

Place in button_card_templates in your dashboard raw configuration.

button_card_templates:
  tap_multi_calls:
    tap_action:
      action: fire-dom-event
      tap_multi_calls: |
        [[[
          if (!window.tap_multi_calls) {
            window.tap_multi_calls = (ev) => {
              if (ev.detail?.tap_multi_calls) {
                if (!Array.isArray(ev.detail.tap_multi_calls)) {
                  console.warn(
                    'tap_multi_calls: not an array!', 
                    ev.detail.tap_multi_calls
                  );
                  return;
                }
                ev.detail.tap_multi_calls.forEach((action)=>{
                  let event = new CustomEvent(
                    'hass-action',
                    { 
                      detail: {
                        config: { tap_action: action },
                        action: 'tap'
                      },
                      bubbles: true,
                      composed: true,
                      cancellable: false
                    }
                  );
                  ev.target.dispatchEvent(event);
                });     
              }
            };
          }
          window.removeEventListener('ll-custom', window.tap_multi_calls);
          window.addEventListener('ll-custom', window.tap_multi_calls);
          return variables.tap_multi_calls?.actions;
        ]]]
      confirmation: |
        [[[
          return variables.tap_multi_calls?.confirmation
        ]]]

Example

An example, toggling the button-card entity switch, another switch, and navigating to `/lovelace'. I use these examples as they are clear and easy to test in your environment with a few simple changes to the entities.

type: custom:button-card
template:
  - tap_multi_calls
variables:
  tap_multi_calls:
    actions:
      - action: perform-action
        perform_action: switch.toggle
        target:
          entity_id: |
            [[[
              return entity.entity_id
            ]]]
      - action: perform-action
        perform_action: switch.toggle
        target:
          entity_id: switch.kitchen_switch
      - action: navigate
        navigation_path: /lovelace
    confirmation:
      text: Are you sure?
entity: switch.bed_switch
section_mode: true
layout: icon_name
grid_options:
  rows: 1
  columns: 6

[dcapslock]

@il77781 As discussed. Here is what I was thinking of in our pevious discussion (Option 3).

[il77781]

It's clear. Thank you!

[dcapslock]

@dcapslock, And if I specify the browser_mod.delay service in the array/list for actions, then this delay won't work, right?

browser_mod.delay only works in browser_mod.sequence.

[il77781]

@dcapslock,
Ah, that's it... I must have been confused by the browser_mod.delay explanation in the documentation. Sorry. It's clear now. Thank you!

[dcapslock]

browser_mod.delay explanation in the documentation

Documentation has been updated for next Browser Mod release to highlight this, though existing comment in documentation kind of spells it out.

[il77781]

I just realized that "most useful" doesn't mean "must be used only" to me, but that's my problem.

[dcapslock]

@lisz8 I guided you here to understand more about how the actions work regarding hacking in javascript. Basically its a by product of how button-card recursively renders templates in *_action and is not intended as a feature. Confirmation of an action is a Home Assistant Frontend function, not something button-card controls. So there is no standard way to achieve running javascript after confirmation without a hack like presented here. I understand you wish to run javascript, but not sure if that is just your example or you actually wish to just set a button red on tap - not sure what that use case really would be for in Home Assistant. Anyhow, this hack could be extended to just run javascript rather than call Home Assistant actions, though I really need to understand your use case.

As per the intro to this, I am sharing the hacks as a community member, not as a maintainer of button-card. These are hacks and will always be regarded as hacks. Just to be clear.

[lisz8]

My favorite way to use custom-button is to create cards from various "small" UI elements available in Home Assistant, like ha-icon, ha-radio, ha-textfield, and so on. I add event listeners, and these are my "actions". So I don't really use "standard" actions very often. Today I thought I could use them to leverage the confirmation object defined on the button card, but it seems hard or impossible. I don't want to post a long example here, as it seems quite off-topic. But the example code is in the question I asked on the HA forums.
Thanks so much for your interest!

[dcapslock]

Hi, as you see now it's Home Assistant conformation not button-card. Take a look at what I presented for PIN and Password confirmation. Also available is window.cardHelpers.showConfirmationDialog.

[lisz8]

Great, that's exactly what I was looking for. Thank you!

[RomRider]

This should break in 5.0.0 as actions are evaluated at render time also now (to know if the button and/or the icon are actionable). It would fire the events directly during the first render.

We could make *_action support array of actions, but again... I really think this should be handled by a script in the backend.

[i-myslach]

Supporting arrays of actions could simplify some use cases.

I do wonder, though, about how navigation-type actions would behave if handled purely in the backend. Since navigate is a frontend-only behavior, it can't be triggered from a backend script unless you rely on something like browser_mod.navigate, which introduces its own complexity.

For example, someone may suggest browser-mod, but still it requires the client to be registered, and even then, it targets the entire browser session—so if a user has multiple tabs open, all of them get redirected. That’s not ideal for cases that only want to change the tab that initiated the action navigate.

So I’m curious: if we move toward backend-driven scripts to support action arrays, how frontend-only behaviors like navigation would be handled without introducing similar limitations to those on browser-mod?

[RomRider]

You'll be happy that this will soon have native support inside the card, with some added bonuses. ;-)

[dcapslock]

NOTE: This has been tested with v5 dev9. I did note if using along with another button that uses fire-dom-event for another action (e.g. PIN/Password) that you would get console error. I have updated the tap_multi_calls button_card_template (first post) to address this.

[RomRider]

#1041 👀

[RomRider]

Official support with some goodies released in 5.1.0-dev.2.
Feedback welcome, please read the dev documentation.