feat: ruby_render method to match liquid_render

[brainbuz]

Summary

The liquid_render method allows a ruby template to call a liquid component. It would make sense to be able to call a ruby component from a liquid template.

Motivation

It just makes sense in light of the philosophy of being able choose and switch freely between template engines.

https://edge.bridgetownrb.com/docs/template-engines contains: You can mix ‘n’ match template types in the same project. For example, Liquid’s simple syntax and safe execution context make it ideal for designer-led template creation, so you could use Liquid for layouts but stick to ERB for code-intensive pages and other resources.

Which implies that you can do this.

Guide-level explanation

Reference-level explanation

If the feature already exists, it needs to be documented.

Drawbacks

Unresolved Questions

[brainbuz]

There could be a little more documentation on cross rendering.

Here's an example of something I did in a project where I needed a fragment of liquid rendered in an erb template.
source = data from a resource
lead = extracted content from that resource (which is a md/liquid doc)
<%= Liquid::Template.parse(lead).render( "data" => source ) %>

With similar tricks the main topic here may be possible by documentation. Syntactic Sugar should then definitely be left to 2.1.

[fpsvogel]

I looked into this, and it seems that at least one subclass of Liquid::Block will need to be added within Bridgetown::Tags, maybe two: one for ruby_render, another for slot.

What I'm using as a guide is the Card Ruby component, which looks like this in page_using_erb.erb:

<%= render(Card.new(title: "I'm a card", footer: "I'm a footer")) do |c| %>
  <% c.slot :image do %>
    <img src="test.jpg" />
  <% end %>
  <p>I'm the body of the <%= c.kind %></p>
<% end %>

In Liquid, I'm thinking it would look like this:

{% ruby_render "card", title: "I'm a card", footer: "I'm a footer" %}
  {% slot image %}
    <img src="test.jpg" />
  {% endslot %}
  <p>I'm the body of the {{ kind }}</p>
{% endruby_render %}

However, implementing that would feel like me taking stabs in the dark. Is there a pattern I could follow somewhere, or are there specific places where I should look to build up a pattern? (I don't want this to become time-consuming hand-holding, so feel free also to unassign/reassign this issue.)

[jaredcwhite]

Maybe we could punt on the slot feature? I think we don't necessarily need that for an MVP of this. Also maybe we just focus on component object rendering, since partials are engine-specific so that becomes less obvious how it works (is it looking for ERB? Serbea? something else?).

[fpsvogel]

Gotcha, so a Liquid tag (not a block as above) would be OK for an MVP? Like this:

{% ruby_render "my_component", title: "My Title" %}

[jaredcwhite]

I think that makes sense, yeah.

[fpsvogel]

How about this?

{% ruby_render MyComponent.new(title: "My Title") %}

Just let me know which is preferable. I just realized that the content inside a Liquid tag doesn't have to use a predetermined syntax.

[jaredcwhite]

🤯

Actually, I do like the idea of parsing that and making it look as Ruby-like as possible, then we have some feature parity… I worry it'll be hard to do though!

[fpsvogel]

@jaredcwhite I intend to add one more commit to my PR adding a docs section to the site (analogous to the section on liquid_render), but the implementation is there if you want to take a look and let me know what you think.

EDIT: I added the decs commit.