BaseWebPart class

Package:

@microsoft/sp-webpart-base

This abstract class implements the UI-agnostic base functionality for a client-side web part. The purpose is to allow a common core between 2D and MR WebParts.

Extends

BaseComponent

Constructors

(constructor)()

Constructor for the BaseWebPart class.

Properties

accessibleTitle	This property points to the accessible title of web part made available to screen readers. The base implementation returns that default title in the manifest. Web parts that want to provide more descriptive title containing contextual information need to override this API. virtual
context	Use the context object to access common services and state associated with the component.
dataVersion	The value of this property is stored in the serialized data of the web part to allow developers to manage versioning of their web part. The default version is 1.0
description	Description of the WebPart
disableReactivePropertyChanges	This property is used to change the web part's property pane interaction from Reactive to NonReactive. virtual
displayMode	This property is the current display mode of the web part.
previewImageUrl	This property points to the preview image for the web part. The base implementation returns undefined. Web parts that want to provide a valid preview image url need to override this API. The preview image url can be used to create a preview of the web part or of the page on which the web part is present. virtual
properties	This property is the pointer to the custom property bag of the web part.
propertiesMetadata	This property defines metadata for the web part property bag. The metadata can help SharePoint understand the content of the properties better and perform relevant services on the data. virtual
title	Title of the WebPart

Methods

getPropertyPaneConfiguration()	This API is used to ger the configuration to build the property pane for the web part. If the web part wants to use the PropertyPane for configuration, this API needs to be overridden and the web part needs to return the configuration for the PropertyPane. This API is not invoked until the 'loadPropertyPaneResources' promise is resolved. See IPropertyPane and other PropertyPane integration wiki documentation for more details. virtual
getTopActionsConfiguration()	Returns the configuration for this webpart's top actions or undefined if the webpart doesn't support top actions.
loadPropertyPaneResources()	This API enables asynchronous loading of property pane related resources of the web part.
onAfterDeserialize(deserializedObject, dataVersion)	This API is called after the web part is deserialized to an object, right before the property bag is populated. virtual
onAfterPropertyPaneChangesApplied()	This API is invoked after the changes made on the PropertyPane are applied when the PropertyPane is used in Non-Reactive mode. This API is not invoked when the PropertyPane is used in Reactive mode. virtual
onBeforeSerialize()	This event method is called before the web part is serialized. virtual
onDisplayModeChanged(oldDisplayMode)	This event method is called when the display mode of a web part is changed. virtual
onDispose()	This API should be used to refresh the contents of the PropertyPane. virtual
onInit()	This event method is called when the web part is initialized. virtual
onPropertyPaneConfigurationComplete()	This API is invoked when the configuration is completed on the PropertyPane. virtual
onPropertyPaneConfigurationStart()	This event method is invoked when the configuration starts on the PropertyPane. virtual
onPropertyPaneFieldChanged(propertyPath, oldValue, newValue)	This API is invoked after updating the new value of the property in the property bag when the PropertyPane is being used in Reactive mode. virtual
onPropertyPaneRendered()	This API is invoked when the PropertyPane is rendered. virtual

Constructor Details

(constructor)()

Constructor for the BaseWebPart class.

constructor();

Remarks

It is highly recommended that the web part use the OnInit API to perform any web part specific initialization. Most of the web part features like this.context and this.properties are not available to be used before the the onInit part of the web part loading lifecycle.

Property Details

accessibleTitle

This property points to the accessible title of web part made available to screen readers. The base implementation returns that default title in the manifest. Web parts that want to provide more descriptive title containing contextual information need to override this API. virtual

protected get accessibleTitle(): string;

Property Value

string

context

Use the context object to access common services and state associated with the component.

readonly context: BaseWebPartContext;

Property Value

BaseWebPartContext

Remarks

Child classes are expected to override this field by redeclaring it with a specialized type. It is meant to be a read-only property; the type cannot be declared as read-only in the base class (because it is initialized outside the constructor), but child classes should redeclare it as readonly.

dataVersion

The value of this property is stored in the serialized data of the web part to allow developers to manage versioning of their web part. The default version is 1.0

protected get dataVersion(): Version;

Property Value

Version

description

Description of the WebPart

protected get description(): string;

Property Value

string

disableReactivePropertyChanges

This property is used to change the web part's property pane interaction from Reactive to NonReactive. virtual

protected get disableReactivePropertyChanges(): boolean;

Property Value

boolean

Remarks

The default behavior is Reactive.

Reactive implies that changes made in the PropertyPane are transmitted to the web part instantly and the user can see instant updates. This helps the page creator get instant feedback and decide if they should keep the new configuration changes or not.

NonReactive implies that the configuration changes are transmitted to the web part only after "Apply" PropertyPane button is clicked.

displayMode

This property is the current display mode of the web part.

get displayMode(): DisplayMode;

Property Value

DisplayMode

previewImageUrl

This property points to the preview image for the web part. The base implementation returns undefined. Web parts that want to provide a valid preview image url need to override this API. The preview image url can be used to create a preview of the web part or of the page on which the web part is present. virtual

get previewImageUrl(): string | undefined;

Property Value

string | undefined

properties

This property is the pointer to the custom property bag of the web part.

protected get properties(): TProperties;

Property Value

TProperties

propertiesMetadata

This property defines metadata for the web part 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(): IWebPartPropertiesMetadata | undefined;

Property Value

IWebPartPropertiesMetadata | undefined

Remarks

See IWebPartPropertiesMetadata for more information about how to define metadata

title

Title of the WebPart

protected get title(): string;

Property Value

string

Method Details

getPropertyPaneConfiguration()

This API is used to ger the configuration to build the property pane for the web part. If the web part wants to use the PropertyPane for configuration, this API needs to be overridden and the web part needs to return the configuration for the PropertyPane.

This API is not invoked until the 'loadPropertyPaneResources' promise is resolved.

See IPropertyPane and other PropertyPane integration wiki documentation for more details. virtual

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration;

Returns

IPropertyPaneConfiguration

getTopActionsConfiguration()

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.

Returns the configuration for this webpart's top actions or undefined if the webpart doesn't support top actions.

getTopActionsConfiguration(): ITopActions | undefined;

Returns

ITopActions | undefined

loadPropertyPaneResources()

This API enables asynchronous loading of property pane related resources of the web part.

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

Returns

Promise<void>

Remarks

If not overridden by the web part, base web part resolves the promise immediately.

This method is called before any property pane APIs are called. Other property pane APIs cannot be called until this promise is resolved. No other property pane related events are raised except 'PropertyPaneConfigurationComplete'.

'PropertyPaneConfigurationComplete' event can be raised to clean up any pending resources including 'loadPropertyPaneResources' promise.

onAfterDeserialize(deserializedObject, dataVersion)

This API is called after the web part is deserialized to an object, right before the property bag is populated. virtual

protected onAfterDeserialize(deserializedObject: any, dataVersion: Version): TProperties;

Parameters

deserializedObject

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 web part

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 web part. Web parts can define their data version by overriding the dataVersion property.

Returns

TProperties

The property bag of the web part

Remarks

The default implementation is a no-op. A web part developer can override this API if the deserialized object does not fully reflect the initial state of the property bag. This gives the web part 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 web part may load the data that was serialized by an older version of the web part 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.

onAfterPropertyPaneChangesApplied()

This API is invoked after the changes made on the PropertyPane are applied when the PropertyPane is used in Non-Reactive mode. This API is not invoked when the PropertyPane is used in Reactive mode. virtual

protected onAfterPropertyPaneChangesApplied(): void;

Returns

void

onBeforeSerialize()

This event method is called before the web part is serialized. virtual

protected onBeforeSerialize(): void;

Returns

void

Remarks

The default implementation is a no-op. The serialization process serializes the web part property bag i.e. this.properties. This API gives the web part a chance to update it's property bag before the serialization happens. Some web part's may keep their state other objects or even in the DOM. If a web part needs to persist some of that state, it needs to override this API and update the web part property bag to the latest state. If a web part updates the property bag with invalid property values, those will get persisted. So that should be avoided. The web part property bag should always contain valid property values.

onDisplayModeChanged(oldDisplayMode)

This event method is called when the display mode of a web part is changed. virtual

protected onDisplayModeChanged(oldDisplayMode: DisplayMode): void;

Parameters

oldDisplayMode

DisplayMode

The old display mode.

Returns

void

Remarks

The default implementation of this API calls the web part render method to re-render the web part with the new display mode. If a web part developer does not want a full re-render to happen on display mode change, they can override this API and perform specific updates to the web part DOM to switch its display mode.

If the web part is initialized or re-initialized when switching to a different display mode then this lifecycle method is not called. Example: SharePoint Site Page.

onDispose()

This API should be used to refresh the contents of the PropertyPane. virtual

protected onDispose(): void;

Returns

void

Remarks

This API is called at the end of the web part lifecycle on a page. It should be used to dispose any local resources (i.e. DOM elements) that the web part is holding onto. This API is expected to be called in scenarios like page navigation i.e. the host is transitioning from one page to another and disposes the page that is being transitioned out.

onInit()

This event method is called when the web part is initialized. virtual

protected onInit(): Promise<void>;

Returns

Promise<void>

Remarks

This API should be overridden to perform long running operations e.g. data fetching from a remote service before the initial rendering of the web part. The loading indicator is displayed during the lifetime of this method. This API is called only once during the lifecycle of a web part.

onPropertyPaneConfigurationComplete()

This API is invoked when the configuration is completed on the PropertyPane. virtual

protected onPropertyPaneConfigurationComplete(): void;

Returns

void

Remarks

This event method is invoked in the following cases:

• When the CONFIGURATION_COMPLETE_TIMEOUT((currently the value is 5 secs) elapses after the last change.

• When user clicks the "X" (close) button before the CONFIGURATION_COMPLETE_TIMEOUT elapses.

• When user clicks the 'Apply' button before the CONFIGURATION_COMPLETE_TIMEOUT elapses.

• When the user switches web parts then the current web part gets this event.

onPropertyPaneConfigurationStart()

This event method is invoked when the configuration starts on the PropertyPane. virtual

protected onPropertyPaneConfigurationStart(): void;

Returns

void

Remarks

This event method is invoked in the following cases:

• When the PropertyPane is opened.

• When the user switches web parts then the new web part gets this event.

onPropertyPaneFieldChanged(propertyPath, oldValue, newValue)

This API is invoked after updating the new value of the property in the property bag when the PropertyPane is being used in Reactive mode. 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

onPropertyPaneRendered()

This API is invoked when the PropertyPane is rendered. virtual

protected onPropertyPaneRendered(): void;

Returns

void