Class: AjaxSubmit

AjaxSubmit()

<brut-ajax-submit>

Wraps a <BUTTON> assumed to be inside a form to indicate that, when clicked, it should submit the form it's a part of via AJAX. It accounts for network failures and timeouts.

The general flow is as follows:

  1. When the button is clicked, the form's validity is checked. If it's not valid, nothing happens.
  2. If the form is valid, this element will be given the requesting attribute.
  3. The request will be initiated, set to abort after request-timeout ms as well as to abort on an externally-provided AbortSignal (see below). The data submitted will be the contents of new FormData(form), along with the name/value of the button that was clicked, if it has a name and value.
  4. If the request returns OK:
    • requesting will be removed and submitted will be added.
    • submitted will be removed after submitted-lifetime ms.
    • the brut:submitok event will be fired with the response text, parsed as HTML, as event.detail.
  5. If the request returned a 422:
    • If you have set no-server-side-error-parsing, the results will be included in the detail field of the brut:submitinvalid event.
    • If you have NOT set no-server-side-error-parsing, the response is parsed as errors to be inserted into the DOM. See below for how that works. In this case, brut:submitinvalid's detail bill be null.
  6. If the request returns not OK and not 422:
    • if it has been request-timeout ms or more since the button was first clicked, the operation is aborted (see below).
    • if it has been less than request-timeout ms and the HTTP status code was 5xx, the operation is retried.
    • otherwise, the operation is aborted.
  7. If fetch throws an error, the operation is aborted.

422 Responses

For a 422 response (where no-server-side-error-parsing is not set), this element assumes the response is text/html and contains one or more <brut-cv> elements. These elements will be inserted into the proper <brut-cv-messages> element, as follows:

  1. The input-name is examined.
  2. A <brut-cv-messages input-name="«input-name»"> is located
  3. The containing form is located
  4. The input element(s) are located inside that form, based on input-name.
  5. The <brut-cv-messages> are cleared of any element with attribute server-side
  6. The messages from the server are inserted, with the attribute server-side added if it's not there.
  7. The input is set as having a custom validity
  8. validity is reported
  9. The first input located is scrolled into view
  10. If the input is modified after this all happens, custom validity is cleared

For the server you are contacting, this element has a few requirements:

  • If everything is OK/the operation did what it was intended to do:
    • the server will respond with a 2xx
    • the response body, if it contains anything, be text/html (this is provided in the event detail)
  • If there are server-side constraint violations.
    • the server will return 422
    • the response body will be text/html
    • the response body will contain one or more <brut-cv> elements

Aborting the fetch Request

By default, the call to fetch will be aborted after the value of request-timeout ms (default is 5,000). When this happens, the form is submitted through the browser without Ajax. This is currently not configurable.

You can set an additional AbortSignal by setting the abortSignal property. When this is done, then either a timeout or your custom abort will abort the request and submit the form through the browser.

For your custom abort signal, you can prevent browser submission by providing a reason with the value AjaxSubmit.doNotSubmitThroughBrowser. This can be useful when you are debouncing requests. See the examples. You will also find it useful to set log-request-errors on the element so you can see what is happening.

Constructor

new AjaxSubmit()

Properties:
Name Type Description
no-server-side-error-parsing boolean

if set, the response body for a 422 will not be parsed and inserted into the DOM. Instead, the body will be part of the detail of the brut:submitinvalid event.
request-timeout number

number of ms that the entire operation is expected to complete within. Default is 5000
submitted-lifetime number

number of ms that "submitted" should remain on the element after the form has completed. Default is 2000
requesting boolean

boolean attribute that indicates the request has been made, but not yet returned. Don't set this yourself outside of development. It will be set and removed by this element.
submitted boolean

boolean attribute that indicates the form has been successfully submitted. Don't set this yourselr outside of develoment. It will be set and removed by this element.
log-request-errors boolean

if set, logging related to request error handling will appear in the console. It will also cause any form submission to be delayed by 2s to allow you to read the console.
Source:
Fires:
  • brut:submitok Fired when the AJAX request initated by this returns OK and all processing has completed.event: The detail will include the *parsed document* of the HTML returned in the response.
  • brut:submitinvalid Fired when the AJAX request initated by this returns a 422 and all logic around managing the reponse has completed. The detail will be null unless `no-server-side-error-parsing` is set,event: in which case it will be the parsed document of the HTML returned in the response.
Examples

Typical use

<form action="/widgets" method="post">
  <input type="text" name="name">

  <brut-ajax-submit>
    <button name="button" value="save">Save</button>
  </brut-ajax-submit>
  <brut-ajax-submit>
    <button name="button" value="analyze">Analyze</button>
  </brut-ajax-submit>
</form>
<!-- When "Save" is clicked, "name" will have the value from the text field,
     and "button" will have the value "save".
     When "Analyze" is clicked, "name" will have the value from the text
     field, and "button" will have the value "analyze". -->

Using a custom abort signal

const ajaxSubmit = document.querySelector("brut-ajax-submit")
const controller = new AbortController()
ajaxSubmit.abortSignal = controller.signal
// later, when you want to abort the request
controller.abort(AjaxSubmit.doNotSubmitThroughBrowser)