Mention Strict Locals in more documentation

[seanpdoyle]

Motivation / Background

Strict Locals support was introduced in #45727 and announced as part of the 7.1 Release. There are several mentions across the Guides, but support is rarely mentioned in the API documentation.

Detail

This commit adds two test cases to ensure support for splatting additional arguments, and for forbidding block and positional arguments.

It also makes mention of strict locals in more places, and links to the guides.

[JoelQ]

TIL about strict locals! 👍 for better docs!

[seanpdoyle]

While this is true in the sense that Action View will parse out a # locals: (...) magic comment, engines like jbuilder merge additional values into the locals: Hash under keys like :json, :collection, or :cached).

This behavior is exhibited in the test failures included in rails/jbuilder#557.

Instances of ActionView::Template can hint to the renderer a set of implicit keys that the templating engine is merging into the :locals Hash (for example, collection counters and the current iteration index) with its :implicit_locals keyword argument.

Unfortunately, templating engines like jbuilder are not integrating with Action View rendering at that level.

I see two paths forward for engines like jbuilder:

1. change their implementation to instead rely on template-scoped helper methods to provide access to baked-in references like the json object
   1a. alternatively, change their implementation to directly access an instance of ActionView::Template (maybe through the @current_template instance variable set in the ActionView::Base instance), then render with ActionView::Template#render instead of ActionView::Base#render)
2. change Action View's implementation to support passing in :implicit_locals from higher layers

I'm not sure of the labor involved in either approach, but it's probably worth considering, since Strict Locals has utility outside of ERB.

[seanpdoyle]

pinging @byroot since you're the author of #49782, which resolved issues very similar to this one.

[seanpdoyle]

@casperisfine do you have any insight here?

[casperisfine]

No particular insights and I didn't have much time to dig to have a strong opinion. From high level I think 2 is probably the better solution (at least the lest disruptive one).

[seanpdoyle]

@casperisfine for now, I've softened the language from All templating engines that support comments are supported to Action View will process the locals: magic comment in any templating engine that supports #-prefixed comments.

For now, that represents the truth, and we can investigate a public interface for templating engines separate from improving the documentation.

[mike-burns]

Does it make sense to explain what happens if the arguments are not passed? It looks like it raises a useful error message at runtime but that's probably worth stating.

[casperisfine]

Documentation isn't my forte, but this generally LGTM. I made a small suggestion, so feel free to apply or disagree, then let me know and I'll merge.

[seanpdoyle]

I've also opened #50865 to scaffold out new view partials with built-in # locals: integration.

[p8]

Looks good to me!