@microsoft/sp-webpart-base/lib/core/WebPartDataConverter.d.ts

SharePoint Framework support for building web parts

import { type ISerializedServerProcessedData } from '@microsoft/sp-component-base';
import type IWebPartData from './IWebPartData';
/**
 * On the client, we need to support both HTML and and JSON format of the web part data. This is a utility
 * class to perform conversion between the two formats.
 *
 * @internal
 */
export declare class WebPartDataConverter {
    private static _componentIdAttribute;
    private static _htmlPropertiesAttribute;
    private static _propNameAttribute;
    private static _searchablePlainTextAttribute;
    private static _webPartAttribute;
    private static _webPartDataAttribute;
    private static _webPartDataVersionAttribute;
    private static _tempDoc;
    private static _wpDiv;
    private static _wpComponentIdDiv;
    private static _wpHtmlPropsDiv;
    private static _linkPlaceHolderRegex;
    /**
     * A temporary document detached from the main document for HTML parsing (call createElement on this)
     *
     * Note: Using document.createElement will create the element on the running document of the page which is
     * dangerous, because when you set innerHTML on the element the content will immediately run on the page.
     * That causes a security issue because we might be parsing something that has a <script> tag (XSS attack).
     * In case of <img> tags, the image gets downloaded immediately which is also unwanted behavior. So, for
     * parsing purposes, we should never use document.createElement and insead use this._parsingDocument.createElement.
     *
     */
    private static get _parsingDocument();
    /**
     * Is this string a html web part data ?
     */
    static isWebPartHtml(htmlString: string): boolean;
    /**
     * Converts an instance of IWebPartData to is corresponding persisted HTML element.
     * See WebPartDataConverter tests for examples.
     */
    static convertWebPartDataToHtml(webpartData: IWebPartData): string;
    /**
     * Converts persisted html element for a web part to its corresponding IWebPartData instance.
     *
     * @remarks
     * Returns undefined in case of bad input.
     * See WebPartDataConverter tests for examples
     *
     * @param htmlString - html formatted web part data.
     * @param links - (optional) Array of the fixed up links. If provided, the values in this array
     *   take over the values in the HTML markup.
     */
    static convertHtmlToWebPartData(htmlString: string, links?: string[]): IWebPartData | undefined;
    /**
     * Convert server process data to an equivalent HTML stirng format that the SharePoint server
     * can process for search indexing, link fixup and SafeHTML processing.
     *
     * @remarks
     * HtmlStrings are search indexed. Links and ImageSources are setup for link fixup. All of these are
     * search indexed and passed through SafeHtml processing to sanitize the content.
     *
     * This method is expected to provide reverse processing as compared to `convertHtmltoServerProcessedData`.
     *
     * Input:
     *
     * ```
     * {
     *   htmlStrings: { 'prop1': 'value_of_prop1' },
     *   links: { 'prop2': 'http://www.contoso.com/page1.aspx' },
     *   imageSources: { 'prop3': 'http://www.contoso.com/imag.png' }
     * }
     * ```
     *
     * Output:
     *
     * ```
     * "<div data-sp-prop-name='prop1'>value_of_prop1</div>
     *  <link data-sp-prop-name='prop2' href='http://www.contoso.com/page1.aspx'>
     *  <img data-sp-prop-name='prop3' src='http://www.contoso.com/image.png'>"
     * ```
     */
    static convertServerProcessedDataToHtml(serverContent: ISerializedServerProcessedData | undefined): string;
    /**
     * Convert an HTML string to its equivalent ISerializedServerProcessedData structure format.
     *
     * @remarks
     * This method is expected to provide reverse processing as compared to convertServerProcessedDataToHtml.
     *
     * Input:
     *
     * ```
     * "<div data-sp-prop-name='prop1'>value_of_prop1</div>
     *  <link data-sp-prop-name='prop2' href='http://www.contoso.com/page1.aspx'>
     *  <img data-sp-prop-name='prop3' src='http://www.contoso.com/image.png'>"
     * ```
     *
     * Output:
     *
     * ```
     * {
     *   htmlStrings: { 'prop1': 'value_of_prop1' },
     *   links: { 'prop2': 'http://www.contoso.com/page1.aspx' },
     *   imageSources: { 'prop3': 'http://www.contoso.com/imag.png' }
     * }
     * ```
     *
     * Array of the fixed up links. If provided, the values in this array take over the values in the HTML markup.
     */
    static convertServerProcessedHtmlToData(htmlString: string, links?: string[]): ISerializedServerProcessedData;
    private static _convertServerProcessedDataToHtmlByType;
    /**
     * Get the HTML equivalent string for a server processed prop type.
     */
    private static _getHtmlString;
    /**
     * We need to send valid html from client, because server should understand it to perform services. This method
     * normalizes html by doing basic validations and removing script tags. Returns empty string if passed invalid HTML.
     * Note that this is not a strict html validation, it just needs to make sure the page doesn't break so the
     * html value (or a valid part of it) gets to server for proper validation and sanitization
     */
    private static _normalizeHTML;
    private static _initializeIfNeeded;
    /**
     * Extract the link by processing the links array and the index in the data-sp-splink attribute whose
     * value should be of the format  `__SPLINK__<index>__` where index is the index in the links array.
     */
    private static _extractSPLink;
}
export default WebPartDataConverter;
//# sourceMappingURL=WebPartDataConverter.d.ts.map