Wagtail client-side components
    Preparing search index...

    Class PreviewController

    Controls the preview panel component to submit the current form state and update the preview iframe if the form is valid.

    Dispatches the following events in this order.

    PreviewController#update - Before sending the preview data to the server. Cancelable.

    PreviewController#json - After the preview data update request is completed.

    PreviewController#error - When an error occurs while updating the preview data.

    PreviewController#load - Before reloading the preview iframe. Cancelable.

    PreviewController#loaded - After the preview iframe has been reloaded.

    PreviewController#content - When the content of the preview iframe is extracted to be analyzed.

    PreviewController#ready - When the preview is ready for further updates – only fired on initial load.

    PreviewController#updated - After an update cycle is finished – may or may not involve reloading the iframe.

    PreviewController#update

    Hierarchy

    Index

    Constructors

    constructor

    Properties

    a11yRowTemplate autoUpdateIntervalValue available axeConfig checksPanel checksPanelCounter checksSidePanel checksToggleCounter contentChecksEnabled contentChecksPromise contentExtractorOptions context deviceLocalStorageKeyValue deviceWidthPropertyValue editForm hasErrorsClass hasModeTarget hasNewTabTarget hasSpinnerTarget hasWProgressOutlet iframeTarget iframeTargets modeTarget newTabTarget panelWidthPropertyValue proxyClass ready reloadPromise renderUrlValue resizeObserver selectedSizeClass setPreviewDataLazy sidePanelContainer sizeTargets spinnerTarget spinnerTimeout staleValue updatePromise urlValue wProgressOutlet blessings classes fallbackWidth outlets scrollRestoreTimeout targets values

    Accessors

    activeSizeInput application classes data element identifier outlets renderUrl scope shouldAutoUpdate targets shouldLoad

    Methods

    applySelectedSizeClass autoUpdateIntervalValueChanged checkAndUpdatePreview clearPreviewData connect disconnect dispatch extractContent finishUpdate initialize observePanelSize openPreviewInNewTab reloadIframe renderUrlValueChanged replaceIframe restoreLastSavedPreferences restoreScrollPosition runAccessibilityChecks runChecks runContentChecks setPreviewData setPreviewDataWithAlert setPreviewMode setPreviewWidth setStale setUpContentChecks staleValueChanged togglePreviewSize updateNewTabLink afterLoad

    Constructors

    • Parameters

      • context: Context

      Returns PreviewController

    Properties

    a11yRowTemplate: HTMLTemplateElement | null

    Template for rendering a row of accessibility check results.

    autoUpdateIntervalValue: number

    Interval in milliseconds when the form is checked for changes. Also used as the debounce duration for the update request.

    available: boolean = true

    Whether the preview is currently available. This is used to distinguish whether we are rendering a preview or the "Preview is not available" screen. So even if the preview is currently outdated, this is still true as long as the preview data is available and the preview is rendered (e.g. if the form becomes invalid after the preview is successfully rendered).

    axeConfig: WagtailAxeConfiguration | null

    Configuration for Axe.

    checksPanel: HTMLElement | null

    Container for rendering content checks results.

    checksPanelCounter: HTMLElement | null

    Content checks counter inside the checks panel.

    checksSidePanel: HTMLDivElement | null

    Side panel for content checks.

    checksToggleCounter: HTMLElement | null

    Content checks counter on the side panel toggle.

    contentChecksEnabled: boolean

    Whether content checks are enabled.

    contentChecksPromise: Promise<void> | null = null

    Promise for the current content checks request. This resolved when both the content checks and the accessibility checks are completed. Useful for queueing the checks, as Axe does not allow concurrent runs.

    contentExtractorOptions: ContentExtractorOptions

    Configuration for Wagtail's Axe content extractor plugin instance.

    context: Context
    deviceLocalStorageKeyValue: string

    Key for storing the last selected device size in localStorage.

    deviceWidthPropertyValue: string

    CSS property for setting the device width.

    editForm: HTMLFormElement

    Main editor form.

    hasErrorsClass: string

    CSS class to indicate that there are errors in the form.

    hasModeTarget: boolean
    hasNewTabTarget: boolean
    hasSpinnerTarget: boolean
    hasWProgressOutlet: boolean
    iframeTarget: HTMLIFrameElement

    The main preview <iframe> that is currently displayed.

    iframeTargets: HTMLIFrameElement[]

    All preview <iframe>s that are currently in the DOM. This contains the currently displayed <iframe> and may also contain the new <iframe> that will replace the current one.

    modeTarget: HTMLSelectElement

    Preview mode <select> element.

    newTabTarget: HTMLAnchorElement

    New tab button.

    panelWidthPropertyValue: string

    CSS property for the current width of the panel, to maintain the device scaling.

    proxyClass: string

    CSS class for elements that are invisible and only rendered for functionality purposes.

    ready: boolean = false

    Whether the preview is ready for further updates.

    The preview data is stored in the session, which means:

    • After logging out and logging back in, the session is cleared, so the client must send the preview data on initial editor load in order for Wagtail to render the preview.
    • The preview data can persist after a full-page reload, as long as they use the same key in the session.

    To ensure the preview data is available when the preview panel is opened, we send an update request immediately. This can result in two scenarios:

    In edit views, the form is usually valid on initial load, as the object was successfully saved before. In this case, we can go ahead with rendering the preview and updating it with any new data.

    However, there may be cases where the form is invalid on initial load, e.g. if the "expiry date" in the publishing schedule has become in the past. Another common example is in create views, where the form is likely invalid on initial load due to missing required fields (e.g. title).

    When this happens, Wagtail will not update the preview data in the session, which means it may still contain the outdated preview data from the previous full-page load. We want to clear this data immediately so that the preview panel displays the "Preview is not available" screen instead of an outdated preview.

    This flag determines whether the preview is "ready" for further updates – i.e. this is true if the preview data has been cleared after an invalid initial load, or if the preview data is already valid on initial load.

    An alternative approach would be to handle the initial state of the session's preview data in the backend, but this would require the logic to be applied in all the different places (i.e. page and snippets create and edit views).

    reloadPromise: Promise<void> | null = null

    Promise for the current iframe reload. This is resolved when the new iframe's load event is fired and the scroll position has been restored.

    renderUrlValue: string

    URL for rendering the preview, defaults to urlValue. Useful for headless setups where the front-end may be hosted at a different URL.

    resizeObserver: ResizeObserver

    ResizeObserver to observe when the panel is resized so we can maintain the device size scaling.

    selectedSizeClass: string

    CSS class for the currently selected device size.

    setPreviewDataLazy: DebouncibleFunction<() => Promise<boolean> | undefined>
    sidePanelContainer: HTMLDivElement

    Side panel element of the preview panel, i.e. the element with the data-side-panel attribute. Useful for listening to show/hide events. Normally, this is the parent element of the controller element.

    sizeTargets: HTMLInputElement[]

    Device size <input type="radio"> elements.

    spinnerTarget: HTMLDivElement

    Loading spinner.

    spinnerTimeout: Timeout | null = null

    Timeout before displaying the loading spinner.

    staleValue: boolean

    Whether the preview data is considered stale and needs an update.

    updatePromise: Promise<boolean> | null = null

    Promise for the current update request. This is resolved as soon as the update request is successful, so the preview iframe may not have been fully reloaded.

    urlValue: string

    URL for updating the preview data. Also used for rendering the preview if renderUrlValue is unset.

    wProgressOutlet: ProgressController

    ProgressController for the refresh button that may be displayed when auto-update is turned off.

    blessings: (<T>(constructor: Constructor<T>) => any)[]
    classes: string[] = ...
    fallbackWidth: string = ...

    The device size width to use when the preview is not available.

    outlets: string[] = ...
    scrollRestoreTimeout: number = 10_000

    The time tolerance between the iframe's load event and the scroll restoration completion, which may not be instantaneous for cross-domain preview iframes.

    targets: string[] = ...
    values: {
        autoUpdateInterval: { default: number; type: NumberConstructor };
        deviceLocalStorageKey: { default: string; type: StringConstructor };
        deviceWidthProperty: { default: string; type: StringConstructor };
        panelWidthProperty: { default: string; type: StringConstructor };
        renderUrl: { default: string; type: StringConstructor };
        stale: { default: boolean; type: BooleanConstructor };
        url: { default: string; type: StringConstructor };
    } = ...

    Accessors

    • get application(): Application

      Returns Application

    • get classes(): ClassMap

      Returns ClassMap

    • get data(): DataMap

      Returns DataMap

    • get element(): ElementType

      Returns ElementType

    • get identifier(): string

      Returns string

    • get outlets(): OutletSet

      Returns OutletSet

    • get scope(): Scope

      Returns Scope

    • get targets(): TargetSet

      Returns TargetSet

    • get shouldLoad(): boolean

      Returns boolean

    Methods

    • Applies the selected size class to the specified device input's label, and removes the class from all other device inputs' labels.

      Parameters

      • device: string

        Selected device name

      Returns void

    • Like setPreviewData, but only updates the preview if the form has not changed.

      Returns Promise<boolean | null | undefined>

      whether the data is valid

    • Parameters

      • eventName: string
      • Optional__namedParameters: Partial<
            {
                bubbles: boolean;
                cancelable: boolean;
                detail: Object;
                prefix: string;
                target: Element
                | Window
                | Document;
            },
        >

      Returns CustomEvent<Object>

    • Like setPreviewDataWithAlert, but also opens the preview in a new tab. If an existing tab for the preview is already open, it will be focused and reloaded.

      Parameters

      Returns Promise<boolean | undefined>

      whether the data is valid

    • Reloads the preview iframe.

      Instead of reloading the iframe with iframe.contentWindow.location.reload() or updating the src attribute, this works by creating a new iframe that replaces the old one once the new one has been loaded. This prevents the iframe from flashing when reloading.

      Returns void

    • Restores the last saved preferences. Currently, only the last selected device size is restored.

      Returns void

    • Restores the scroll position from the old iframe to the new one. For same-origin iframes, this is done by calling scroll() on the new iframe's content window with the scroll position of the old iframe. For cross-origin iframes, this is done by using the postMessage API to request the scroll position from the old iframe and send it to the new one.

      Parameters

      Returns Promise<void>

      a Promise that resolves when the scroll position is restored or the timeout has lapsed.

    • Runs the content and accessibility checks. This is called when the iframe sends a message event from the userbar indicating that it has finished running the checks within itself.

      Parameters

      • Optionalevent: MessageEvent<{ wagtail: { type: string } }>

        The message event from the userbar

      Returns Promise<void | null>

    • Updates the preview data in the session. If the data is valid, the preview iframe will be reloaded. If the data is invalid, the preview panel will display an error message.

      Returns Promise<boolean> | undefined

      whether the data is valid

    • Like setPreviewData, but also displays an alert if an error occurred while updating the preview data. Note that this will not display an alert if the update request was successful, but the data is invalid.

      This is useful when the preview data is updated in response to a user interaction, such as:

      • clicking the "open in new tab" link
      • clicking the "Refresh" button (if auto update is disabled)
      • changing the preview mode.

      Returns Promise<boolean | undefined>

      whether the data is valid

    • Sets the simulated device width of the preview iframe.

      Parameters

      • Optionalwidth: string

        The width of the preview device. If falsy:

        • the default size will be used if the preview is currently unavailable,
        • otherwise, the currently selected device size is used.

      Returns void

    • Marks the preview data as stale, indicating it needs an update. Accepts an optional stale parameter to explicitly override the value.

      Parameters

      • Optionalevent: Event & { params?: { stale: boolean } }

      Returns void

    • Toggles the preview size based on the selected input. The selected device name (input[value]) is stored in localStorage.

      Parameters

      Returns void

    • Parameters

      • _identifier: string
      • _application: Application

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods