Template registration, first implementation (now in dev-3.x)

[clarle]

As discussed in #1021 and the linked gist.

Here's a first drop for template registration, including full tests, user guide documentation, and API docs.

@ericf and I were discussing a possible addition to the Y.Template.register API, where it would also accept a hash of template names to template functions. For example:

// Registers 'foo', 'bar', and 'baz' templates all at once
Y.Template.register({
     'foo': fooTemplate,
     'bar': barTemplate,
     'baz': bazTemplate
});

I started implementing something like this, but I wasn't sure what Y.Template.register(templateHash) would return. The current Y.Template.register(templateName, template) returns the revived template to maintain compatibility with the revive() API.

Pinging @caridy also for review.

[ericf]

I'm wondering if _registry is a better name for this property…

[clarle]

I agree. It makes more sense than _cache, so I'll change it all around.

[caridy]

About Y.Template.register(templateHash), I don't like it. You will probably use a tool to compile your templates, and a simple each if you really need to register a bunch of them at once, aside from the fact that it will make the api way more complex. Let's stick to the simple use-cases.

[caridy]

+1

[ericf]

@clarle I sent you a PR: https://github.com/clarle/yui3/pull/1 with some changes:

• Remove trailing whitespace
• Make sure Y.Template.render() always returns a string
• Added @since tags to API docs
• Tweak API doc text
• Tweak user guide text
• Added HISTROY.md entry

[ericf]

@clarle here's some improvements on the example based on your comments: https://github.com/clarle/yui3/pull/2

[clarle]

@ericf @caridy Everything looks good to me, is it ready to merge?

[ericf]

@clarle I think it's ready, but we should wait until the end of the week to give @rgrove a chance to look this over (and anyone else interested) since he was involved in the original discussion.

[tivac]

[evocateur]

There is also the module I wrote, mustache-wax, but it is admittedly not as integrated into the Y.Template sphere as locator-handlebars is.

[clarle]

I like the patterns idea that you have there, though we'll probably do more of that on the server-side compilation step. It might be useful to group templates by their templating engine, if we have a project that has precompiled templates with multiple rendering engines.

[ericf]

@evocateur once this lands, would this be something that you'd use in mustache-wax?

[evocateur]

@ericf Totally! I've always felt kind of weird by the namespacing options I added to simulate this kind of registry in the past.

[rgrove]

Thanks for waiting guys. Sorry I couldn't get to this sooner; I'm swamped.

I really like this! I suggested a few minor API doc tweaks above, but otherwise this looks great.

Incidentally, I would love to see multi-template registration like @clarle mentioned in the PR description. I would use that all the time.

[ericf]

I realized I forgot to add the URL to this issue…

[clarle]

I'll do that when I finish up the API docs changes too.

[clarle]

I think I've addressed any outstanding issues, and I've fixed one small bug in the user guide where engine.revive was passed in the wrong parameter.

Anything else before I merge?

[rgrove]

🚢

[clarle]

Manually merged into dev-3.x, let me know if any other problems come up!