BaseAdaptiveCardExtension class

Package:

@microsoft/sp-adaptive-card-extension-base

Base class for Adaptive Card Extensions.

Extends

BaseComponent

Remarks

Adaptive Card Extensions must inherit from this class.

Constructors

(constructor)()

Constructs a new instance of the BaseAdaptiveCardExtension class

Properties

_iconProperty
_title
cardNavigator	The ViewNavigator for the Card view.
cardSize	The current CardSize.
context	See BaseComponent.context.
dataVersion	The value of this property is stored in the serialized data of the Adaptive Card Extension. It can be used to manage versioning of the Adaptive Card Extension.
description	The description of the Adaptive Card Extension defined in the manifest.
displayMode	The current DisplayMode.
iconProperty	The icon url used to render an icon on the Card view.
isRenderAsync	Indicates whether the ACE is rendering in async mode.
isVisible	Sets the visibility of the Adaptive Card Extension and re-render
navigator	The current ViewNavigator.
properties	The custom, persisted properties of the Adaptive Card Extension.
propertiesMetadata	This property defines metadata for the Adaptive Card Extension property bag. The metadata can help SharePoint understand the content of the properties better and perform relevant services on the data.
quickViewNavigator	QuickViewNavigator is a ViewNavigator for the Quick view.
renderedFromPersistedData	Indicates whether the Adaptive Card Extension was rendered from persisted data or initialized from a default state.
renderedOnce	Indicates whether the Adaptive Card Extension has initially rendered.
renderType	The current RenderType.
state	Gets the custom state of the Adaptive Card Extension.
title	This value is displayed in Card and Quick view unless it is explicitly overridden by the Views. It is also displayed as the Property Pane title.

Methods

getCachedState(state)	This virtual method returns a subset of the state object that will be cached by the client.
getCacheSettings()	Override the default cache settings.
getPropertyPaneConfiguration()	Get the Property Pane configuration for this Adaptive Card Extension. If an Adaptive Card Extension wants to use the Property Pane, then this method must be overriden.
loadPropertyPaneResources()	API to enable asynchronous loading of Property Pane related resources of the Adaptive Card Extension.
onAfterDeserialize(deserializedProperties, dataVersion)	Lifecycle method called before the property bag is populated with the deserialized property object.
onAfterPropertiesUpdatedExternally(prevProperties)	Lifecycle method called after the Adaptive Card Extension's properties have been updated by a source other than the property pane (except for isolated Adaptive Card Extensions).
onBeforeAction(action)	Lifecycle method called before Action is passed to IAdaptiveCardExtensionActionView.onAction.
onBeforeSerialize()	Lifecycle method called before serialization.
onDisplayModeChanged(oldDisplayMode)	Lifecycle method called after the DisplayMode changed.
onDispose()	Lifecycle method called before disposing the Adaptive Card Extension.
onInit()	Lifecycle method called during initialization.
onInit(cachedLoadParameters)	Lifecycle method called during initialization.
onNotificationReceived(notificationArguments)	Lifecycle method called when a notification is received for this Adaptive Card Extension.
onPropertyPaneFieldChanged(propertyPath, oldValue, newValue)	Lifecycle method called when a Property Pane field is changed.
onRenderTypeChanged(oldRenderType)	Lifecycle method called when the RenderType changes.
renderCard()	The id of the initial Card view.
renderCompleted(didUpdate)	Lifecycle method that signifies ACE has finished loading. When this API is called, performance data will be generated. Depending on didUpdate parameter, end marker for the rendering lifecycle can change. If an ACE received LKG data and does NOT need to update, render is completed when LKG is used. If an ACE received LKG data and DOES need to update, render is completed when new render arguments are used. If an ACE does not receive LKG data, render is completed when new render arguments are used.
setState(newState)	Update the state of the Adaptive Card Extension and re-render.

Constructor Details

(constructor)()

Constructs a new instance of the BaseAdaptiveCardExtension class

constructor();

Property Details

_iconProperty

protected _iconProperty: string;

Property Value

string

_title

protected _title: string;

Property Value

string

cardNavigator

The ViewNavigator for the Card view.

get cardNavigator(): IViewNavigator<BaseCardView<TProperties, TState>>;

Property Value

IViewNavigator<BaseCardView<TProperties, TState>>

cardSize

The current CardSize.

protected get cardSize(): CardSize;

Property Value

CardSize

context

See BaseComponent.context.

protected context: AdaptiveCardExtensionContext;

Property Value

AdaptiveCardExtensionContext

dataVersion

The value of this property is stored in the serialized data of the Adaptive Card Extension. It can be used to manage versioning of the Adaptive Card Extension.

protected get dataVersion(): Version;

Property Value

Version

Remarks

The default version is 1.0.

description

The description of the Adaptive Card Extension defined in the manifest.

protected get description(): string;

Property Value

string

displayMode

The current DisplayMode.

get displayMode(): DisplayMode;

Property Value

DisplayMode

iconProperty

The icon url used to render an icon on the Card view.

/** @virtual */
get iconProperty(): string;

Property Value

string

Remarks

By default, this will return the iconImageUrl defined in the manifest.

isRenderAsync

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Indicates whether the ACE is rendering in async mode.

protected get isRenderAsync(): boolean;

Property Value

boolean

Remarks

If the ACE overrides this field to return true, then it needs to call renderCompleted API after the ACE finishes initializing.

The default value is false.

isVisible

Sets the visibility of the Adaptive Card Extension and re-render

get isVisible(): boolean;

set isVisible(value: boolean);

Property Value

boolean

Remarks

This method should be called after a card view has been registered. Otherwise visibility change will not be applied to the Adaptive Card.

navigator

The current ViewNavigator.

get navigator(): IViewNavigator<BaseView<TProperties, TState>>;

Property Value

IViewNavigator<BaseView<TProperties, TState>>

Remarks

If the current BaseAdaptiveCardExtension.renderType is QuickView then returns BaseAdaptiveCardExtension.quickViewNavigator.

properties

The custom, persisted properties of the Adaptive Card Extension.

protected get properties(): TProperties;

Property Value

TProperties

propertiesMetadata

This property defines metadata for the Adaptive Card Extension property bag. The metadata can help SharePoint understand the content of the properties better and perform relevant services on the data.

/** @virtual */
protected get propertiesMetadata(): IAdaptiveCardExtensionPropertiesMetadata | undefined;

Property Value

IAdaptiveCardExtensionPropertiesMetadata | undefined

Remarks

See IAdaptiveCardExtensionPropertiesMetadata for more information about how to define metadata.

quickViewNavigator

QuickViewNavigator is a ViewNavigator for the Quick view.

get quickViewNavigator(): IQuickViewNavigator<BaseQuickView<TProperties, TState>>;

Property Value

IQuickViewNavigator<BaseQuickView<TProperties, TState>>

renderedFromPersistedData

Indicates whether the Adaptive Card Extension was rendered from persisted data or initialized from a default state.

protected get renderedFromPersistedData(): boolean;

Property Value

boolean

renderedOnce

Indicates whether the Adaptive Card Extension has initially rendered.

get renderedOnce(): boolean;

Property Value

boolean

renderType

The current RenderType.

get renderType(): RenderType;

Property Value

RenderType

state

Gets the custom state of the Adaptive Card Extension.

protected get state(): Readonly<TState>;

protected set state(initialState: Readonly<TState>);

Property Value

Readonly<TState>

Remarks

This property should not be directly updated. Please use BaseAdaptiveCardExtension.setState() to update the state after initialization.

title

This value is displayed in Card and Quick view unless it is explicitly overridden by the Views. It is also displayed as the Property Pane title.

/** @virtual */
get title(): string;

Property Value

string

Remarks

By default, this will return the title defined in the manifest.

Method Details

getCachedState(state)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

This virtual method returns a subset of the state object that will be cached by the client.

/** @virtual */
protected getCachedState(state: TState): Partial<TState>;

Parameters

state

TState

A shallow clone of the AdaptiveCardExtension state object.

Returns

Partial<TState>

Remarks

If not overriden, this will return an empty object.

getCacheSettings()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Override the default cache settings.

/** @virtual */
protected getCacheSettings(): Partial<ICacheSettings>;

Returns

Partial<ICacheSettings>

getPropertyPaneConfiguration()

Get the Property Pane configuration for this Adaptive Card Extension. If an Adaptive Card Extension wants to use the Property Pane, then this method must be overriden.

/** @virtual */
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration;

Returns

IPropertyPaneConfiguration

Remarks

Property Pane resources can be defer loaded to reduce bundle size. See BaseAdaptiveCardExtension.loadPropertyPaneResources().

loadPropertyPaneResources()

API to enable asynchronous loading of Property Pane related resources of the Adaptive Card Extension.

/** @virtual */
protected loadPropertyPaneResources(): Promise<void>;

Returns

Promise<void>

Remarks

No Property Pane events will be raised until this method resolves except for PropertyPaneConfigurationComplete, which can be used to clean up any pending resources.

onAfterDeserialize(deserializedProperties, dataVersion)

Lifecycle method called before the property bag is populated with the deserialized property object.

/** @virtual */
protected onAfterDeserialize(deserializedProperties: any, dataVersion: Version): TProperties;

Parameters

deserializedProperties

any

The object deserialized from the stored data. Note that the schema of this object is not necessarily consistent with the current property bag, because the serialization could have been done by an older version of the Adaptive Card Extension

dataVersion

Version

The data version of the stored data being deserialized. You can use this value to determine if the data was serialized by an older Adaptive Card Extension. Adaptive Card Extensions can define their data version by overriding the dataVersion property.

Returns

TProperties

The property bag of the Adaptive Card Extension

Remarks

The default implementation is a no-op. An Adaptive Card Extension developer can override this API if the deserialized object does not fully reflect the initial state of the property bag. This gives the Adaptive Card Extension developer a chance to populate the property bag right after the data is deserialized to an object.

An important scenario to use deserialize is upgrading. An upgraded Adaptive Card Extension may load the data that was serialized by an older version of the Adaptive Card Extension that supported a different schema of the property bag, resulting the deserialized object to be incosistent with the current schema of the property bag. The developer can use onAfterDeserialize to check the dataVersion and fix the property bag.

onAfterPropertiesUpdatedExternally(prevProperties)

Lifecycle method called after the Adaptive Card Extension's properties have been updated by a source other than the property pane (except for isolated Adaptive Card Extensions).

/** @virtual */
onAfterPropertiesUpdatedExternally(prevProperties: TProperties): void;

Parameters

prevProperties

TProperties

The Adaptive Card Extension properties before the update.

Returns

void

Remarks

For isolated Adaptive Card Extensions, this lifecycle is invoked instead of onPropertyPaneFieldChanged.

onBeforeAction(action)

Lifecycle method called before Action is passed to IAdaptiveCardExtensionActionView.onAction.

/** @virtual */
onBeforeAction(action: IOnBeforeActionArguments): void;

Parameters

action

IOnBeforeActionArguments

IOnBeforeActionArguments for the current action.

Returns

void

Remarks

This method is not intended to be used to cancel the action or to change the flow.

onBeforeSerialize()

Lifecycle method called before serialization.

/** @virtual */
onBeforeSerialize(): void;

Returns

void

onDisplayModeChanged(oldDisplayMode)

Lifecycle method called after the DisplayMode changed.

/** @virtual */
protected onDisplayModeChanged(oldDisplayMode: DisplayMode): void;

Parameters

oldDisplayMode

DisplayMode

The old display mode.

Returns

void

onDispose()

Lifecycle method called before disposing the Adaptive Card Extension.

/** @virtual */
onDispose(): void;

Returns

void

onInit()

Lifecycle method called during initialization.

/** @virtual */
onInit(): Promise<void>;

Returns

Promise<void>

Remarks

Asynchronous data fetches should be started during this lifecycle. Rendering can either be dependent on the result or, if resolved immediately, a fetching data state can be rendered.

onInit(cachedLoadParameters)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Lifecycle method called during initialization.

/** @virtual */
onInit(cachedLoadParameters?: ICachedLoadParameters): Promise<void>;

Parameters

cachedLoadParameters

ICachedLoadParameters

Parameters containing the cached state object (see BaseAdaptiveCardExtension.getCachedState()), which can be used to rehydrate the AdaptiveCardExtension. If undefined, the AdaptiveCardExtension was not cached or the cache expired.

Returns

Promise<void>

Remarks

Asynchronous data fetches should be started during this lifecycle. Rendering can either be dependent on the result or, if resolved immediately, a fetching data state can be rendered.

onNotificationReceived(notificationArguments)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Lifecycle method called when a notification is received for this Adaptive Card Extension.

/** @virtual */
onNotificationReceived(notificationArguments: Readonly<INotificationArguments<{}>>): INotificationResponse | undefined;

Parameters

notificationArguments

Readonly<INotificationArguments<{}>>

The INotificationArguments for the current notification event.

Returns

INotificationResponse | undefined

A registered quick view id to open or undefined.

Remarks

Only one Adaptive Card Extension can handle a notification event. If the event is handled, then propagation is finished.

onPropertyPaneFieldChanged(propertyPath, oldValue, newValue)

Lifecycle method called when a Property Pane field is changed.

/** @virtual */
protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void;

Parameters

propertyPath

string

JSON path of the property in the property bag. In the case of custom field, if no target property is provided then a custom value is assigned, which will be in the form of __CustomField_<key provided when the custom field is created>.

oldValue

any

Old value of the property. This value could be undefined/empty in the case of custom field.

newValue

any

New value of the property. This value could be undefined/empty in the case of custom field.

Returns

void

Remarks

This is invoked for reactive Property Panes.

onRenderTypeChanged(oldRenderType)

Lifecycle method called when the RenderType changes.

/** @virtual */
protected onRenderTypeChanged(oldRenderType: RenderType): void;

Parameters

oldRenderType

RenderType

The previous RenderType.

Returns

void

renderCard()

The id of the initial Card view.

/** @virtual */
protected renderCard(): string | undefined;

Returns

string | undefined

Remarks

By default, this returns undefined and will render a default Card view.

renderCompleted(didUpdate)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Lifecycle method that signifies ACE has finished loading. When this API is called, performance data will be generated. Depending on didUpdate parameter, end marker for the rendering lifecycle can change. If an ACE received LKG data and does NOT need to update, render is completed when LKG is used. If an ACE received LKG data and DOES need to update, render is completed when new render arguments are used. If an ACE does not receive LKG data, render is completed when new render arguments are used.

renderCompleted(didUpdate: boolean): void;

Parameters

didUpdate

boolean

boolean value indicating if ACE has updated.

Returns

void

setState(newState)

Update the state of the Adaptive Card Extension and re-render.

setState(newState?: Partial<TState>): void;

Parameters

newState

Partial<TState>

The new state to set.

Returns

void

Remarks

BaseAdaptiveCardExtension.state must have been initialized before calling BaseAdaptiveCardExtension.setState().