| [RF-DOCS] Rewrite the Layouts and Rendering guide (#57152)
### Motivation / Background
A complete rewrite of the Layouts and Rendering guide. It covered a lot of topics already covered in other guides, and the narrative flow went off on numerous tangents. I've moved content to other guides and removed information as I saw fit.
### Detail
I've rewritten the guide to focus heavily on the _relationship_ between the controller and the view.
A lot of detail about rendering partials was already covered in the Action View Overview guide, so I've removed it. I moved the information about structuring layouts and similar view related detail into the Action View Overview with it fits a lot better with the narrative.
I've moved the section on request variants out of the Action Controller Overview and added it to this guide where I feel it fits a lot better. I also took the opportunity to add a brief intro about rendering to the Action Controller Overview and signpost this guide since they are very closely related.
### Internal Audit
Section 1: "though it normally hands off any heavy code to the Model" - 'heavy code' is possibly a bit unhelpful for beginners. How about 'it normally hands off more complex logic to methods on the model' or something like that?
Section 2: Creating responses. I almost want to go one step even further back and be sure to cover what we mean by HTTP responses, for those just starting out. Not in massive depth, because it isn't the right place for that, but just a little bit more clarification. Something like: "there are three ways to create an HTTP response in order to display information to the user on the page".
"Call [render](https://api.rubyonrails.org/v7.1.3.4/classes/ActionController/Rendering.html#method-i-render) to create a full response to send back to the browser". Perhaps we could just add one more sentence here to break down what a 'full response' really is in terms of what a new developer/user would experience.
"Call [head](https://api.rubyonrails.org/v7.1.3.4/classes/ActionController/Head.html#method-i-head) to create a response consisting solely of HTTP headers to send back to the browser" - maybe we could add examples of why we might do this?
[New boost](https://3.basecamp.com/3076981/buckets/35498807/boosts/new?boost%5Bboostable_gid%5D=Z2lkOi8vYmMzL1JlY29yZGluZy83Njk3MzY5MTA4)Section 1: "though it normally hands off any heavy code to the Model" - 'heavy code' is possibly a bit unhelpful for beginners. How about 'it normally hands off more complex logic to methods on the model' or something like that?
Section 2: Creating responses. I almost want to go one step even further back and be sure to cover what we mean by HTTP responses, for those just starting out. Not in massive depth, because it isn't the right place for that, but just a little bit more clarification. Something like: "there are three ways to create an HTTP response in order to display information to the user on the page".
"Call [render](https://api.rubyonrails.org/v7.1.3.4/classes/ActionController/Rendering.html#method-i-render) to create a full response to send back to the browser". Perhaps we could just add one more sentence here to break down what a 'full response' really is in terms of what a new developer/user would experience.
"Call [head](https://api.rubyonrails.org/v7.1.3.4/classes/ActionController/Head.html#method-i-head) to create a response consisting solely of HTTP headers to send back to the browser" - maybe we could add examples of why we might do this?
[New boost](https://3.basecamp.com/3076981/buckets/35498807/boosts/new?boost%5Bboostable_gid%5D=Z2lkOi8vYmMzL1JlY29yZGluZy83Njk3MzY5MTA4)
End of section 2.1.1 we mention `status: :unprocessable_entity`. Worth expanding out this slightly to point out that we can render a template with a specific status code etc., and briefly why we might want to do this. We've got more info on this in section 2.2.13.4, so maybe just worth linking to this.
2.2.4 - I feel like this section is slightly confusing. We are told that it's valid to use `render inline:`, but the warning box tells us that there is seldom any reason to use this. Maybe it would be better to find a reason why we would need this, but if not, make it short and clear - more like 'this is here but probably won't be needed'.
2.2.7 and 2.2.8 feel repetitive. Can we combine these into one section and say that it's applicable to both XML and JSON?
2.2.13.1 MIME content type - worth a link to the MDN web docs or similar for explanation.
2.2.14 Finding Layouts - this is mostly a repeat of information at the beginning of the guide - the only difference is the addition of the builder information. We can probably re-organise this to make both sections more DRY.
At the start of Section 3, it mentions 'the rules for finding layouts that were mentioned earlier in this guide'. It would be more user-friendly to also link to them at this point.
3.1.1 - let's provide links to more information about RSS/Atom if possible?
Likewise, would be good to provide a link to the Sprockets gem repo when we mention it, for context.
- I think the "Using `render`" section could be it's own top section. This probably applies to all sections ("Rendering by Default", "Using `redirect_to`" and "Using `head`"). All these sections have interesting sub section that currently don't show up in the sidebar and this guide doesn't have that much sub sections as of yet.
- "Rendering an Action's View" shows an example of explicitly rendering a view (the "edit" view in the "update" action). Maybe rename this section to: "Explicitly Rendering an Action's View"? Maybe the example could be simpler as well with a "show" action that renders for example a "details" view?
- "Ajax libraries" is probably an outdated term? Maybe replace with something about an API end-point?
- The "Finding Layouts" section should probably be a top section in a "Layout and Rendering" guide?
- Some examples here could benefit from having the filename as a comment in the example code.
- The whole "Asset Tag Helpers" section can probably be removed as these are already described the in the "Action View Helpers" guide. I'm not sure it adds anything here.
- Maybe move the "Understanding yield" section to the "Action View Overview" guide under "Layouts" which also handles `yield`?
- The above also applies to "Using the content_for method".
- The "Using Partials" section can probably be removed as this is already described in the "Action View Overview" guide. Partials don't really know anything about Controllers, so it makes more sense to have it in a Action View guide.
- I'm not sure if the "Nested Layouts" adds anything or if that is a commonly used pattern.
Co-authored-by: Petrik de Heus |