text/template: make blocks easier to use

[bep]

I spent a little too much time trying to get the new block syntax in Go 1.6 implemented in Hugo, with no success.

Which is telling me that you should try to supply a "more real" example in the documentation.

Hugo uses the built-in associative transitive map to store its templates, so adding a new template is something like:

hugoTemplates.New("homePage").Parse(someTemplate)

As I understand the new block implementation, one needs to first parse it with the master file (with the block keywords), then do a "overlay" (a modification, a re-parsing) of the same template with the template with the definitions.

How to do that with the above I cannot figure out (other than the simple standalone clone example in the doc -- I could clone it, but how do I replace the template in the map?).

My naive approach would be:

m, _ := hugoTemplates.New("home").Parse(master)
m.Parse(overlay)

And this works ... for the first template. Adding a second breaks in confusing ways.

Ref. gohugoio/hugo#1832

Also see #3812

[ianlancetaylor]

If you want to a question about the new syntax, please see https://golang.org/wiki/Questions . Thanks.

[bep]

@ianlancetaylor -- no, this was plain and simple issue report. If something was unclear, don't hesitate to ask.

I'm not sure if this is a bug in the template package or simply some missing documentation, though.

[adg]

I think the issue is that hugo does things one way, while the block feature wants to do them another. The deal with blocks is that you create new *template.Template values for each "version" of the master templates.

Maybe @spf13 can comment on the approach taken by Hugo.

I am working on a better example of template blocks.

[bep]

Hugo's approach is basically:

root := template.New("")
root.Funcs(funcs)
// add embedded templates ...

// Then add all the user and theme templates (including partials, shortcodes, views)
// may use a master/overlay construct
root.New("template1").Parse(...)
root.New("template2").Parse(...)

// ...

templateForPage := root.Lookup("template1")

If I read you correct, this approach will not work with blocks and master/overlay templates, but you would have to get rid of the global and track the individual templates (with funcs and all the other dependencies (templates) duplicated/cloned) in your own registry?

I guess that would work, but it sounds like fighting the original design .

Not sure what I expected by the new block feature, but I did expect it to be more integrated, something a la:

root.New("template1").Parse(master, overlay)

[spf13]

@bep knows this as well as anyone.

I'm not sure if I understand this all correctly at all. From my reading of this thread and some of the related ones it sounds to me like go template blocks will use a vanilla *template.Template for the children (overriders)?

If so I think the approach the go team has taken makes sense from an implementation perspective, but is also a bit shortsighted. I don't think it's reasonable to assume that people would want a plain *template.Template for each of the master templates, particularly if they (as is in Hugo's case) have extended the functionality of the templates with additional functions. It seems very odd to me that these functions would be present in the parent but not in the children templates (not sure what the right terminology is here).

I've always thought the templates worked a bit strangely as you need to create a template and then chain off of it to create others, but it's worked really well for Hugo by creating an empty template at the root, customizing it and then all of the others effectively extend it. It's disappointing that this feature would not respect that valid use pattern.

Please correct me if I'm wrong.

[gopherbot]

CL https://golang.org/cl/19443 mentions this issue.

[adg]

The CL that @gopherbot just mentioned is my attempt to demonstrate the intended use of block.

[adg]

@spf13 this sentence

I don't think it's reasonable to assume that people would want a plain *template.Template for each of the master templates

leads me to believe you misunderstand how blocks should be used. You first declare a master *template.Template and then Clone that value to parse in new templates to replace blocks inside the master. Take a look at the above CL and let me know whether that makes sense.

[bep]

If I read you correct, this approach will not work with blocks and master/overlay templates, but you would have to get rid of the global and track the individual templates (with funcs and all the other dependencies (templates) duplicated/cloned) in your own registry?

@adg: I guess the CL was a "yes" to the question above.

I suggest you keep this issue open to track obvious improvements to the "master/overlay" feature.

I will put the Hugo-issue in freeze-mode for now.

[adg]

@bep yes.

[adg]

I'm not sure that there's anything to do wrt this issue. Anyone object to my closing it?

[bep]

I object.

Your new example is just a little slightly more practical example of the same.

The block feature is half-finished.

If you look at template.Parse, there is plenty of logic to keep all the associated templates in the same namespace in sync.

With the current master/overlay-dance you will have to re-implement similar logic yourself, which may or may not be a simple thing, depending on the use case.

So, a template.Overlay method or similar would be good. This is a very common use case and deserves better support from Go's std-lib.

Simplicity is hard.