Adaptivecards: ActionSet element type to render actions anywhere

[matthidinger]

Release	Renderer status	Tasks status
1.2	✔️ .NET (#2438) ✔️ Android (#2439) ✔️ iOS (#2440) ✔️ TS (#2441) ✔️ UWP (#2225)	✔️ Shared (#2437)

Solves requests

• Be able to use actions (buttons) anywhere within card body (#2027)

Summary

Allow authors to place an "action bar" (or multiple) anywhere within the card body, by introducing an ActionSet element, which takes an array of actions.

This is rendered identically to the existing actions bar - meaning the host gets to choose the button orientation (horizontal/vertical) and alignment (left/center/right/stretch). This lets authors create the cards they want, while still achieving that host consistency of how the buttons are oriented and aligned.

Note that the maxActions from host config is also enforced. The maxActions only apply to a single ActionSet... so if you have two ActionSets and maxActions is 5, you can have 10 buttons on your card.

Schema

New element, ActionSet

Property | Type | Required | Description
---|---|---|---
type | "ActionSet" | Yes | The type of the element
id | string | No | A unique identifier associated with the element.
spacing | string | No | Controls the amount of spacing between this element and the preceding element.
separator | bool | No | When true, draw a separating line at the top of the element.
actions | Action[] | Yes | The actions to be displayed.
horizontalAlignment | string | No | Does NOT have horizontalAlignment property, since it wouldn't do anything, since hosts get to pick the alignment of buttons. If an author wanted to force the buttons to the left, they could place it in a ColumnSet.

Example

...
                {
                    "type": "ActionSet",
                    "actions": [
                        {
                            "type": "Action.OpenUrl",
                            "title": "Set due date",
                            "url": "https://msn.com"
                        },
                        {
                            "type": "Action.OpenUrl",
                            "title": "View",
                            "url": "https://msn.com"
                        }
                    ]
                },
                {
                    "type": "FactSet",
                    "facts": [
                        {
                            "title": "Board:",
                            "value": "Adaptive Card"
                        },
                        {
                            "title": "List:",
                            "value": "Backlog"
                        },
                        {
                            "title": "Assigned to:",
                            "value": "Matt Hidinger"
                        },
                        {
                            "title": "Due date:",
                            "value": "Not set"
                        }
                    ]
                }

Examples with different host configs. Note that author doesn't get to control the alignment.

Host config | Example
--|--
Horizontal, stretch |
Horizontal, left |
Vertical, center |
Vertical, right |

Host Config

No changes.

Down-level impact

Medium. ActionSet will be dropped.

Host burden

Theoretically no burden.

Renderer requirements

• A renderer MUST render the ActionSet using everything from the actions HostConfig except the spacing (the author picks the spacing).
  
  
  
  • Apply the maxActions limit independently to each ActionSet
  
  
  • Use the buttonSpacing between buttons
  
  
  • Respect the showCard host settings
  
  
  • Use the actionsOrientation and actionAlignment
  
  
• A renderer MUST treat ShowCards as follows...
  
  
  
  • Each individual ActionSet behaves independently of others. Thus, if there are 2 ActionSets (and the bottom action bar), each of these three can all have a ShowCard visible at once. Interacting with ShowCards on one ActionSet does NOT cause a different ActionSet's ShowCard to disappear.
  
  
• (More requirements needed, not complete list)

Auto-generated task status

• [x] Shared
• [x] .NET
• [x] Android
• [x] iOS
• [x] TS
• [x] UWP
  

[matthidinger]

Dupe of #743

[sahar922]

Hi @matthidinger ,
Why did you decide to remove it? why not keep the option to use it, and let the developer decide?
My current chatbot is built on this ActionSet, which is totally legit need in the chatbot world.

Can you please consider bringing it back?

[yaronism]

Hi @matthidinger,

We are using MSBF and using this capability with one of our customers which is production. Out of a sudden you decided to remove this feature and their chatbot stopped functioning due to this unilateral decision. Please bring it back ASAP. You can mark it as deprecated but please don't just exclude things which were part from the product before.

[matthidinger]

Hi folks, I sincerely apologize for the troubles. We removed ActionSet after feedback from host apps that did not want card authors to be able to put actions anywhere inside the card (they wanted to ensure that all actions were at the bottom of the card).

Therefore we were in a tough spot in that keeping it would have immediately fragmented the ecosystem by setting a precedent that some elements may not be supported everywhere, so for v1.0 we went conservative and opted for consistency in the schema over flexibility.

I'd be happy to keep this discussion going, but in the meantime you should be able to work around this, by registering your own custom ActionSet element and rendering it yourselves using the APIs we provide in the renders. See the bottom of this page for details.

There may also be another workaround if you only need the JavaScript rendererer: @dclaux I know you offer support for this in your client, can you explain if there's a way to toggle ActionSet support in the JS renderer as-is?

[dclaux]

For folks using the TypeScript renderer (as in rendering cards using the TypeScript renderer in your own application, not sending cards to clients that use the TypeScript renderer to render them) you can already enable support for ActionSet using this one liner:

AdaptiveCard.elementTypeRegistry.registerType("ActionSet", () => { return new Adaptive.ActionSet(); });

[amotzhoshen]

Thanks @dclaux ,
Do you have a suggestion how to enable it in MSFT BotFramework-WebChat client?

[matthidinger]

@compulim do you have any documentation here on registering custom elements in WebChat?

[sahar922]

@matthidinger suddenly the ActionSet is working again.
Did you make any updates?

[szul]

I see ActionSet available in the Outlook documentation as of May 7th, but the Visual Studio Code extension doesn't support it, and neither does the Visualizer on the web site.

The problem I'm having is that to create vertically oriented button sets, it seems that I have to edit the host config (a global change), or rely completely on the host rendering.

[dclaux]

@szul the visualizer does support ActionSet when the selected host is Outlook Actionable Messages. The designer also supports it when Outlook is selected as the host.

[szul]

@dclaux So this is Outlook exclusive then?

[dclaux]

Yes, and documented as such in the Outlook documentation:

Not to say that ActionSet will never be supported outside of Outlook, but at the moment it is Outlook specific.

[szul]

@dclaux So at this time, the only way to make actionable buttons appear in a vertical orientation for all hosts is to edit the host configuration file, correct?

[dclaux]

@szul Correct.

[ignacionr]

From the perspective of a host product intended to receive content from many different providers, I strongly believe that Adaptive Cards should (as @matthidinger put it) keep "semantics" rather than aim at "pixel perfect."
As much as that statement can be kept as a core value, Adaptive Cards can find a great user base.
Sorry to add my 2cents but if you were to start adding a lot of presentation-related features, that would threaten the arguments I am using for my internal sale of the concept.

[matthidinger]

Notes from 11/6 review: in the future we will probably add additional styles of actions, like overflow/popup, etc

style="expandedFill"
style="expandedLeft"
style="compact" // overflow

[andrewleader]

Proposal approved!

[shalinijoshi19]

Closing the issue. Documentation for 1.2 is being tracked separately.