|
| 1 | +# Adaptive Card Host |
| 2 | + |
| 3 | +The motivation behind this control is to have a React control that facilitates the use of Adaptive Cards in SPFx by adding some features such as: |
| 4 | + |
| 5 | +- Graphic integration with SharePoint / Microsoft Teams themes, both as regards the color palette and the use of the Fluent UI React controls instead of the classic HTML controls. |
| 6 | + |
| 7 | +- Automatic use of Adaptive Cards Templating if an object containing data is passed to the control. |
| 8 | + |
| 9 | +For graphic integration, in the case of SharePoint the current theme (page or section theme) or a custom theme is used. |
| 10 | +Three custom themes have been created for Microsoft Teams to emulate the colors of the available themes: Default, Dark and Hight Contrast. |
| 11 | + |
| 12 | +All Elements and Actions of Adaptive Cards have been redefined using Fluent UI React, both for SharePoint and Microsoft Teams (in this case the "Fluent UI Northstar" library is not used), adding and improving features that are not managed in Microsoft's implementation of the "adaptivecards-fluentui" library (Theme support for example). |
| 13 | + |
| 14 | +The Adaptive Cards version supported is 1.5, by using the 'adaptivecards' npm package version 2.10.0. |
| 15 | + |
| 16 | +Here is an example of the control in action inside a Web Part: |
| 17 | + |
| 18 | + |
| 19 | + |
| 20 | +Here is an example of the previous Web Part (using different Card), hosted as a Tab in Microsoft Teams: |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +## How to use this control in your solutions |
| 25 | + |
| 26 | +- Check that you installed the `@pnp/spfx-controls-react` dependency. Check out the [getting started](../../#getting-started) page for more information about installing the dependency. |
| 27 | +- In your component file, import the `AdaptiveCardHost` control as follows: |
| 28 | + |
| 29 | +```TypeScript |
| 30 | +import { AdaptiveCardHost, IAdaptiveCardHostActionResult, AdaptiveCardHostThemeType } from "@pnp/spfx-controls-react/lib/AdaptiveCardHost"; |
| 31 | +``` |
| 32 | + |
| 33 | +- Example on use the `AdaptiveCardHost` control with only required properties: |
| 34 | + |
| 35 | +```TSX |
| 36 | +<AdaptiveCardHost |
| 37 | + card={card} |
| 38 | + onInvokeAction={(action) => alert(JSON.stringify(action))} |
| 39 | + onError={(error) => alert(error.message)} |
| 40 | +/> |
| 41 | +``` |
| 42 | + |
| 43 | +- Example on use the `AdaptiveCardHost` control with all properties: |
| 44 | + |
| 45 | +```TSX |
| 46 | +<AdaptiveCardHost |
| 47 | + card={card} |
| 48 | + data={data} |
| 49 | + style={null} |
| 50 | + className={null} |
| 51 | + theme={this.props.theme} |
| 52 | + themeType={themeType} |
| 53 | + hostConfig={null} |
| 54 | + onInvokeAction={(action) => alert(JSON.stringify(action))} |
| 55 | + onError={(error) => alert(error.message)} |
| 56 | + onSetCustomElements={(registry: CardObjectRegistry<CardElement>) => { |
| 57 | + registry.register("CustomElementName", CustomElement); |
| 58 | + }} |
| 59 | + onSetCustomActions={(registry: CardObjectRegistry<Action>) => { |
| 60 | + registry.register("CustomActionName", CustomAction); |
| 61 | + }} |
| 62 | + onUpdateHostCapabilities={(hostCapabilities: HostCapabilities) => { |
| 63 | + hostCapabilities.setCustomProperty("CustomPropertyName", Date.now); |
| 64 | + }} |
| 65 | + isUniqueControlInPage={true} |
| 66 | +/> |
| 67 | +``` |
| 68 | + |
| 69 | +- Example on use the `AdaptiveCardHost` control with SharePoint Theme: |
| 70 | + |
| 71 | +```TSX |
| 72 | +<AdaptiveCardHost |
| 73 | + card={card} |
| 74 | + themeType={AdaptiveCardHostThemeType.SharePoint} |
| 75 | + onInvokeAction={(action) => alert(JSON.stringify(action))} |
| 76 | + onError={(error) => alert(error.message)} |
| 77 | +/> |
| 78 | +``` |
| 79 | + |
| 80 | +- Example on use the `AdaptiveCardHost` control with SharePoint Theme "Section Variation" ('this.props.theme' is the theme that come from the Web Part) */): |
| 81 | + |
| 82 | +```TSX |
| 83 | +<AdaptiveCardHost |
| 84 | + card={card} |
| 85 | + theme={this.props.theme} |
| 86 | + themeType={AdaptiveCardHostThemeType.SharePoint} |
| 87 | + onInvokeAction={(action) => alert(JSON.stringify(action))} |
| 88 | + onError={(error) => alert(error.message)} |
| 89 | +/> |
| 90 | +``` |
| 91 | + |
| 92 | +- Example on use the `AdaptiveCardHost` control with Teams "Default" Theme: |
| 93 | + |
| 94 | +```TSX |
| 95 | +<AdaptiveCardHost |
| 96 | + card={card} |
| 97 | + themeType={AdaptiveCardHostThemeType.Teams} |
| 98 | + onInvokeAction={(action) => alert(JSON.stringify(action))} |
| 99 | + onError={(error) => alert(error.message)} |
| 100 | +/> |
| 101 | +``` |
| 102 | + |
| 103 | +- Example on use the `AdaptiveCardHost` control with Teams "Dark" Theme: |
| 104 | + |
| 105 | +```TSX |
| 106 | +<AdaptiveCardHost |
| 107 | + card={card} |
| 108 | + themeType={AdaptiveCardHostThemeType.TeamsDark} |
| 109 | + onInvokeAction={(action) => alert(JSON.stringify(action))} |
| 110 | + onError={(error) => alert(error.message)} |
| 111 | +/> |
| 112 | +``` |
| 113 | + |
| 114 | +- Example on use the `AdaptiveCardHost` control with Teams "High Contrast" Theme: |
| 115 | + |
| 116 | +```TSX |
| 117 | +<AdaptiveCardHost |
| 118 | + card={card} |
| 119 | + themeType={AdaptiveCardHostThemeType.TeamsHighContrast} |
| 120 | + onInvokeAction={(action) => alert(JSON.stringify(action))} |
| 121 | + onError={(error) => alert(error.message)} |
| 122 | +/> |
| 123 | +``` |
| 124 | + |
| 125 | +## Implementation |
| 126 | + |
| 127 | +The `AdaptiveCardHost` control can be configured with the following properties: |
| 128 | + |
| 129 | +| Property | Type | Required | Description | |
| 130 | +| ---- | ---- | ---- | ---- | |
| 131 | +| card | object | yes | Set Adaptive Card payload. | |
| 132 | +| data | { "$root": object } | no | Set Data Source for template rendering. | |
| 133 | +| style | React.CSSProperties | no | Set CSS Style. | |
| 134 | +| className | string | no | Set CSS Class. | |
| 135 | +| theme | IPartialTheme or ITheme | no | Set Fluent UI Theme. Used only if the "themeType" property is set to 'ThemeType.SharePoint'. If not set or set to null or not defined, the theme passed through context will be searched, or the default theme of the page will be loaded. | |
| 136 | +| themeType | ThemeType | no | Select the Type of Theme you want to use. If it is not set or set to null or undefined, the 'ThemeType.SharePoint' value will be used and the "theme" property or the theme passed through the context or default page will be loaded. In other cases, the chosen Microsoft Teams theme will be applied. | |
| 137 | +| hostConfig | object | no | Set custom HostConfig. | |
| 138 | +| onInvokeAction | (action: IAdaptiveCardActionResult) => void | yes | Invoked every time an Action is performed. | |
| 139 | +| onError | (error: Error) => void | yes | Invoked every time an exception occurs in the rendering phase. | |
| 140 | +| onSetCustomElements | (registry: CardObjectRegistry<CardElement>) => void | no | Invoked to manage Elements to the current Adaptive Card instance. | |
| 141 | +| onSetCustomActions | (registry: CardObjectRegistry<Action>) => void | no | Invoked to manage Actions to the current Adaptive Card instance. | |
| 142 | +| onUpdateHostCapabilities | (hostCapabilities: HostCapabilities) => void | no | Invoked to manage the HostCapabilities object like add custom properties. | |
| 143 | +| isUniqueControlInPage | boolean | no | Set to true if you want to use only one instance of this control per page, false for multiple controls. This affects how CSS variables are set. | |
| 144 | + |
| 145 | +Interface `IAdaptiveCardHostActionResult` |
| 146 | + |
| 147 | +| Property | Type | Required | Description | |
| 148 | +| ---- | ---- | ---- | ---- | |
| 149 | +| type | string | yes | Type of the Action. | |
| 150 | +| title | string | no | Title of the Action. | |
| 151 | +| url | string | no | Url of the Action. | |
| 152 | +| data | object | no | Data of the Action. | |
| 153 | +| verb | string | no | Verb of the Action. | |
| 154 | + |
| 155 | +Enum `AdaptiveCardHostThemeType` |
| 156 | + |
| 157 | +| Type | Description | |
| 158 | +| ---- | ---- | |
| 159 | +| SharePoint | Use the SharePoint current Theme or Theme Variation | |
| 160 | +| Teams | Use the Fluent UI Teams default theme | |
| 161 | +| TeamsDark | Use the Fluent UI Teams dark theme | |
| 162 | +| TeamsHighContrast | Use the Fluent UI Teams high contrast theme | |
| 163 | + |
| 164 | + |
0 commit comments