Merge pull request rails#50864 from seanpdoyle/strict-loading-documentation

Mention Strict Locals in more documentation

Author: rafaelfranca

actionview/lib/action_view/base.rb

@@ -80,6 +80,23 @@ module ActionView # :nodoc:
   # This is useful in cases where you aren't sure if the local variable has been assigned. Alternatively, you could also use
   # <tt>defined? headline</tt> to first check if the variable has been assigned before using it.
   #
+  # By default, templates will accept any <tt>locals</tt> as keyword arguments. To restrict what <tt>locals</tt> a template accepts, add a <tt>locals:</tt> magic comment:
+  #
+  #   <%# locals: (headline:) %>
+  #
+  #   Headline: <%= headline %>
+  #
+  # In cases where the local variables are optional, declare the keyword argument with a default value:
+  #
+  #   <%# locals: (headline: nil) %>
+  #
+  #   <% unless headline.nil? %>
+  #   Headline: <%= headline %>
+  #   <% end %>
+  #
+  # Read more about strict locals in {Action View Overview}[https://guides.rubyonrails.org/action_view_overview.html#strict-locals]
+  # in the guides.
+  #
   # === Template caching
   #
   # By default, \Rails will compile each template to a method in order to render it. When you alter a template,
@@ -257,7 +274,8 @@ def _run(method, template, locals, buffer, add_to_stack: true, has_strict_locals
               message.
                 gsub("unknown keyword:", "unknown local:").
                 gsub("missing keyword:", "missing local:").
-                gsub("no keywords accepted", "no locals accepted")
+                gsub("no keywords accepted", "no locals accepted").
+                concat(" for #{@current_template.short_identifier}")
           )
         end
       else

actionview/lib/action_view/template.rb

@@ -148,6 +148,20 @@ class Template
     #     <p><%= alert %></p>
     #   <% end %>
     #
+    # By default, templates will accept any <tt>locals</tt> as keyword arguments
+    # and make them available to <tt>local_assigns</tt>. To restrict what
+    # <tt>local_assigns</tt> a template will accept, add a <tt>locals:</tt> magic comment:
+    #
+    #   <%# locals: (headline:, alerts: []) %>
+    #
+    #   <h1><%= headline %></h1>
+    #
+    #   <% alerts.each do |alert| %>
+    #     <p><%= alert %></p>
+    #   <% end %>
+    #
+    # Read more about strict locals in {Action View Overview}[https://guides.rubyonrails.org/action_view_overview.html#strict-locals]
+    # in the guides.
 
     eager_autoload do
       autoload :Error

actionview/test/template/template_test.rb

@@ -155,7 +155,7 @@ def test_locals_can_be_disabled
       render(foo: "bar")
     end
 
-    assert_match(/no locals accepted/, error.message)
+    assert_match(/no locals accepted for hello template/, error.message)
   end
 
   def test_locals_can_not_be_specified_with_positional_arguments
@@ -172,6 +172,25 @@ def test_locals_can_be_specified_with_splat_arguments
     assert_equal "bar", render(foo: "bar")
   end
 
+  def test_locals_can_be_specified_with_keyword_and_splat_arguments
+    @template = new_template("<%# locals: (id:, **attributes) -%>\n<%= tag.hr(id: id, **attributes) %>")
+    assert_equal '<hr id="1" class="h-1">', render(id: 1, class: "h-1")
+  end
+
+  def test_locals_cannot_be_specified_with_positional_arguments
+    @template = new_template("<%# locals: (argument = 'content') -%>\n<%= argument %>")
+    assert_raises ActionView::Template::Error, match: "`argument` set as non-keyword argument for hello template. Locals can only be set as keyword arguments." do
+      render
+    end
+  end
+
+  def test_locals_cannot_be_specified_with_block_arguments
+    @template = new_template("<%# locals: (&block) -%>\n<%= tag.div(&block) %>")
+    assert_raises ActionView::Template::Error, match: "`block` set as non-keyword argument for hello template. Locals can only be set as keyword arguments." do
+      render { "content" }
+    end
+  end
+
   def test_locals_can_be_specified
     @template = new_template("<%# locals: (message:) -%>\n<%= message %>")
     assert_equal "Hello", render(message: "Hello")
@@ -188,7 +207,7 @@ def test_required_locals_can_be_specified
       render
     end
 
-    assert_match(/missing local: :message/, error.message)
+    assert_match(/missing local: :message for hello template/, error.message)
   end
 
   def test_extra_locals_raises_error
@@ -197,7 +216,7 @@ def test_extra_locals_raises_error
       render(message: "Hi", foo: "bar")
     end
 
-    assert_match(/unknown local: :foo/, error.message)
+    assert_match(/unknown local: :foo for hello template/, error.message)
   end
 
   def test_rails_injected_locals_does_not_raise_error_if_not_passed

guides/source/7_1_release_notes.md

@@ -318,12 +318,23 @@ You can also set default values for these locals:
 <%= message %>
 ```
 
+Optional keyword arguments can be splatted:
+
+```erb
+<%# locals: (message: "Hello, world!", **attributes) -%>
+<%= tag.p(message, **attributes) %>
+```
+
 If you want to disable the use of locals entirely, you can do so like this:
 
 ```erb
 <%# locals: () %>
 ```
 
+Action View will process the `locals:` magic comment in any templating engine that supports `#`-prefixed comments, and will read the magic comment from any line in the partial.
+
+CAUTION: Only keyword arguments are supported. Defining positional or block arguments will raise an Action View Error at render-time.
+
 ### Add `Rails.application.deprecators`
 
 The new [`Rails.application.deprecators` method](https://github.com/rails/rails/pull/46049) returns a

guides/source/action_view_overview.md

@@ -346,6 +346,8 @@ Combining Ruby 3.1's pattern matching assignment with calls to [Hash#with_defaul
 <% end %>
 ```
 
+INFO: By default, partials will accept any `locals` as keyword arguments. To define what `locals` a partial accepts, use a `locals:` magic comment. To learn more, read about [Strict Locals](#strict-locals).
+
 [local_assigns]: https://api.rubyonrails.org/classes/ActionView/Template.html#method-i-local_assigns
 
 ### `render` without `partial` and `locals` Options
@@ -445,26 +447,73 @@ Rails will render the `_product_ruler` partial (with no data passed to it) betwe
 
 ### Strict Locals
 
-By default, templates will accept any `locals` as keyword arguments. To define what `locals` a template accepts, add a `locals` magic comment:
+By default, templates will accept any `locals` as keyword arguments. To define what `locals` a template accepts, add a `locals:` magic comment:
 
 ```erb
+<%# app/views/messages/_message.html.erb %>
+
 <%# locals: (message:) -%>
 <%= message %>
 ```
 
+Rendering the partial without a `:message` local variable argument will raise an exception:
+
+```ruby
+render "messages/message"
+# => ActionView::Template::Error: missing local: :message for app/views/messages/_message.html.erb
+```
+
 Default values can also be provided:
 
 ```erb
+<%# app/views/messages/_message.html.erb %>
+
 <%# locals: (message: "Hello, world!") -%>
 <%= message %>
 ```
 
+Rendering the partial without a `:message` local variable uses the provided default value:
+
+```ruby
+render "messages/message"
+# => "Hello, world!"
+```
+
+Rendering the partial with additional local variable arguments will raise an exception:
+
+```ruby
+render "messages/message", unknown_local: "will raise"
+# => ActionView::Template::Error: missing local: :unknown_local for app/views/messages/_message.html.erb
+```
+
+Optional local variable arguments can be splatted:
+
+```erb
+<%# app/views/messages/_message.html.erb %>
+
+<%# locals: (message: "Hello, world!", **attributes) -%>
+<%= tag.p(message, **attributes) %>
+```
+
 Or `locals` can be disabled entirely:
 
 ```erb
+<%# app/views/messages/_message.html.erb %>
+
 <%# locals: () %>
 ```
 
+Rendering the partial with any local variable arguments will raise an exception:
+
+```ruby
+render "messages/message", unknown_local: "will raise"
+# => ActionView::Template::Error: no locals accepted for app/views/messages/_message.html.erb
+```
+
+Action View will process the `locals:` magic comment in any templating engine that supports `#`-prefixed comments, and will read the magic comment from any line in the partial.
+
+CAUTION: Only keyword arguments are supported. Defining positional or block arguments will raise an Action View Error at render-time.
+
 Layouts
 -------