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.

[adg]

Right. We considered Overlay in the original design, but thought that what is in 1.6 is a good incremental step.

This issue is [now] tracking API improvements that make blocks more useful. Apologies if I misinterpreted the original intent of the issue.

[adg]

I just sent a CL with a proposed API addition, similar to what was discussed when blocks were originally introduced. I'd like to hear people's thoughts. Is this enough? Does it address the issues?

[moorereason]

That would be CL https://golang.org/cl/19788

[adg]

Yeah, I was hoping @gopherbot would chime in sooner!

[gopherbot]

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

[bep]

@agl what you have added is convenience methods that behaves very differently from their Parse and ParseFiles counterparts.

I'm sorry if I couldn't convey my message better, but these two methods I think are better left out of the API as is, it will confuse more than it helps.

What I would expect of template.Overlay if I hadn't read the GoDoc is something ala this pseudo code:

master := template.New("master").Funcs(funcs).Parse("some template")

master.Overlay("overlay").Parse("some other template")

// then later, somewhere else

overlay := master.Lookup("overlay")

This is how the template API looks like. There may be technical challenges making this overlay construct fit into that API, but if it's impossible, then just leave it as is.

[adg]

master.Overlay("overlay").Parse("some other template")

What would that even do, conceptually? It makes no sense to me.

(my username is @adg not @agl 😄)

[bep]

What would that even do, conceptually? It makes no sense to me.

It would parse the overlay and associate it in the same namespace with the rest. Conceptually it would be the same as:

master.New("some other").Parse("some other template")

In the above, master.Lookpup("some other") does return the expected template.

Maybe my construct would make more sense looking like this:

master.New("some overlay").Overlay("some other template")

Anyhow, I would expect the master and the overlay to be associated (I believe the term associated is used in the template code).

(sorry about the username confusion, but agl is about as close to your real name as adg ..)

[mfzl]

I maybe missing something significant but why not keep overlay information in templates themselves?.

layout.tmpl

<html>
<body>
    {{block "content"}}
        Default content
    {{end}}
</body>
</html>

home.tmpl

{{template "layout.tmpl"}}
{{define "content"}}
    <div id="home">
    this overrides default content
    </div>
{{end}}

Something like this http://play.golang.org/p/qRmZPnKYCF

[adg]

@fazal you'll need to describe your proposal in a lot more detail. There
are many unanswered questions there.

On 24 February 2016 at 21:39, fazal notifications@github.com wrote:

I maybe missing something significant but why not keep overlay information
in templates themselves?.

layout.tmpl

{{block "content"}} Default content {{end}}

home.tmpl

{{template "layout.tmpl"}}
{{define "content"}}

this overrides default content

{{end}}

—
Reply to this email directly or view it on GitHub
#14285 (comment).

[rsc]

As Andrew said, I don't see a clear proposal here. Closing this issue.