More documentation for the render plugin

[gonubana]

Hello, I'm the same guy from #262 (Allowing the view method to accept a block).
As I usually arrive on this site by following some link from a search engine,
which often leads to some issue discussions, I wrongly assumed that
the issues section was the only way to communicate something.
Anyway, thanks to you, I now know about the dedicated discussions section.

In general, when I'm not losing anything significant, I like to make my code DRY.
So, when I use templates, I try to apply the DRY rule by picking the appropriate
approache from the following 4 approaches to making dynamic templates:

• Instance variables
  Helper methods
  Template locals
  Calling yield

But after looking into how the render plugin works, it looks like, performance wise,
it's best to use either instance variables or helper methods instead of using locals,
which in turn seems better than yield-ing.

If this is true, maybe it could be mentioned somewhere in the docs.

Back to the #262 feature request,
I mentioned there that I'd like to be able to replace:

  render :layout do
    render :inner, locals: il do
      render :innermost, locals: iml
    end
  end

with:

  view :inner, locals: il do
    render :innermost, locals: iml
  end

Then some hours later a commit (which I'm really thankful for)
that implemented this feature appeared.

But, again after looking into how the render plugin works, it seems like when
the view method calls the render_template method, it always does so by passing
a hash as the only argument which effectively skips the 2 potential optimizations
otherwise gained from directly using the render method.

If this is also true, maybe it could be mentioned somewhere in the docs too.

What do you think?
Is the default use of a layout template the only practical difference between
the render and the view methods?

[jeremyevans]

The view and render methods are both optimized for single argument calls. This is mentioned in the plugin documentation: https://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Render.html#module-Roda::RodaPlugins::Render-label-Speeding+Up+Template+Rendering. It doesn't explicitly mention that view calls with a block are not optimized, though it could be. The technical problem with trying to optimize that is that you cannot pass the block received to the _optimized_view_content method, as that is called as a default argument (so as not to slow down non-optimized cases), and the block local variable is not yet in scope at that point. You used to be able to do this via Proc.new without a block, but that was removed in Ruby 3.0.

view using a layout by default and render not is mentioned right at the top of the render plugin documentation, and yes, that's the main difference between the methods.

[gonubana]

That 'Speeding Up Template Rendering' section mentions that [only] single arguments of type String/Symbol get optimized. A single argument of type Hash doesn't get optimized. The single argument type gets in fact checked in the _cached_template_method method.

In other words, the optimized code:

render :layout do                  # <- gets handled by the `if` section in the render method (1st optimization route)
  render :inner, locals: il do     # <- gets handled by the `elsif` section in the render method (2nd optimization route)
    render :innermost, locals: iml
  end
end

Becomes the unoptimized code:

view :inner, locals: il do         # <- gets handled by the `else` section in the render method (No optimization route)
  render :innermost, locals: iml
end

So, calling the render method with a single argument of type Hash, which is what calling the view method with a block results into, triggers its no-optimization route.

[jeremyevans]

Your understanding is correct. If this is a bottleneck in your application, you'll probably want to stick with the more verbose approach with 3 render method calls, assuming you've benchmarked both approaches and have found that it significantly improves performance.

[gonubana]

Actually, I haven't done any benchmarks, but for my simple use case of the view method I think I could override it to something like:

def view(...)
  render_template :layout do
    render_template(...)
  end
end

Anyway, thanks again for the good work.