Skip to content

Commit

Permalink
Document [data-turbo-track="dynamic"]
Browse files Browse the repository at this point in the history 
Follow-up to [hotwired/turbo#1140][]

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"]`
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.

[hotwired/turbo#1140]: hotwired/turbo#1140
  • Loading branch information
@seanpdoyle
seanpdoyle committed Feb 20, 2024
1 parent 5cf3013 commit cd9075c
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 5 deletions.
28 changes: 23 additions & 5 deletions _source/handbook/02_drive.md
View file
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
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 `script` and CSS `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

0 comments on commit cd9075c

Please sign in to comment.