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
Constructors
| (constructor)() | Constructor for the |
Properties
| accessible |
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. |
| data |
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 |
| disable |
This property is used to change the web part's property pane interaction from Reactive to NonReactive. virtual |
| display |
This property is the current display mode of the web part. |
| preview |
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. |
| properties |
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
| get |
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 |
| get |
Returns the configuration for this webpart's top actions or undefined if the webpart doesn't support top actions. |
| load |
This API enables asynchronous loading of property pane related resources of the web part. |
| on |
This API is called after the web part is deserialized to an object, right before the property bag is populated. virtual |
| on |
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 |
| on |
This event method is called before the web part is serialized. virtual |
| on |
This event method is called when the display mode of a web part is changed. virtual |
| on |
This API should be used to refresh the contents of the PropertyPane. virtual |
| on |
This event method is called when the web part is initialized. virtual |
| on |
This API is invoked when the configuration is completed on the PropertyPane. virtual |
| on |
This event method is invoked when the configuration starts on the PropertyPane. virtual |
| on |
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 |
| on |
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
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
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
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
getTopActionsConfiguration()
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 inconsistent 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