BaseClientSideWebPart class

This abstract class implements the the base functionality for a client-side web part. Every client-side web part needs to inherit from this class.

Extends
BaseWebPart

Remarks

Along with the base functionality, this class provides some APIs that can be used by the web part. These APIs fall in two catagories.

The first category of APIs provide data and functionality. Example, the web part context (i.e. this.context). This API should be used to access contextual data relevant to this web part instance.

The second category of APIs provide a base implementation for the web part lifecycle and can be overridden for an updated implementation. The render() API is the only API that is mandatory to be implemented/overridden by a web part. All other life cycle APIs have a base implementation and can be overridden based on the needs of the web part. Please refer to the documentation of the individual APIs to make the right decision.

Constructors

(constructor)()

Constructor for the BaseClientSideWebPart class.

Properties

canOpenPopupOnRender

This property indicates whether a web part can open a popup on initial render.

context

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

domElement

This property is a pointer to the root DOM element of the web part. This is a DIV element and contains the whole DOM subtree of the web part.

isRenderAsync

Indicates whether the web part is rendering in Async mode.

renderedFromPersistedData

This property indicates whether the web part was rendered from the persisted data (serialized state from the last time that the web part was saved) or not.

renderedOnce

This property indicates whether the web part has been rendered once or not. After the first time rendering, the value of this property is always true until a full re-render of the web part happens.

Methods

clearError()

This API should be used to clear the error message from the web part display area.

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.

render()

This API is called to render the web part. There is no base implementation of this API and the web part is required to override this API.

renderCompleted()

This API should be called by web parts that perform Async rendering. Those web part are required to override the isRenderAsync API and return true. One such example is web parts that render content in an IFrame. The web part initiates the IFrame rendering in the render() API but the actual rendering is complete only after the iframe loading completes.

renderError(error)

This API should be used to render an error message in the web part display area. Also logs the error message using the trace logger.

Constructor Details

(constructor)()

Constructor for the BaseClientSideWebPart 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

canOpenPopupOnRender

This property indicates whether a web part can open a popup on initial render.

protected readonly canOpenPopupOnRender: boolean;

Property Value

boolean

Remarks

In some environments the host re-renders the web parts frequently, and therefore opening popups during render will cause popups to open repeatedly, which is a poor user experience. As an example, the classic SharePoint pages perform postbacks causing the page to re-render on all button clicks.

If a web part needs to open a popup on render, it should use this API before opening the popup. If this API returns false, the web part should not open popup on initial render. Some web parts that open popups during render are the document embed web part that pops up the file picker on initial render, embedded video web part that pops up the PropertyPane on initial render.

context

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

protected readonly context: WebPartContext;

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.

domElement

This property is a pointer to the root DOM element of the web part. This is a DIV element and contains the whole DOM subtree of the web part.

protected readonly domElement: HTMLElement;

Property Value

HTMLElement

isRenderAsync

Indicates whether the web part is rendering in Async mode.

/** @virtual */
protected readonly isRenderAsync: boolean;

Property Value

boolean

Remarks

If the web part overrides this field to return true, then it needs to call renderCompleted API after the web part rendering is complete.

The default value is false.

renderedFromPersistedData

This property indicates whether the web part was rendered from the persisted data (serialized state from the last time that the web part was saved) or not.

protected readonly renderedFromPersistedData: boolean;

Property Value

boolean

Remarks

Example: When web part is added for the first time using toolbox then the value is false.

renderedOnce

This property indicates whether the web part has been rendered once or not. After the first time rendering, the value of this property is always true until a full re-render of the web part happens.

protected readonly renderedOnce: boolean;

Property Value

boolean

Method Details

clearError()

This API should be used to clear the error message from the web part display area.

protected clearError(): void;

Returns

void

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.

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.

render()

This API is called to render the web part. There is no base implementation of this API and the web part is required to override this API.

protected abstract render(): void;

Returns

void

renderCompleted()

This API should be called by web parts that perform Async rendering. Those web part are required to override the isRenderAsync API and return true. One such example is web parts that render content in an IFrame. The web part initiates the IFrame rendering in the render() API but the actual rendering is complete only after the iframe loading completes.

protected renderCompleted(): void;

Returns

void

renderError(error)

This API should be used to render an error message in the web part display area. Also logs the error message using the trace logger.

protected renderError(error: Error): void;

Parameters

error
Error

An error object containing the error message to render.

Returns

void