BaseClientSideWebPart class

Package:

@microsoft/sp-webpart-base

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<TProperties>

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.
width	This property returns the width of the container for the web part.

Methods

clearError()	This API should be used to clear the error message from the web part display area.
onAfterResize(newWidth)	This API is invoked when the web part container dom element width is changed, e.g. when the browser browser window is resized and when the property pane is toggled open/closed.
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.
onThemeChanged(theme)	This API is called when a theme is initialized or changed on the page or for the current section.
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(error, didUpdate)	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 get 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.

readonly context: WebPartContext;

Property Value

WebPartContext

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 get domElement(): HTMLElement;

Property Value

HTMLElement

isRenderAsync

Indicates whether the web part is rendering in Async mode.

/** @virtual */
protected get 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 get 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 get renderedOnce(): boolean;

Property Value

boolean

width

This property returns the width of the container for the web part.

protected get width(): number;

Property Value

number

Remarks

Web parts should utilize this property to perform operations such as any conditional styling of components based on the initial available width for the web part.

Method Details

clearError()

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

protected clearError(): void;

Returns

void

onAfterResize(newWidth)

This API is invoked when the web part container dom element width is changed, e.g. when the browser browser window is resized and when the property pane is toggled open/closed.

/** @virtual */
protected onAfterResize(newWidth: number): void;

Parameters

newWidth

number

Width (in pixels) of the container for the web part after the resize event.

Returns

void

Remarks

Web parts should utilize this method to perform operations such as potentially re-rendering components based on the new available width for the web part.

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.

onThemeChanged(theme)

This API is called when a theme is initialized or changed on the page or for the current section.

/** @virtual */
protected onThemeChanged(theme: IReadonlyTheme | undefined): void;

Parameters

theme

IReadonlyTheme | undefined

New theme for the page or section

Returns

void

Remarks

Developers sould not call render in overridden method. It can lead to unpredicted re-flow of the web part. render will be called from the base class when needed.

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(error, didUpdate)

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(error?: Error, didUpdate?: boolean): void;

Parameters

error

Error

error object indicating async render has completed with an error

didUpdate

boolean

used to override end performance time with sync render time

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