PlaceholderProvider class
Allows third-party components to discover and use SharePoint placeholders. Placeholders enable third-party components to render custom content into designated regions on the page.
Remarks
Placeholders are designated regions on the page, identified by one of the predefined PlaceholderName constants. Different applications and pages might support different placeholder names. Placeholders can appear and disappear as the user interacts with the page, for example via in-place navigation. Third-party components should not assume that a given placeholder will always be available.
Use PlaceholderProvider.tryCreateContent() to test whether a placeholder is available and add content to it. Use the PlaceholderProvider.changedEvent event to discover when new placeholders appear.
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the PlaceholderProvider class.
Properties
| is |
|
| placeholder |
Returns the names of the currently available placeholders. |
Methods
| dispose() | |
| try |
Tests whether the page contains the specified placeholder. If so, a new PlaceholderContent object is created, which allows the caller to render custom content inside the placeholder. |
Events
| changed |
This event is raised when the list of currently available placeholders is changed. |
Property Details
isDisposed
get isDisposed(): boolean;Property Value
boolean
placeholderNames
Returns the names of the currently available placeholders.
get placeholderNames(): ReadonlyArray<PlaceholderName>;Property Value
ReadonlyArray<PlaceholderName>
Method Details
dispose()
dispose(): void;Returns
void
tryCreateContent(name, options)
Tests whether the page contains the specified placeholder. If so, a new PlaceholderContent object is created, which allows the caller to render custom content inside the placeholder.
tryCreateContent(name: PlaceholderName, options?: IPlaceholderCreateContentOptions): PlaceholderContent | undefined;Parameters
- name
- PlaceholderName
The requested placeholder
- options
- IPlaceholderCreateContentOptions
Additional options, for example to detect when the placeholder is disposed.
Returns
PlaceholderContent | undefined
A new PlaceholderContent object, or undefined if the requested placeholder does not exist.
Remarks
The host application makes no guarantees about the availability of a given placeholder. In situations where an expected placeholder is not available, the third-party extension must handle it gracefully, e.g. by not rendering anything, or by choosing an alternative placeholder.
Event Details
changedEvent
This event is raised when the list of currently available placeholders is changed.
get changedEvent(): SPEvent<SPEventArgs>;Event Type
Remarks
The application can change its list of available placeholders at any time. This means that the existing placeholders may get disposed or new placeholders may be added. Use this event to discover new placeholders when they appear.