Should snd move to a different templating engine?

BigJk commented 4 years ago

Currently snd uses doT.js for it's templating. I choose it at first because I used it in a project ages ago and knew that it would work. After working with it a bit more I feel like it would be a good idea to consider moving to a different templating engine (before it's too late).

1. The Documentation I think the templating library should have a good documentation so that it is easy to pick up by people. doT nearly has no documentation. The only real source of information is one advanced example file.

2. Extensibility The main feature of snd is to build cool templates and it would be beneficial to have a templating language that could be extended with useful features. doT unfortunately isn't extensible at all.

3. Intuitive Syntax This point is probably a bit subjective but I feel like the syntax of the more advanced features of doT feels really strange and unintuitive.

Stuff like that:

{{##def.testFunctionWithParam = function(str) {
        return "My name is: " + str;
    }
#}}

{{##def.mytestparam: {{=it.name}} #}}
{{#def.testFunctionWithParam(def.mytestparam)}}

4. Full Logic The templating engine needs support for "complex" logic. It's not just enough to put the data straight into the template. There needs to be ways to loop over arrays in the data, manipulate the data for the template and do conditional stuff. That's actually the only point where I can't really complain about doT, as it makes every logic that javascript offers available to the template.

Possible Templating Languages

1. EJS

It's essentially just Javascript so complex logic is not a problem.

2. Nunjucks

Has the style of syntax you would find in templating of CMS-type of stuff. It's really extensible. Good documentation and a lot of functions out of the box.

3. Squirrelly

It's actually really similar to Nunjucks but a bit more lightweight (less functions out of the box) and faster. I don't think speed is really a problem as the templates we deal with are still minimal in comparison to the CMS stuff these templating engines normally have to deal with.

My personal favorite so far is Nunjucks as it feels mature, well documented, there are a lot of functions already present and It's really easy to extend. I also like the syntax.

If anyone has any input on this I would be happy to hear it! 😃

TrevorKlar commented 4 years ago

I completely agree with what you've said about doT.js. I'm not first-hand familiar with any of the other choices you've offered here, but I definitely agree that good documentation is critical.

Having looked through a few pages of the documentation, I'm also tending towards Nunjucks.

I think we'll have 3 major groups of people using Sales & Dungeons:

Noncoders. They see a quick / convenient way to get stats on the game table, and mostly just want to print stuff straight from Open5E and have it look like the photos they saw on Reddit.
Amateur coders. They do above, and might want to change some of the decorations in a template, or add obscure homebrew content. (I consider myself to be in this category)
Legit programmers. They do above, and make whole templates from scratch and add features/bugfixes to the program.

I think that to get to the point where noncoders feel like they just just plug-and-play, we want lots of documentation, good examples, and we'd like to do it without reinventing the wheel whenever possible.

With what we have right now, I feel a little lost because I don't have a walkthrough to follow or a manpage to read. I just come up against generic errors or uncommented files with syntax I don't recognize, and I don't know where to go from there.

BigJk commented 4 years ago

Thanks for the feedback! I totally agree in regards to the potential users of S&D. What also came to my mind was the lack of good errors with doT.js... It basically tells you "there is something wrong" but not the line and column. With Nunjucks I was able to extract the exact error position from the error and show it in the editor (typical red underlining with tooltip about what's wrong), which is really helpful 😄

So I think Nunjucks really does seem like a good choice so far.

BigJk commented 4 years ago

Sales & Dungeons is using Nunjucks now 👍

BigJk / snd