Skip to content

Commit 15c0968

Browse files
AJIXuMuKAJIXuMuK
authored
Merge pull request #1119 from fabiofranzini/adaptive-card-host
Added 'AdaptiveCardHost' Control
2 parents 1ef5a7d + a3cf720 commit 15c0968

21 files changed

+3544
-27
lines changed

‎docs/documentation/docs/assets/AdaptiveCardHost.gif

5.23 MB
Loading

‎docs/documentation/docs/assets/AdaptiveCardHostTeams.gif

17.2 MB
Loading

‎docs/documentation/docs/controls/AdaptiveCardHost.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
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+
![Adaptive Card Host control](../assets/AdaptiveCardHost.gif)
19+
20+
Here is an example of the previous Web Part (using different Card), hosted as a Tab in Microsoft Teams:
21+
22+
![Adaptive Card Host control](../assets/AdaptiveCardHostTeams.gif)
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+
![](https://telemetry.sharepointpnp.com/sp-dev-fx-controls-react/wiki/controls/AdaptiveCardHost)

0 commit comments

Comments
 (0)