topic: HTML template engine

[isaacvando]

I have an idea for a design; will update the issue when I get a chance.

[isaacvando]

For context, a template engine is a tool that enables dynamically expanding a static document with data. Some examples are Jinja and Thymeleaf.

I use Freemarker frequently at work, and my biggest annoyance with it is that you run into a huge number of run time errors that you have to find the hard way. I would like to write a Roc template engine that surfaces these errors at compile time. My idea for doing this is to create a templating language where the expressions are normal Roc expressions and we compile the template into a human readable Roc function which is then called directly by the consuming program. This way we get compile time errors and all the other standard tooling benefits for free.

At a minimum, I think a template engine should support loops, conditionals, and interpolation. A template could look like this:

{| for number : numbers |}
<div>{{Num.toStr number}}</div>
{|endfor|}

And generate a Roc function like this:

page = \{ numbers } -> 
    List.map numbers \number -> 
        "<div>$(Num.toStr number)</div>\n"
    |> Str.joinWith ""

To implement this, we need to parse the template to extract the content and template language expressions, determine what parameters are needed for the generated function based on the expressions used in the template, and generate the final function.

The most complicated part about this is determine which parameters are necessary. Fortunately Roc's strictness with identifier names, and the fact that the generated module would not have any user defined imports make the job easier, but still not trivial. For example, given {{foo.result |> Result.map \r -> r * 2}} we need to determine that foo is a parameter and nothing else. To do this, we will need to know about lambdas, string interpolation, sub definitions (if we allow expressions to be multiple lines), and probably more things. Nevertheless, I think it is doable. If getting all of the edge cases right is too much to ask, we can always limit the allowed expressions.

I have not landed on a syntax yet so I am open to suggestions. It might be interesting to use a syntax similar to another engine so that existing templates in that language could be ported to Roc easily.

This design could be emulated in dynamic languages like JavaScript and Python, but not so easily in many other statically typed languages like Java, because the generated function would need to have types specified for the arguments which means the engine would need to do type inference. I think this highlights how awesome Roc's full type inference is for allow us to generate a function like this with a simple approach and still get all the compile time validation. I am also very excited about the fact that the you can use familiar Roc functions and syntax in the template.

Note that the generated function always accepts a record. This is probably what the user would want to pass in anyway, and it means that the order of the fields in the generated function does not matter.

[isaacvando]

@gvwilson I will probably want to expand on this idea further outside of the book and turn it into a fully featured tool. How do you think that would work with licensing for the book?

Edit: I see now that you mentioned on another issue that the code will be MIT Licensed so this shouldn't be an issue. :heavy_check_mark:

[gvwilson]

:+1: There is also now an FAQ in #16 that unpacks this a bit more.

[gvwilson]

Thanks again for this @isaacvando - I've assigned the issue to you. Can you please create a subdirectory called template under the root directory and put your code there as a standalone project for now?

[isaacvando]

Yes, will do.