Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document [data-turbo-track="dynamic"] #168

Merged
merged 1 commit into from
Jun 21, 2024
Merged

Document [data-turbo-track="dynamic"] #168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 23 additions & 5 deletions _source/handbook/02_drive.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,13 +158,13 @@ Turbo Drive can be disabled on a per-element basis by annotating the element or
<a href="/" data-turbo="false">Disabled</a>

<form action="/messages" method="post" data-turbo="false">
...
<!-- … -->
</form>

<div data-turbo="false">
<a href="/">Disabled</a>
<form action="/messages" method="post">
...
<!-- … -->
</form>
</div>
```
Expand Down Expand Up @@ -247,19 +247,37 @@ To accomplish this, just annotate those asset elements with `data-turbo-track="r

```html
<head>
...
<!-- … -->
<link rel="stylesheet" href="/application-258e88d.css" data-turbo-track="reload">
<script src="/application-cbd3cd4.js" data-turbo-track="reload"></script>
</head>
```

## Removing Assets When They Change

As we saw above, Turbo Drive merges the contents of the `<head>` elements. When a page depends on external assets like CSS stylesheets that other pages do not, it can be useful to remove them when navigating away from the page.

Rendering a `<link>` or `<style>` element with `[data-turbo-track="dynamic"]` instructs Turbo Drive to dynamically remove the element when it is absent from a navigation's response, and can serve a complementary role to the [`[data-turbo-track="reload"]`](#reload-when-assets-change) attribute to avoid triggering a full page reload when deploying changes that only affect styles.

```html
<head>
<!-- … -->
<link rel="stylesheet" href="/page-specific-styles-258e88d.css" data-turbo-track="dynamic">
<style data-turbo-track="dynamic">
.page-specific-styles { /* … */ }
</style>
</head>
```

Note that rendering `<script>` elements with `[data-turbo-track="dynamic"]` might unintended side-effects. When `<script>` disconnected from the document, the JavaScript context doesn't change, nor is the element's already evaluated JavaScript code unloaded or changed in any way.

## Ensuring Specific Pages Trigger a Full Reload

You can ensure visits to a certain page will always trigger a full reload by including a `<meta name="turbo-visit-control">` element in the page’s `<head>`.

```html
<head>
...
<!-- … -->
<meta name="turbo-visit-control" content="reload">
</head>
```
Expand All @@ -276,7 +294,7 @@ Include a `<meta name="turbo-root">` element in your pages’ `<head>` to scope

```html
<head>
...
<!-- … -->
<meta name="turbo-root" content="/app">
</head>
```
Expand Down
1 change: 1 addition & 0 deletions _source/reference/attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ The following data attributes can be applied to elements to customize Turbo's be

* `data-turbo="false"` disables Turbo Drive on links and forms including descendants. To reenable when an ancestor has opted out, use `data-turbo="true"`. Be careful: when Turbo Drive is disabled, browsers treat link clicks as normal, but [native adapters](/handbook/native) may exit the app.
* `data-turbo-track="reload"` tracks the element's HTML and performs a full page reload when it changes. Typically used to [keep `script` and CSS `link` elements up-to-date](/handbook/drive#reloading-when-assets-change).
* `data-turbo-track="dynamic"` tracks the element's HTML and removes the element when it is absent from an HTML response. Typically used to [remove `style` and `link` elements](/handbook/drive#removing-assets-when-they-change) during navigation.
* `data-turbo-frame` identifies the Turbo Frame to navigate. Refer to the [Frames documentation](/reference/frames) for further details.
* `data-turbo-preload` signals to [Drive](/handbook/drive#preload-links-into-the-cache) to pre-fetch the next page's content
* `data-turbo-action` customizes the [Visit](/handbook/drive#page-navigation-basics) action. Valid values are `replace` or `advance`. Can also be used with Turbo Frames to [promote frame navigations to page visits](/handbook/frames#promoting-a-frame-navigation-to-a-page-visit).
Expand Down