From a5325563b1caaa38ba5616cea74249868880f2e5 Mon Sep 17 00:00:00 2001 From: Kevin McConnell Date: Fri, 10 Feb 2023 13:18:56 +0000 Subject: [PATCH 1/5] Tweaked a sentence to clarify it --- _source/handbook/03_frames.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_source/handbook/03_frames.md b/_source/handbook/03_frames.md index 68f11ed..b040a7a 100644 --- a/_source/handbook/03_frames.md +++ b/_source/handbook/03_frames.md @@ -102,7 +102,7 @@ This page now works in both its minimized form, where only the `div` with the in Note that the `` on `/emails/set_aside` does not contain a `src` attribute. That attribute is only added to the frame that needs to lazily load the content, not to the rendered frame that provides the content. -During navigation, a Frame will set `[aria-busy="true"]` on the `` element when fetching the new contents. When the navigation completes, the Frame will remove the `[aria-busy]` attribute. When navigating the `` through a `
` submission, Turbo will toggle the `[aria-busy="true"]` attribute in tandem with the Frame's. +During navigation, a Frame will set `[aria-busy="true"]` on the `` element when fetching the new contents. When the navigation completes, the Frame will remove the `[aria-busy]` attribute. When navigating the `` through a `` submission, Turbo will toggle the Form's `[aria-busy="true"]` attribute in tandem with the Frame's. After navigation finishes, a Frame will set the `[complete]` attribute on the `` element. From 4c6f8324da818dddbe04df7826981d843c2c4e68 Mon Sep 17 00:00:00 2001 From: Kevin McConnell Date: Fri, 10 Feb 2023 13:43:33 +0000 Subject: [PATCH 2/5] Update frame-missing docs with new behaviour --- _source/reference/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_source/reference/events.md b/_source/reference/events.md index f47218c..369da5c 100644 --- a/_source/reference/events.md +++ b/_source/reference/events.md @@ -40,6 +40,6 @@ Turbo emits events that allow you to track the navigation lifecycle and respond * `turbo:frame-load` fires when a `` element is navigated and finishes loading (fires after `turbo:frame-render`). The specific `` element is the event target. -* `turbo:frame-missing` fires when a navigated `` element is unable to update its contents from a `` element in the response with a matching `[id]` attribute. After dispatching the event, Turbo transforms the response into a Visit and navigates the page. Cancel the event to prevent navigation. Access the request's [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance with `event.detail.response`. +* `turbo:frame-missing` fires when the response to a `` element request does not contain a matching `` element. By default, Turbo writes an informational message into the frame and throws an exception. Cancel this event to override this handling. You can access the [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance with `event.detail.response`, and perform a visit by calling `event.detail.visit(...)`. * `turbo:fetch-request-error` fires when a form or frame fetch request fails due to network errors. This event fires on the respective element (turbo-frame or form element) which triggers it and can be accessed with `event.target` property. This event can be canceled. From c3e50bd8855e93187044dbc62cdc48575f18e5a5 Mon Sep 17 00:00:00 2001 From: Kevin McConnell Date: Fri, 10 Feb 2023 13:44:59 +0000 Subject: [PATCH 3/5] Mention frames in the `turbo-visit-control` ref --- _source/reference/attributes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_source/reference/attributes.md b/_source/reference/attributes.md index 5e73508..de27f20 100644 --- a/_source/reference/attributes.md +++ b/_source/reference/attributes.md @@ -35,5 +35,5 @@ The following attributes are automatically added by Turbo and are useful to dete The following `meta` elements, added to the `head`, can be used to customize caching and Visit behavior. * `` to [opt out of caching](/handbook/building#opting-out-of-caching). -* `` will perform a full page reload. +* `` will perform a full page reload whenever Turbo navigates to the page, including when the request originates from a ``. * `` to [scope Turbo Drive to a particular root location](/handbook/drive#setting-a-root-location). From 8908251902f343378d76e1896aa8ab94c9f0ab73 Mon Sep 17 00:00:00 2001 From: Kevin McConnell Date: Fri, 10 Feb 2023 14:24:57 +0000 Subject: [PATCH 4/5] Add "breaking out of the frame" to the handbook --- _source/handbook/03_frames.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/_source/handbook/03_frames.md b/_source/handbook/03_frames.md index b040a7a..24a2e48 100644 --- a/_source/handbook/03_frames.md +++ b/_source/handbook/03_frames.md @@ -209,6 +209,40 @@ any other state derived from the URL path and search parameters. [Visit]: /handbook/drive#page-navigation-basics [advance]: /handbook/drive#application-visits +## "Breaking out" from a Frame + +In most cases, requests that originate from a `` are expected to fetch content for that frame (or for +another part of the page, depending on the use of the `target` or `data-turbo-frame` attributes). This means the +response should always contain the expected `` element. If a response is missing the `` +element that Turbo expects, it's considered an error; when it happens Turbo will write an informational message into the +frame, and throw an exception. + +In certain, specific cases, you might want the response to a `` request to be treated as a new, full-page +navigation instead, effectively "breaking out" of the frame. The classic example of this is where a lost or expired +session causes an application to redirect to a login page. In this case, it's better for Turbo to display that login +page rather than treat it as an error. + +The simplest way to achieve this is to specify that the login page requires a full-page reload, by including the +[`turbo-visit-control`][meta] meta tag: + +```html + + + ... + +``` + +If you're using Turbo Rails, you can use the `turbo_page_requires_reload` helper to accomplish the same thing. + +Pages that specify `turbo-visit=control` `reload` will always result in a full-page navigation, even if the request +originated from inside a frame. + +If your application needs to handle missing frames in some other way, you can intercept the +[`turbo:frame-missing`][events] event to, for example, transform the response or perform a visit to another location. + +[meta]: /reference/attributes#meta-tags +[events]: /reference/events + ## Anti-Forgery Support (CSRF) Turbo provides [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection by checking the DOM for the existence of a `` tag with a `name` value of either `csrf-param` or `csrf-token`. For example: From 99ca71c5b41464a7cfbf12acdf2e657403731f55 Mon Sep 17 00:00:00 2001 From: Kevin McConnell Date: Mon, 13 Feb 2023 10:58:43 +0000 Subject: [PATCH 5/5] Minor edit --- _source/handbook/03_frames.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_source/handbook/03_frames.md b/_source/handbook/03_frames.md index 24a2e48..6af890b 100644 --- a/_source/handbook/03_frames.md +++ b/_source/handbook/03_frames.md @@ -218,7 +218,7 @@ element that Turbo expects, it's considered an error; when it happens Turbo will frame, and throw an exception. In certain, specific cases, you might want the response to a `` request to be treated as a new, full-page -navigation instead, effectively "breaking out" of the frame. The classic example of this is where a lost or expired +navigation instead, effectively "breaking out" of the frame. The classic example of this is when a lost or expired session causes an application to redirect to a login page. In this case, it's better for Turbo to display that login page rather than treat it as an error.