Merge pull request hotwired#168 from seanpdoyle/document-turbo-track-…

…dynamic Document `[data-turbo-track="dynamic"]`
searls · Jun 21, 2024 · 2230464 · 2230464
2 parents 394c7af + 18d80d0
commit 2230464
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 5 deletions.
diff --git a/_source/handbook/02_drive.md b/_source/handbook/02_drive.md
@@ -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>
 ```
@@ -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>
 ```
@@ -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>
 ```

diff --git a/_source/reference/attributes.md b/_source/reference/attributes.md
@@ -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).