Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

topic: HTML template engine #5

Open
isaacvando opened this issue Mar 7, 2024 · 5 comments
Open

topic: HTML template engine #5

isaacvando opened this issue Mar 7, 2024 · 5 comments
Assignees
Labels
assigned Topic has been assigned in-content Is the issue in lesson content?
Milestone

Comments

@isaacvando
Copy link
Contributor

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

@gvwilson gvwilson added discuss An issue or PR currently being discussed in-content Is the issue in lesson content? propose-addition A suggestion for an addition to content or infrastructure labels Mar 8, 2024
@gvwilson gvwilson added this to the topic-outline milestone Mar 8, 2024
@gvwilson gvwilson changed the title HTML Templating Engine topic proposal: HTML template engine Mar 8, 2024
@isaacvando
Copy link
Contributor Author

isaacvando commented Mar 8, 2024

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
Copy link
Contributor Author

isaacvando commented Mar 9, 2024

@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. ✔️

@gvwilson
Copy link
Collaborator

gvwilson commented Mar 9, 2024

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

@gvwilson gvwilson removed the discuss An issue or PR currently being discussed label Mar 10, 2024
@gvwilson
Copy link
Collaborator

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?

@gvwilson gvwilson changed the title topic proposal: HTML template engine topic: HTML template engine Mar 10, 2024
@isaacvando
Copy link
Contributor Author

Yes, will do.

@gvwilson gvwilson added assigned Topic has been assigned and removed propose-addition A suggestion for an addition to content or infrastructure labels Mar 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
assigned Topic has been assigned in-content Is the issue in lesson content?
Projects
None yet
Development

No branches or pull requests

2 participants