IWebPartPropertyMetadata interface

This is the structure used for map values in IWebPartPropertiesMetadata

Properties

dynamicPropertyType

If specified, indicates that the property is a dynamic property and the type of the dynamic property.

isHtmlString

Indicates whether the property should be serialized as HTML.

isImageSource

Indicates if the property contains a link. This allows SharePoint server to treat the value as such and perform services like link fix-up, search indexing, loading from CDN, etc.

isLink

Indicates if the property contains a link. This allows SharePoint server to treat the value as such and perform services like search indexing, link fix-up, loading from CDN, etc.

isSearchablePlainText

Indicates if the property contains plain text that should be search-indexed by SharePoint.

shouldNotPersist

Indicates if the framework should persist the property on the server.

Property Details

dynamicPropertyType

If specified, indicates that the property is a dynamic property and the type of the dynamic property.

dynamicPropertyType?: 'boolean' | 'number' | 'string' | 'array' | 'object';

Property Value

'boolean' | 'number' | 'string' | 'array' | 'object'

Remarks

If a web part has properties that are dynamically configurable, then use this flag to declare the property as a dynamic property by specifying its type. When a property specifies its dynamic property type, then the framework ensures that its value can be accessed using 'tryGetValue' anytime in the life cycle of the web part. If a property is marked as DynamicProperty in the IWebPartProperties interface, but does not appear in the IWebPartPropertiesMetadata with a dynamicPropertyType, then the web part developer will need to manually create the DynamicProperty themselves and assign it to the property.

A web part can configure a default value for the property by specifying it in the properties section of the web part's manifest. This value will be used when a dynamic property is constructed for the property.

Note: Web parts should be able to type cast the resultant value from the tryGetValue to suit their needs.

isHtmlString

Indicates whether the property should be serialized as HTML.

isHtmlString?: boolean;

Property Value

boolean

Remarks

This flag instructs framework to store the value as HTML, so that SharePoint can perform the following services on it:

  • normalizing HTML encodings

  • stripping unsafe HTML tags (i.e. for usage with Element.innerHTML)

  • search indexing

  • SharePoint link fix-up

Only enable this flag for HTML content where these modifications are acceptable. If non-HTML content is provided, SharePoint framework might make modifications to convert it to HTML valid. For plain text content that simply needs to be exposed to the search index (without any rewriting), use the isSearchablePlainText flag instead.

isImageSource

Indicates if the property contains a link. This allows SharePoint server to treat the value as such and perform services like link fix-up, search indexing, loading from CDN, etc.

isImageSource?: boolean;

Property Value

boolean

Indicates if the property contains a link. This allows SharePoint server to treat the value as such and perform services like search indexing, link fix-up, loading from CDN, etc.

isLink?: boolean;

Property Value

boolean

isSearchablePlainText

Indicates if the property contains plain text that should be search-indexed by SharePoint.

isSearchablePlainText?: boolean;

Property Value

boolean

Remarks

This flag instructs the framework to store the property in a representation that supports search indexing. The content will be treated as plain text; SharePoint will not modify the string in any way, and special HTML characters may be stored encoded and appear in search results. If your string contains HTML markup, use the isHtmlString setting instead.

Security note: For security reasons, never assign a plain text string to Element.innerHTML.

shouldNotPersist

Indicates if the framework should persist the property on the server.

shouldNotPersist?: boolean;

Property Value

boolean

Remarks

Use this for properties that are only important in run-time, and do not need to persist on the server. This can reduce the size of the serialized data of the web part and optimize the web part load time. The property value will be removed from the serialized data sent to the server, but this has no effect on the run-time property bag. The property value will still be available in the onBeforeSerialize() method, and the value will not be cleared from the run-time property bag. The initial render of your web part should not depend on the value of the property. Setting a default value for the property can be done in onInit() method.

Note that if the property path refers to a property that has a complex object as the value, the whole object will be removed from the persisted data.