Wagtail client-side components
    Preparing search index...

    Class SwapController

    Allow for an element to trigger an async query that will patch the results into a results DOM container. The controlled element can be the query input, the containing form, or a button. It supports the ability to update the URL with the query when processed or simply make a query based on a form's values.

    <div id="results"></div>
    <form
      data-controller="w-swap"
      data-action="input->w-swap#submitLazy"
      data-w-swap-src-value="path/to/search"
      data-w-swap-target-value="#results"
    >
      <input id="search" type="text" name="query" />
      <input id="filter" type="text" name="filter" />
    </form>

    Example: - A single input that will update the results & the URL

    <div id="results"></div>
    <form>
      <input
        id="search"
        type="text"
        name="q"
        data-controller="w-swap"
        data-action="input->w-swap#searchLazy"
        data-w-swap-src-value="path/to/search"
        data-w-swap-target-value="#results"
      />
    </form>

    <div id="results"></div>
    <form>
      <button
        id="clear"
        data-controller="w-swap"
        data-action="input->w-swap#replaceLazy"
        data-w-swap-src-value="path/to/results/?type=bar"
        data-w-swap-target-value="#results"
      >
        Clear owner filter
      </button>
    </form>

    Note: This requires a messages controller to be present in the page, which should be available in the base admin template.

    <div id="results"></div>
    <form
      data-controller="w-swap"
      data-action="input->w-swap#submitLazy"
      data-w-swap-messages-value='{"400": "There was a problem with your search input."}'
      data-w-swap-target-value="#results"
    >
      <input id="search" type="text" name="query" />
    </form>

    <div id="results" class="base-class"></div>
    <form
      data-controller="w-swap"
      data-action="input->w-swap#submitLazy"
      data-w-swap-loading-class="is-loading"
      data-w-swap-src-value="path/to/search"
      data-w-swap-target-value="#results"
    >
      <input id="search" type="text" name="query" />
    </form>

    Hierarchy

    Index

    Constructors

    constructor

    Properties

    abortController? context deferValue errorValue hasInputTarget hasJsonPathValue hasTargetValue hasUrlValue iconElement? iconValue inputTarget jsonPathValue loadingClasses loadingValue messagesValue reflectValue replaceLazy? searchLazy? srcValue submitLazy? targetValue waitValue writeDeferred? blessings classes defaultClearParam outlets targets values

    Accessors

    application classes data element formElement identifier outlets scope target targets shouldLoad

    Methods

    connect disconnect dispatch errorValueChanged initialize loadingValueChanged reflectParams replace search submit afterLoad

    Constructors

    • Parameters

      • context: Context

      Returns SwapController

    Properties

    abortController?: AbortController

    Allow cancelling of in flight async request if disconnected.

    context: Context
    deferValue: boolean

    Defer writing the results while there is interaction with the target container.

    errorValue: string

    Tracking of the active error key (e.g. 'error 400') for dispatching & clearing error messages.

    hasInputTarget: boolean
    hasJsonPathValue: boolean
    hasTargetValue: boolean
    hasUrlValue: boolean
    iconElement?: SVGUseElement | null

    The related icon element to attach the spinner to.

    iconValue: string

    The icon name to be used for loading states (e.g. spinner), set on connect by finding the closest svg use href.

    inputTarget: HTMLInputElement

    Target element to be used as the primary search field input, if not provided the controlled element will be used instead.

    jsonPathValue: string

    A dotted path to the HTML string value to extract from the JSON response.

    loadingClasses: string[]

    The loading state class(es) to apply to the element when a request is in progress.

    loadingValue: boolean

    Tracking for transitional state of loading.

    messagesValue: Record<string, string>

    An object of messages, where the keys are HTTP status codes, used to determine what message should show in the UI on HTTP error.

    reflectValue: boolean

    If true, the browser's URL will be updated to reflect the search params (excluding those with _w_ prefix and without creating a browser history entry).

    replaceLazy?: { cancel(): void; (...args: any[]): void }

    Debounced function to request a URL and then replace the DOM with the results.

    searchLazy?: { cancel(): void; (...args: any[]): void }

    Debounced function to search results and then replace the DOM.

    srcValue: string

    The URL to request for the async swap HTML content, gets set to the form's action attribute if not passed in via the controller's attributes.

    submitLazy?: { cancel(): void; (...args: any[]): void }

    Debounced function to submit the serialized form and then replace the DOM.

    targetValue: string

    A CSS selector for the target DOM element that should have its inner HTML swapped with the response HTML.

    waitValue: number

    The duration, in milliseconds, to wait (debounce) before making the request.

    writeDeferred?: () => Promise<string>

    A function that writes the HTML to the target.

    blessings: (<T>(constructor: Constructor<T>) => any)[]
    classes: string[] = ...
    defaultClearParam: string = 'p'
    outlets: string[]
    targets: string[] = ...
    values: {
        defer: { default: boolean; type: BooleanConstructor };
        error: { default: string; type: StringConstructor };
        icon: { default: string; type: StringConstructor };
        jsonPath: { default: string; type: StringConstructor };
        loading: { default: boolean; type: BooleanConstructor };
        messages: { default: {}; type: ObjectConstructor };
        reflect: { default: boolean; type: BooleanConstructor };
        src: { default: string; type: StringConstructor };
        target: { default: string; type: StringConstructor };
        wait: { default: number; type: NumberConstructor };
    } = ...

    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

    • When disconnecting, ensure we reset any visual related state values and cancel any in-flight requests.

      Returns void

    • Parameters

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

      Returns CustomEvent<Object>

    • When the error key changes, work out if we need to add a message to the UI or if we just need to clear any existing message that was previously set.

      This must be based on the error key but also what message is being used.

      Parameters

      • currentError: string
      • previousError: string

      Returns void

    • Returns void

    • Toggle the visual spinner icon if available and ensure content about to be replaced is flagged as busy with a toggling of the loading class.

      Parameters

      • isLoading: boolean
      • isLoadingPrevious: any

      Returns void

    • Update the current URL's search params to reflect those in the provided URL, excluding any params that start with _w_ (Wagtail internal params) or have an empty value.

      This should not create a new browser history entry, it replaces the current entry.

      Parameters

      • url: string

      Returns void

    • Abort any existing requests & set up new abort controller, then fetch and replace the HTML target with the new results. Cancel any in progress results request using the AbortController so that a faster response does not replace an in flight request.

      Parameters

      • OptionalurlSource: string | CustomEvent<{ url: string }> & { params?: { url?: string } }
      • Optionaldata: FormData

      Returns Promise<unknown>

    • Perform a URL search param update based on the input's value with a comparison against the matching URL search params. Will replace the target element's content with the results of the async search request based on the query.

      Search will only be performed with the URL param value is different to the input value. Cleared params will be removed from the URL if present.

      clear can be provided as Event detail or action param to override the default of 'p'.

      Parameters

      • Optionaldata: CustomEvent<{ clear: string }> & { params?: { clear?: string } }

      Returns void

    • Update the target element's content with the response from a request based on the input's form values serialized. Do not account for anything in the main location/URL, simply replace the content within the target element.

      Returns void

    • Parameters

      • _identifier: string
      • _application: Application

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods