From 84c27bb9e2bc5c400e4421db25e0ace1f3a80d92 Mon Sep 17 00:00:00 2001 From: Sean Doyle Date: Wed, 21 Feb 2024 15:38:02 -0500 Subject: [PATCH] Document Event Detail types 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. --- _source/reference/drive.md | 69 +++++++++++++++++++++++++++++++++++++ _source/reference/events.md | 31 ++++++++++------- 2 files changed, 87 insertions(+), 13 deletions(-) diff --git a/_source/reference/drive.md b/_source/reference/drive.md index 0cd05b6..a60a2a0 100644 --- a/_source/reference/drive.md +++ b/_source/reference/drive.md @@ -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` | clones the `Response` if its HTML, then calls [Response.text()][] +| `responseText` | `Promise` | 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 `
` 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 `` 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 `` 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 diff --git a/_source/reference/events.md b/_source/reference/events.md index ea25a42..e161110 100644 --- a/_source/reference/events.md +++ b/_source/reference/events.md @@ -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 `` element submission +| `formSubmission` | [FormSubmission][] | the `` 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 `` 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 @@ -181,11 +183,11 @@ Fires before rendering the `` element. Access the new `` element renders its view. The specific `` element is the [event.target][]. Access the `FetchResponse` object with `event.detail.fetchResponse` property. +Fires right after a `` element renders its view. The specific `` 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` @@ -215,7 +217,7 @@ Fires before rendering a Turbo Stream page update. Access the new `` element that will replace the document's current `` element +| `newStream` | `StreamElement` | the new `` element whose action will be executed | `render` | `async (currentElement) => void` | override to define [Custom Actions][] [Custom Actions]: /handbook/streams#custom-actions @@ -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` @@ -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