Skip to content

Commit 8a3f582

Browse files
AJIXuMuKAlex Terentiev
andauthored
ACE migration to spfx 1.18 (SharePoint#9025)
* ACE migration * toc * grammar --------- Co-authored-by: Alex Terentiev <[email protected]>
1 parent ec2444c commit 8a3f582

File tree

2 files changed

+252
-0
lines changed

2 files changed

+252
-0
lines changed
Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
---
2+
title: Migrate Adaptive Card Extensions to SharePoint Framework 1.18
3+
description: SharePoint Framework 1.18 introduces new base classes and modified approach for building Adaptive Card Extensions (ACEs) for Microsoft Viva Connections. This article explains how to migrate your existing ACEs to the new approach.
4+
ms.date: 06/20/2023
5+
ms.localizationpriority: high
6+
---
7+
8+
# Migrate Adaptive Card Extensions to SharePoint Framework 1.18
9+
SharePoint Framework 1.18 introduces new base classes and a modified approach for building Adaptive Card Extensions (ACEs) for Microsoft Viva Connections.
10+
The changes allow us to switch from "templates"-based to more granular "components"-based card views. It will enable more flexibility for developers and increase the number of supported card views variants, or [permutations](./permutations).
11+
This article explains how to migrate your existing ACEs to the new approach.
12+
13+
> [!NOTE]
14+
> All the changes described in this article are backward compatible. You can continue using your existing ACEs without any changes. However, we recommend migrating your ACEs to the new approach to take advantage of the new features and capabilities.
15+
16+
## Migrate Quick Views to the new base class
17+
With SPFx 1.18, we deprecate the `BaseAdaptiveCardView` class and introduce `BaseAdaptiveCardQuickView` as a new base class for all quick views.
18+
The new base class provides the same functionality as the old one, so the migration is straightforward.
19+
Update the definition of your quick view class to inherit from the new base class:
20+
21+
```ts
22+
import { BaseAdaptiveCardQuickView } from '@microsoft/sp-adaptive-card-extension-base';
23+
// ...
24+
export class QuickView extends BaseAdaptiveCardQuickView<
25+
ISlashNAdaptiveCardExtensionProps,
26+
ISlashNAdaptiveCardExtensionState,
27+
IQuickViewData
28+
> {
29+
// ...
30+
```
31+
32+
## Migrate Card Views to new base class and configuration model
33+
With SPFx 1.18, we introduce a new base class and configuration model for card views. Instead of having a separate base class for each card view "template", we provide a new single base class `BaseComponentsCardView<TProperties = {}, TState = {}, TParameters extends ComponentsCardViewParameters = ITextCardViewParameters>`.
34+
Instead of specifying `cardButtons` and `data`, you must override the `cardViewParameters` getter to provide both look and data for the card view.
35+
36+
As part of the `cardViewParameters` property, you can specify the following:
37+
- **image**: Image parameters for the card view.
38+
- **cardBar**: Card bar component for the card view (title and icon).
39+
- **header**: Header components for the card view.
40+
- **body**: Body components for the card view.
41+
- **footer**: Footer components for the card view.
42+
43+
We also provide helper functions to simplify the creation of the predefined views:
44+
``ts
45+
function BasicCardView(configuration: IBasicTextCardViewConfiguration): ITextCardViewParameters;
46+
function PrimaryTextCardView(configuration: IPrimaryTextCardViewConfiguration): ITextCardViewParameters;
47+
function ImageCardView(configuration: IImageCardViewConfiguration): ITextCardViewParameters;
48+
``
49+
50+
These helpers can also be used to migrate your existing card views to the new model easily.
51+
52+
So, the migration steps are:
53+
1. Update the definition of your card view class to inherit from the new base class:
54+
55+
```ts
56+
import { BaseComponentsCardView } from '@microsoft/sp-adaptive-card-extension-base';
57+
// ...
58+
export class CardView extends BaseComponentsCardView<
59+
ISlashNAdaptiveCardExtensionProps,
60+
ISlashNAdaptiveCardExtensionState,
61+
ITextCardViewParameters
62+
> {
63+
// ...
64+
}
65+
```
66+
67+
1. Override the `cardViewParameters` getter to provide both look and data for the card view. You can use one of the helper functions to simplify the migration:
68+
69+
```ts
70+
import { BaseComponentsCardView, BasicCardView } from '@microsoft/sp-adaptive-card-extension-base';
71+
72+
// ...
73+
public get cardViewParameters(): ITextCardViewParameters {
74+
return BasicCardView({
75+
// ...
76+
});
77+
}
78+
```
79+
80+
1. Remove the `cardButtons` and `data` properties from your card view class.
81+
82+
## Examples
83+
Below are the examples of `cardViewParameters` getters for the default scaffolded Basic, Primary Text, and Image Card Views.
84+
85+
### Basic Card View
86+
`cardButtons` and `data` properties for the scaffolded Basic Card View look like this:
87+
88+
```ts
89+
public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
90+
return [
91+
{
92+
title: strings.QuickViewButton,
93+
action: {
94+
type: 'QuickView',
95+
parameters: {
96+
view: QUICK_VIEW_REGISTRY_ID
97+
}
98+
}
99+
}
100+
];
101+
}
102+
103+
public get data(): IBasicCardParameters {
104+
return {
105+
primaryText: strings.PrimaryText,
106+
title: this.properties.title
107+
};
108+
}
109+
```
110+
111+
The same configuration using `cardViewParameters`:
112+
113+
```ts
114+
public get cardViewParameters(): ITextCardViewParameters {
115+
return BasicCardView({
116+
cardBar: {
117+
componentName: 'cardBar',
118+
title: this.properties.title
119+
},
120+
header: {
121+
componentName: 'text',
122+
text: strings.PrimaryText
123+
},
124+
footer: {
125+
componentName: 'cardButton',
126+
title: strings.QuickViewButton,
127+
action: {
128+
type: 'QuickView',
129+
parameters: {
130+
view: QUICK_VIEW_REGISTRY_ID
131+
}
132+
}
133+
}
134+
});
135+
}
136+
```
137+
138+
### Primary Text Card View
139+
`cardButtons` and `data` properties for the scaffolded Primary Text Card View look like this:
140+
141+
```ts
142+
public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
143+
return [
144+
{
145+
title: strings.QuickViewButton,
146+
action: {
147+
type: 'QuickView',
148+
parameters: {
149+
view: QUICK_VIEW_REGISTRY_ID
150+
}
151+
}
152+
}
153+
];
154+
}
155+
156+
public get data(): IPrimaryTextCardParameters {
157+
return {
158+
primaryText: strings.PrimaryText,
159+
description: strings.Description,
160+
title: this.properties.title
161+
};
162+
}
163+
```
164+
165+
The same configuration using `cardViewParameters`:
166+
167+
```ts
168+
public get cardViewParameters(): ITextCardViewParameters {
169+
return PrimaryTextCardView({
170+
cardBar: {
171+
componentName: 'cardBar',
172+
title: this.properties.title
173+
},
174+
header: {
175+
componentName: 'text',
176+
text: strings.PrimaryText
177+
},
178+
body: {
179+
componentName: 'text',
180+
text: strings.Description
181+
},
182+
footer: {
183+
componentName: 'cardButton',
184+
title: strings.QuickViewButton,
185+
action: {
186+
type: 'QuickView',
187+
parameters: {
188+
view: QUICK_VIEW_REGISTRY_ID
189+
}
190+
}
191+
}
192+
});
193+
}
194+
```
195+
196+
### Image Card View
197+
`cardButtons` and `data` properties for the scaffolded Image Card View look like this:
198+
199+
```ts
200+
public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
201+
return [
202+
{
203+
title: strings.QuickViewButton,
204+
action: {
205+
type: 'QuickView',
206+
parameters: {
207+
view: QUICK_VIEW_REGISTRY_ID
208+
}
209+
}
210+
}
211+
];
212+
}
213+
214+
public get data(): IImageCardParameters {
215+
return {
216+
primaryText: strings.PrimaryText,
217+
imageUrl: require('../assets/MicrosoftLogo.png'),
218+
title: this.properties.title
219+
};
220+
}
221+
```
222+
223+
The same configuration using `cardViewParameters`:
224+
```ts
225+
public get cardViewParameters(): ITextCardViewParameters {
226+
return ImageCardView({
227+
cardBar: {
228+
componentName: 'cardBar',
229+
title: this.properties.title
230+
},
231+
image: {
232+
url: require('../assets/MicrosoftLogo.png')
233+
},
234+
header: {
235+
componentName: 'text',
236+
text: strings.PrimaryText
237+
},
238+
footer: {
239+
componentName: 'cardButton',
240+
title: strings.QuickViewButton,
241+
action: {
242+
type: 'QuickView',
243+
parameters: {
244+
view: QUICK_VIEW_REGISTRY_ID
245+
}
246+
}
247+
}
248+
});
249+
}
250+
```

docs/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -588,6 +588,8 @@
588588
href: spfx/viva/get-started/actions/media-upload/MediaUploadPropertyPane.md
589589
- name: Using focus feature in an ACE
590590
href: spfx/viva/features/focus-feature/FocusFeatureTutorial.md
591+
- name: Migrate existing ACEs to SharePoint Framework 1.18
592+
href: spf/viva/get-started/migrate-to-spfx-1-18.md
591593
- name: Known issues
592594
href: spfx/viva/known-issues-adaptive-cards.md
593595
- name: Extend Viva Connections Learning Path

0 commit comments

Comments
 (0)