BaseWebPart class

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
Implements
IPropertyPaneConsumer

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.

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.

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.

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.

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.

onAfterDeserialize(deserializedObject, dataVersion)

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

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.

onBeforeSerialize()

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

onDisplayModeChanged(oldDisplayMode)

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

onDispose()

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

onInit()

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

onPropertyPaneConfigurationComplete()

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

onPropertyPaneConfigurationStart()

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

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.

onPropertyPaneRendered()

This API is invoked when the PropertyPane is rendered.

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.

protected readonly accessibleTitle: string;

Property Value

string

context

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

protected readonly context: BaseWebPartContext;

Property Value

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 readonly dataVersion: Version;

Property Value

description

Description of the WebPart

protected readonly description: string;

Property Value

string

disableReactivePropertyChanges

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

protected readonly 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.

protected readonly displayMode: DisplayMode;

Property Value

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.

protected readonly previewImageUrl: string | undefined;

Property Value

string | undefined

properties

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

protected readonly 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.

protected readonly propertiesMetadata: IWebPartPropertiesMetadata | undefined;

Property Value

IWebPartPropertiesMetadata | undefined

Remarks

See IWebPartPropertiesMetadata for more information about how to define metadata

title

Title of the WebPart

protected readonly 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.

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration;

Returns

onAfterDeserialize(deserializedObject, dataVersion)

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

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.

protected onAfterPropertyPaneChangesApplied(): void;

Returns

void

onBeforeSerialize()

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

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.

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.

onDispose()

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

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.

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.

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.

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.

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.

protected onPropertyPaneRendered(): void;

Returns

void