From 39b1d32de17a711dbbd91de48df8a6897b6f4e47 Mon Sep 17 00:00:00 2001 From: Jorge Manrubia Date: Fri, 29 Dec 2023 17:45:00 +0100 Subject: [PATCH] Remove turbo_meta_tags and add missing documentation See https://github.com/hotwired/turbo-rails/pull/542#issuecomment-1869699754 --- app/helpers/turbo/drive_helper.rb | 38 ++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/app/helpers/turbo/drive_helper.rb b/app/helpers/turbo/drive_helper.rb index 18e4daa8..f2d78f98 100644 --- a/app/helpers/turbo/drive_helper.rb +++ b/app/helpers/turbo/drive_helper.rb @@ -1,14 +1,21 @@ module Turbo::DriveHelper - # Note: These helpers require a +turbo_meta_tags+ provision in the layout. + # Helpers to configure Turbo Drive via meta directives. They come in two + # variants: + # + # The recommended option is to include +yield :head+ in the ++ section + # of the layout. Then you can use the helpers in any view. # # ==== Example # # # app/views/application.html.erb - # <%= turbo_meta_tags %><%= yield %> + # <%= yield :head %><%= yield %> # # # app/views/trays/index.html.erb # <% turbo_exempts_page_from_cache %> #

Page that shouldn't be cached by Turbo

+ # + # Alternatively, you can use the +_tag+ variant of the helpers to only get the + # HTML for the meta directive. # Pages that are more likely than not to be a cache miss can skip turbo cache to avoid visual jitter. # Cannot be used along with +turbo_exempts_page_from_preview+. @@ -16,6 +23,7 @@ def turbo_exempts_page_from_cache provide :head, turbo_exempts_page_from_cache_tag end + # See +turbo_exempts_page_from_cache+ def turbo_exempts_page_from_cache_tag tag.meta(name: "turbo-cache-control", content: "no-cache") end @@ -26,6 +34,7 @@ def turbo_exempts_page_from_preview provide :head, turbo_exempts_page_from_preview_tag end + # See +turbo_exempts_page_from_preview+ def turbo_exempts_page_from_preview_tag tag.meta(name: "turbo-cache-control", content: "no-preview") end @@ -35,27 +44,44 @@ def turbo_page_requires_reload provide :head, turbo_page_requires_reload_tag end + # See +turbo_page_requires_reload+ def turbo_page_requires_reload_tag tag.meta(name: "turbo-visit-control", content: "reload") end + # Configure how to handle page refreshes. A page refresh happens when + # Turbo loads the current page again with a *replace* visit: + # + # === Parameters: + # * method - Specifies the method to update the ++ of the page + # during a page refresh. It can be one of: + # * +replace:+: Replaces the existing ++ with the new one. This is the + # default behavior. + # * +morph:+: Morphs the existing ++ into the new one. + # + # * scroll - Controls the scroll behavior when a page refresh happens. It + # can be one of: + # * +reset:+: The page scroll gets reset to the top, left corner. This is the default. + # * +preserve:+: The page scroll is kept. + # + # === Example Usage: + # + # turbo_refreshes_with(method: :morph, scroll: :preserve) def turbo_refreshes_with(method: :replace, scroll: :reset) provide :head, turbo_refresh_method_tag(method) provide :head, turbo_refresh_scroll_tag(scroll) end + # Configure method to perform page refreshes. See +turbo_refreshes_with+. def turbo_refresh_method_tag(method = :replace) raise ArgumentError, "Invalid refresh option '#{method}'" unless method.in?(%i[ replace morph ]) tag.meta(name: "turbo-refresh-method", content: method) end + # Configure scroll strategy for page refreshes. See +turbo_refreshes_with+. def turbo_refresh_scroll_tag(scroll = :reset) raise ArgumentError, "Invalid scroll option '#{scroll}'" unless scroll.in?(%i[ reset preserve ]) tag.meta(name: "turbo-refresh-scroll", content: scroll) end - - def turbo_meta_tags - content_for :head - end end