Fallback and requires properties on elements

[andrewleader]

Release	Renderer status	Tasks status
1.2	✔️ .NET (#2418) ✔️ Android (#2419) ✔️ iOS (#2420) ✔️ TS (#2421) ✔️ UWP (#2125)	✔️ Shared (#2624) 🔄 Designer (#2502)

Solves requests

• Ability to provide fallback elements when elements aren't supported Request: Ability to provide fallback elements when elements aren't supported #2018
• Ability to declare required host features for content within card Request: Ability to declare required host features for content within card #2028

Summary

Add a fallback and requires property to all elements

Schema

New properties on all elements

Property	Type	Required	Description
fallback	"drop" or AdaptiveElement	false	Fallback content or action if the element cannot be rendered. If not provided and an ancestor element has a fallback, the ancestor's fallback will be triggered. Otherwise, the element itself will be dropped.
requires	Dictionary<string, string>	false	Requirements for the element to be rendered. In the format of <feature, version>, where the version number uses NuGet package manager version syntax to allow specifying min/max/etc

New properties on all actions (only difference is the allowed fallback object type of Action rather than Element)

Property	Type	Required	Description
fallback	"drop" or AdaptiveAction	false	Fallback content or action if the element cannot be rendered. If not provided and an ancestor element has a fallback, the ancestor's fallback will be triggered. Otherwise, the element itself will be dropped.
requires	Dictionary<string, string>	false	Requirements for the element to be rendered. In the format of <feature, version>, where the version number uses NuGet package manager version syntax to allow specifying min/max/etc

Example

Alternative media content

{
  "type": "Media",
  "poster": "https://...",
  "sources": [ ],
  "fallback": {
    "type": "Image",
    "url": "https://movies.com/thumbnail"
  }
}

Drop a group of dependent content

The text doesn't make sense without the graph, so we want all of this to be dropped together.

On the entire container, the author specifies "fallback": "drop".

When the child Graph fails to render, since it doesn't have a fallback of its own, the error will be bubbled up to the parent container, where the error will be caught by the fallback the author specified.

        {
            "type": "Container",
            "items": [
                {
                    "type": "TextBlock",
                    "text": "This text block makes no sense without the graph below it."
                },
                {
                    "type": "Graph",
                    "xAxis": "Profit"
                }
            ],
            "fallback": "drop"
        }

Alternate content for a group of dependent content

If the graph isn't supported, both the graph and the text need to change.

Since the child must be rendered (but cannot), the container will display its fallback.

        {
            "type": "Container",
            "items": [
                {
                    "type": "TextBlock",
                    "text": "This text block makes no sense without the graph below it."
                },
                {
                    "type": "Graph",
                    "xAxis": "Profit"
                }
            ],
            "fallback": {
                "type": "Container",
                "items": [
                    {
                        "type": "TextBlock",
                        "text": "To view a graph, click this card"
                    }
                ]
            }
        }

Require AAD sign on token and at least Adaptive version 1.2

If either AAD sign on or Adaptive Card 1.2 isn't supported, the fallback will be employed.

Version numbers use NuGet package manager version string syntax.

{
    "type": "Container",
    "requires": {
      "-ms-aadSignOn": "*",
      "adaptiveCard": "1.2"
    },
    "items": [
        {
            "type": "TextBlock",
            "text": "This text block makes no sense without the graph below it."
        },
        {
            "type": "Graph",
            "xAxis": "Profit"
        }
    ],
    "fallback": {
        "type": "Container",
        "items": [
            {
                "type": "TextBlock",
                "text": "To view a graph, click this card"
            }
        ]
    }
}

Host Config

None.

Down-level impact

No change from today.

Host burden

None.

Auto-generated task status

• Shared
• Designer
• .NET
• Android
• iOS
• TS
• UWP

[andrewleader]

Closing as this was done in 1.2