Document Turbo.cache

See: hotwired/turbo#632 and hotwired/turbo#634
marcoroth · Jul 18, 2022 · 67dbee2 · 67dbee2
1 parent 4f1598e
commit 67dbee2
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 3 deletions.
diff --git a/_source/handbook/06_building.md b/_source/handbook/06_building.md
@@ -83,6 +83,26 @@ To specify that a page should not be cached at all, use the `no-cache` directive
 
 To completely disable caching in your application, ensure every page contains a no-cache directive.
 
+### Opting Out of Caching from the client-side
+
+The value of the `<meta name="turbo-cache-control">` element can also be controlled by a client-side API exposed via `Turbo.cache`.
+
+```js
+// Set cache control of current page to `no-cache`
+Turbo.cache.exemptPageFromCache()
+
+// Set cache control of current page to `no-preview`
+Turbo.cache.exemptPageFromPreview()
+```
+
+Both functions will create a `<meta name="turbo-cache-control">` element in the `<head>` if the element is not already present.
+
+A previously set cache control value can be reset via:
+
+```js
+Turbo.cache.resetCacheControl()
+```
+
 ## Installing JavaScript Behavior
 
 You may be used to installing JavaScript behavior in response to the `window.onload`, `DOMContentLoaded`, or jQuery `ready` events. With Turbo, these events will fire only in response to the initial page load, not after any subsequent page changes. We compare two strategies for connecting JavaScript behavior to the DOM below.

diff --git a/_source/reference/drive.md b/_source/reference/drive.md
@@ -21,14 +21,16 @@ If _action_ is unspecified, Turbo Drive assumes a value of `"advance"`.
 
 Before performing the visit, Turbo Drive fires a `turbo:before-visit` event on `document`. Your application can listen for this event and cancel the visit with `event.preventDefault()` (see [Canceling Visits Before They Start](/handbook/drive#canceling-visits-before-they-start)).
 
-## Turbo.clearCache
+## Turbo.cache.clear
 
 ```js
-Turbo.clearCache()
+Turbo.cache.clear()
 ```
 
 Removes all entries from the Turbo Drive page cache. Call this when state has changed on the server that may affect cached pages.
 
+**Note:** This function was previously exposed as `Turbo.clearCache()`. The top-level function was deprecated in favor of the new `Turbo.cache.clear()` function.
+
 ## Turbo.setProgressBarDelay
 
 ```js
@@ -45,4 +47,4 @@ Note that this method has no effect when used with the iOS or Android adapters.
 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"`.
+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"`.