2.0 Planning

[rexm]

As a celebration of Handlebars.Net's millionth installation, it seems like a good time for:

Handlebars.Net Version 2.0 🎉

This thread will be to discuss what goes into 2.0. Really appreciate everyone's involvement, even if it's just bringing your experience and input to the table.

Call for Input

So far, here's the changes being considered (in no particular order): As consensus develops in this thread, approved items will get a [x] to indicate they're officially part of the 2.0 roadmap. Please review, comment, and add your own:

• Make all the function names match handlebars.js (for example, changing RegisterTemplate to RegisterPartial)
• Be able to return a value from a helper (and generally restructure the helper delegates to be more js-esque) (see Support for returning a complex object from a subexpression #264)
• Support more advanced helper construction (see Question: How to create a custom helper with access to @index #151)
• Add a Compile<ExpectedModelType>() overload for performance optimization
• Support for decorators (see Decorators implementation #137)
• Support the as |alias| syntax for enumerators (see Sequence contains more than one element #301)
• Refactor the compiler so it can provide line numbers of errors and syntax hints (see Add line number in handlebars exceptions #156, Please report betters errors (context) when having mistakes in the template #314)
• Remove the built-in filesystem based templating extension, but ensure we have a good extensibility model so it can still be added as an external plugin
• Support noEscape (see Can't seem to handle German umlauts.... #276)

Special thanks

to @mcintyre321, @Magentaize, @dejx, @amaclean, @vzwick, @axelheer, @sandorfr, @leniency, @pmccloghrylaing, @mikeprince3, @StefH, @huysentruitw, @abraham-fox, @ondrejtomcik, @mohd-akram, @EBMike, @JvanderStad, @katavasha, @Andrew-Hanlon, @nblumhardt, @crra, @esskar, and the many others who've helped make this library useful to people all over the world in the last 5 years!

[rexm]

Plan to address #292

[rexm]

Plan to address #297

[rexm]

Plan to address #301

[johnknoop]

Suggestion for v2:

I'm not sure if this is even possible using the tools available, but here's my idea:

We only use Handlebars to render html e-mails, and I imagine that's what most people use this library for, since rendering website UI's using Handlebars in .NET seems like an unusual thing to do. And given the nature of e-mail clients, a common setup is to produce the e-mail body in this sequence:

1. Check if the template is already compiled. If not, compile it.
2. Render the template.
3. Run Premailer.Net or any other CSS inliner.
4. Extract image paths from img elements in the html, and create CID-embedded attachments.

Now, step 3 and 4 doesn't really have any dependency on the context data used in step 2. Therefore, it's a shame we can't do step 3 and 4 as part of the compilation, so it only has do be done once per template. Now I have no idea how the execution flow looks when it comes compiling a Handlebars template, but it would be nice if one were able to register hooks that get called by Handlebars.Compile:

Handlebars.RegisterCompileHook(CompileHooks.AfterAllPartialsHaveBeenIncluded, (string html, Dictionary<string, object> templateProperties) =>
{
    templateProperties["EmbeddedImages"] = ExtractImagePaths(html, "/path/of/templates");
    return ApplyCssInlining(html);
});

And the return type of Handlebars.Compile would be:

interface CompiledTemplate
{
    string Render(object context);

    // Any properties that have been set by hooks
    Dictionary<string, object> templateProperties)
}

With this approach, the task of rendering an e-mail body would be so much quicker since all that has to be done is step 2 instead of steps 2, 3 and 4.

I don't know enough about the internals of how Handlebars templates get compiled. But if this seems reasonable and possible to do, then I'd be happy to help out implement it. But I don't want to add it to the checklist above before I know if this is even a sensible thing to do and if it's inline with the vision of this project.

[rexm]

The main goal of this project is to have a .NET native implementation of the handlebars JS library. The handful of times we’ve bent and added features that aren’t in the original handlebars library, it’s ended up being a mistake. That being said, since .NET and JS are different platforms, it can make sense to diverge. It should make sense based on those differences and be universally useful - contrary to your perception, while generating emails is one popular use-case, it is also widely used as a website templating engine, a code generator (not something I’d recommend, but it gets used that way) and a lot of others. Compiler hooks could make sense, but we’d need to work on a model that is useful to everyone and doesn’t commit us to supporting contracts we end up regretting.

[johnknoop]

Maybe compiler hooks could be part of the extensibility model you mention above. But I don't even know if html in -> html out would make sense as a contract for such hooks. You might work with other primitives than strings of html during the assembly process?

Also, everything I've written is based on the assumption that partials are sucked in during compilation, and not later on when the compiled template is rendered. Is this a correct assumption btw?

[rexm]

When a template is compiled and a partial is referenced, that reference is replaced by a function to look up the partial by name and invoke it during execution. What are you thinking you could do with that?

[johnknoop]

In the e-mail scenario, you typically wanna apply the CSS inlining after all partials have been pulled together into a single html document, because you might have styles coming from one partial and the elements from another. I just assumed this was how the compilation process looked, meaning the result of the compilation was a complete hbs document where all partials have been sucked, and the only thing happening during rendering was turning the remaining handlebars expressions into strings using the context data.

So given this, perhaps there's no real use for compilation hooks in my case.

[rexm]

Have you considered inlining before template compilation? Even as part of the build...

[johnknoop]

I have, The problem is that styles might reside in a partial for reusability, so it's only when a template has been assembled into a complete html file that I can safely apply the inlining.

[rexm]

I suggest exploring some other structures to achieve the same result without introducing the same challenges.