Skip to content

Commit

Permalink
Document Event Detail types
Browse files Browse the repository at this point in the history 
The various events dispatched by Turbo can embed references to Turbo
specific classes like `FetchRequest`, `FetchResponse`, and
`FormSubmission`.

This commit adds dedicated entries to the `Drive` page, then links to
those entries from the `Events` page.
  • Loading branch information
@seanpdoyle
seanpdoyle committed Feb 22, 2024
1 parent f33f804 commit 84c27bb
Show file tree
Hide file tree
Showing 2 changed files with 87 additions and 13 deletions.
69 changes: 69 additions & 0 deletions _source/reference/drive.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,72 @@ Turbo.session.drive = false
```

Turns Turbo Drive off by default. You must now opt-in to Turbo Drive on a per-link and per-form basis using `data-turbo="true"`.

## `FetchRequest`

Turbo dispatches a variety of [events while making HTTP requests](/reference/events#http-requests) that reference `FetchRequest` objects with the following properties:

| Property | Type | Description
|-------------------|-----------------------------------------------------------------------------------|------------
| `body` | [FormData][] \| [URLSearchParams][] | a [URLSearchParams][] instance for `"get"` requests, [FormData][] otherwise
| `enctype` | `"application/x-www-form-urlencoded" \| "multipart/form-data" \| "text/plain"` | the [HTMLFormElement.enctype][] value
| `fetchOptions` | [RequestInit][] | the request's configuration options
| `headers` | [Headers][] \| `{ [string]: [any] }` | the request's HTTP headers
| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete"` | the HTTP verb
| `params` | [URLSearchParams][] | the [URLSearchParams][] instance for `"get"` requests
| `target` | [HTMLFormElement][] \| [HTMLAnchorElement][] \| `FrameElement` \| `null` | the element responsible for initiating the request
| `url` | [URL][] | the request's [URL][]

[HTMLAnchorElement]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement
[RequestInit]: https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options
[Headers]: https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#headers
[HTMLFormElement.enctype]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/enctype

## `FetchResponse`

Turbo dispatches a variety of [events while making HTTP requests](/reference/events#http-requests) that reference `FetchResponse` objects with the following properties:

| Property | Type | Description
|-------------------|-------------------|------------
| `clientError` | `boolean` | `true` if the status is between 400 and 499, `false` otherwise
| `contentType` | `string` | the value of the [Content-Type][] header
| `failed` | `boolean` | `true` if the response did not succeed, `false` otherwise
| `isHTML` | `boolean` | `true` if the content type is HTML, `false` otherwise
| `location` | [URL][] | the value of [Response.url][]
| `redirected` | `boolean` | the value of [Response.redirected][]
| `responseHTML` | `Promise<string>` | clones the `Response` if its HTML, then calls [Response.text()][]
| `responseText` | `Promise<string>` | clones the `Response`, then calls [Response.text()][]
| `response` | [Response] | the `Response` instance
| `serverError` | `boolean` | `true` if the status is between 500 and 599, `false` otherwise
| `statusCode` | `number` | the value of [Response.status][]
| `succeeded` | `boolean` | `true` if the [Response.ok][], `false` otherwise

[Response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
[Response.url]: https://developer.mozilla.org/en-US/docs/Web/API/Response/url
[Response.ok]: https://developer.mozilla.org/en-US/docs/Web/API/Response/ok
[Response.redirected]: https://developer.mozilla.org/en-US/docs/Web/API/Response/redirected
[Response.status]: https://developer.mozilla.org/en-US/docs/Web/API/Response/status
[Response.text]: https://developer.mozilla.org/en-US/docs/Web/API/Response/text
[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type

## `FormSubmission`

Turbo dispatches a variety of [events while submitting forms](/reference/events#forms) that reference `FormSubmission` objects with the following properties:

| Property | Type | Description
|-------------------|----------------------------------------------------------------------------------|------------
| `action` | `string` | where the `<form>` element is submitting to
| `body` | [FormData][] \| [URLSearchParams][] | the underlying [Request][] payload
| `enctype` | `"application/x-www-form-urlencoded" \| "multipart/form-data" \| "text/plain"` | the [HTMLFormElement.enctype][]
| `fetchRequest` | [FetchRequest][] | the underlying [FetchRequest][] instance
| `formElement` | [HTMLFormElement][] | the `<form>` element to that is submitting
| `isSafe` | `boolean` | `true` if the `method` is `"get"`, `false` otherwise
| `location` | [URL][] | the `action` string transformed into a [URL][] instance
| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete"` | the HTTP verb
| `submitter` | [HTMLButtonElement][] \| [HTMLInputElement][] \| `undefined` | the element responsible for submitting the `<form>` element

[FetchRequest]: #fetchrequest
[FormData]: https://developer.mozilla.org/en-US/docs/Web/API/FormData
[HTMLFormElement]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement
[URLSearchParams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
[URL]: https://developer.mozilla.org/en-US/docs/Web/API/URL
31 changes: 18 additions & 13 deletions _source/reference/events.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -147,23 +147,25 @@ Turbo Drive emits events during submission, redirection, and submission failure.

### `turbo:submit-start`

Fires during a form submission. Access the `FormSubmission` object with `event.detail.formSubmission`. Abort form submission (e.g. after validation failure) with `event.detail.formSubmission.stop()`. Use `event.originalEvent.detail.formSubmission.stop()` if you're using jQuery.
Fires during a form submission. Access the [FormSubmission][] object with `event.detail.formSubmission`. Abort form submission (e.g. after validation failure) with `event.detail.formSubmission.stop()`. Use `event.originalEvent.detail.formSubmission.stop()` if you're using jQuery.

| `event.detail` property | Type | Description
|---------------------------|-------------------------------------------|------------
| `formSubmission` | `FormSubmission` | the `<form>` element submission
| `formSubmission` | [FormSubmission][] | the `<form>` element submission

### `turbo:submit-end`

Fires after the form submission-initiated network request completes. Access the `FormSubmission` object with `event.detail.formSubmission` along with `FormSubmissionResult` properties included within `event.detail`.
Fires after the form submission-initiated network request completes. Access the [FormSubmission][] object with `event.detail.formSubmission` along with the properties included within `event.detail`.

| `event.detail` property | Type | Description
|---------------------------|---------------------------|------------
| `success` | `boolean` | a `boolean` representing the request's success
| `fetchResponse` | `FetchResponse \| null` | present when `success: true`, `null` when `success: false`
| `error` | [Error][] or `null` | `null` when `success: true`, present when `success: false`
| `event.detail` property | Type | Description
|---------------------------|-------------------------------|------------
| `formSubmission` | [FormSubmission][] | the `<form>` element submission
| `success` | `boolean` | a `boolean` representing the request's success
| `fetchResponse` | [FetchResponse][] \| `null` | present when `success: true`, `null` when `success: false`
| `error` | [Error][] or `null` | `null` when `success: true`, present when `success: false`

[Error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors
[FormSubmission]: /reference/drive#formsubmission

## Frames

Expand All @@ -181,11 +183,11 @@ Fires before rendering the `<turbo-frame>` element. Access the new `<turbo-frame

### `turbo:frame-render`

Fires right after a `<turbo-frame>` element renders its view. The specific `<turbo-frame>` element is the [event.target][]. Access the `FetchResponse` object with `event.detail.fetchResponse` property.
Fires right after a `<turbo-frame>` element renders its view. The specific `<turbo-frame>` element is the [event.target][]. Access the [FetchResponse][] object with `event.detail.fetchResponse` property.

| `event.detail` property | Type | Description
|---------------------------|-----------------------------------|------------
| `fetchResponse` | `FetchResponse` | the HTTP request's response
| `fetchResponse` | [FetchResponse][] | the HTTP request's response

### `turbo:frame-load`

Expand Down Expand Up @@ -215,7 +217,7 @@ Fires before rendering a Turbo Stream page update. Access the new `<turbo-stream

| `event.detail` property | Type | Description
|---------------------------|-----------------------------------|------------
| `newStream` | `StreamElement` | the new `<body>` element that will replace the document's current `<body>` element
| `newStream` | `StreamElement` | the new `<turbo-stream>` element whose action will be executed
| `render` | `async (currentElement) => void` | override to define [Custom Actions][]

[Custom Actions]: /handbook/streams#custom-actions
Expand Down Expand Up @@ -250,7 +252,9 @@ Fires after the network request completes. Access the fetch options object with

| `event.detail` property | Type | Description
|---------------------------|---------------------------|------------
| `fetchResponse` | `FetchResponse` | the HTTP request's response
| `fetchResponse` | [FetchResponse][] | the HTTP request's response

[FetchResponse]: /reference/drive#fetchresponse

### `turbo:before-prefetch`

Expand All @@ -262,7 +266,8 @@ Fires when a form or frame fetch request fails due to network errors. This event

| `event.detail` property | Type | Description
|---------------------------|-------------------|------------
| `request` | `FetchRequest` | The HTTP request that failed
| `request` | [FetchRequest][] | The HTTP request that failed
| `error` | [Error][] | provides the cause of the failure

[Error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors
[FetchRequest]: /reference/drive#fetchrequest

0 comments on commit 84c27bb

Please sign in to comment.