DynamicProperty class

Package:

@microsoft/sp-component-base

Serializable object that simplifies usage of a DynamicProperty.

Remarks

This is built for usage in web part properties, and modified through the property pane. Can be initialized with a default callback. Web parts initialize with the render method so if the 3rd party developer does nothing, a change in the DynamicProperty will re-render the web part automatically.

Constructors

(constructor)(provider, callback)

Create a new DynamicProperty object.

Properties

isDisposed	Returns true if the dispose() method has been called. Once an object is disposed, it remains in this state permanently.
reference	DynamicDataReference string that the DynamicProperty object points to. The reference is of the form <source>:<property>:<path>.

Methods

dispose()	This method is called to permanently dispose the object.
hasDefaultCallback()	Returns true if the object has a default callback.
register(callback)	Registers a callback function for updates on the associated DynamicDataSource.
removeDefaultCallback()	Removes the registration for the default callback.
setReference(reference)	Sets the value of the DynamicProperty to be a reference to a DynamicDynamicSource and property. The reference is of the form <source>:<property>:<path>.
setValue(value)	Sets a static value in the DynamicProperty.
tryGetSource()	Returns the DynamicDataSource that the DynamicProperty object refers to. Returns undefined if the source doesn't exist.
tryGetValue()	Returns the value of the object.
tryGetValues()	Returns the value of the object.
unregister(callback)	Unregisters a callback function for updates on the associated DynamicDataSource. The callback function must be the same it was registered with.

Constructor Details

(constructor)(provider, callback)

Create a new DynamicProperty object.

constructor(provider: DynamicDataProvider, callback?: () => void);

Parameters

provider

DynamicDataProvider

DynamicDataProvider.

callback

() => void

Optional. Default callback to be registered for updates in the DynamicDataSource.

Property Details

isDisposed

Returns true if the dispose() method has been called. Once an object is disposed, it remains in this state permanently.

get isDisposed(): boolean;

Property Value

boolean

Remarks

After the object has been disposed, do not call its methods or access its properties.

reference

DynamicDataReference string that the DynamicProperty object points to. The reference is of the form <source>:<property>:<path>.

get reference(): string | undefined;

Property Value

string | undefined

Remarks

If the DynamicProperty is set up with static data, this returns undefined.

Method Details

dispose()

This method is called to permanently dispose the object.

dispose(): void;

Returns

void

Remarks

After the object has been disposed, do not call its methods or access its properties.

hasDefaultCallback()

Returns true if the object has a default callback.

hasDefaultCallback(): boolean;

Returns

boolean

register(callback)

Registers a callback function for updates on the associated DynamicDataSource.

register(callback: () => void): void;

Parameters

callback

() => void

Callback function to register.

Returns

void

removeDefaultCallback()

Removes the registration for the default callback.

removeDefaultCallback(): void;

Returns

void

Remarks

This can be useful for advanced users who only want their custom callbacks.

setReference(reference)

Sets the value of the DynamicProperty to be a reference to a DynamicDynamicSource and property. The reference is of the form <source>:<property>:<path>.

setReference(reference: string): void;

Parameters

reference

string

Id of the DynamicDataSource and property.

Returns

void

setValue(value)

Sets a static value in the DynamicProperty.

setValue(value: TValue): void;

Parameters

value

TValue

Value for the DynamicProperty.

Returns

void

tryGetSource()

Returns the DynamicDataSource that the DynamicProperty object refers to. Returns undefined if the source doesn't exist.

tryGetSource(): IDynamicDataSource | undefined;

Returns

IDynamicDataSource | undefined

tryGetValue()

Returns the value of the object.

tryGetValue(): TValue | undefined;

Returns

TValue | undefined

the value associated with the dynamic property or undefined if the source or the data doesn't exist.

Remarks

If the value is an array, then the first element of the array is returned; otherwise, the value itself is returned.

NOTE: This api will never return an array. To retrieve an array value, use the DynamicProperty.tryGetValues() API.

tryGetValues()

Returns the value of the object.

tryGetValues(): TValue[];

Returns

TValue[]

the value associated with the dynamic property or an empty array if the source or the data doesn't exist.

Remarks

If the value is NOT an array, then an array is returned with the value being the single entry; otherwise, the value itself is returned. If the property is undefined or cannot be found, an empty array will be returned.

NOTE: This api will always return an array and it assumes that the array is homogeneous. To retrieve a non-array value, use the DynamicProperty.tryGetValue() API.

unregister(callback)

Unregisters a callback function for updates on the associated DynamicDataSource. The callback function must be the same it was registered with.

unregister(callback: () => void): void;

Parameters

callback

() => void

Callback function to unregister.

Returns

void