Skip to content

Commit

Permalink
Merge pull request #172 from seanpdoyle/document-event-detail-types
Browse files Browse the repository at this point in the history 
Document Event Detail types
  • Loading branch information
@dhh
dhh authored Sep 15, 2024
2 parents 54b893f + 84c27bb commit 2648c0c
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 @@ -145,23 +145,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 @@ -179,11 +181,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 @@ -213,7 +215,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 @@ -248,7 +250,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 @@ -260,7 +264,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 2648c0c

Please sign in to comment.