Permalink
Browse files

Adding 'partial' template function to add theme / local awareness to …

…the partials directory.
  • Loading branch information...
1 parent 4e99d6b commit c297d7451f6e71c9e790802ce807625a260da443 @spf13 spf13 committed Jun 6, 2014
@@ -65,8 +65,8 @@ same as the other types but the directory must be called "\_default".
This content template is used for [spf13.com](http://spf13.com).
It makes use of [partial templates](/layout/partials)
- {{ template "partials/header.html" . }}
- {{ template "partials/subheader.html" . }}
+ {{ partial "header.html" . }}
+ {{ partial "subheader.html" . }}
{{ $baseurl := .Site.BaseUrl }}
<section id="main">
@@ -105,17 +105,17 @@ It makes use of [partial templates](/layout/partials)
</div>
</aside>
- {{ template "partials/disqus.html" . }}
- {{ template "partials/footer.html" . }}
+ {{ partial "disqus.html" . }}
+ {{ partial "footer.html" . }}
## project/single.html
This content template is used for [spf13.com](http://spf13.com).
It makes use of [partial templates](/layout/partials)
- {{ template "partials/header.html" . }}
- {{ template "partials/subheader.html" . }}
+ {{ partial "header.html" . }}
+ {{ partial "subheader.html" . }}
{{ $baseurl := .Site.BaseUrl }}
<section id="main">
@@ -152,7 +152,7 @@ It makes use of [partial templates](/layout/partials)
</div>
{{ end }}
- {{ template "partials/footer.html" }}
+ {{ partial "footer.html" }}
Notice how the project/single.html template uses an additional parameter unique
to this template. This doesn't need to be defined ahead of time. If the key is
@@ -54,18 +54,18 @@ It makes use of [partial templates](/templates/partials) and uses a similar appr
<head>
<meta charset="utf-8">
- {{ template "partials/meta.html" . }}
+ {{ partial "meta.html" . }}
<base href="{{ .Site.BaseUrl }}">
<title>{{ .Site.Title }}</title>
<link rel="canonical" href="{{ .Permalink }}">
<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
- {{ template "partials/head_includes.html" . }}
+ {{ partial "head_includes.html" . }}
</head>
<body lang="en">
- {{ template "partials/subheader.html" . }}
+ {{ partial "subheader.html" . }}
<section id="main">
<div>
@@ -75,4 +75,4 @@ It makes use of [partial templates](/templates/partials) and uses a similar appr
</div>
</section>
- {{ template "partials/footer.html" }}
+ {{ partial "footer.html" }}
@@ -107,8 +107,8 @@ It makes use of [partial templates](/templates/partials). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
- {{ template "partials/header.html" . }}
- {{ template "partials/subheader.html" . }}
+ {{ partial "header.html" . }}
+ {{ partial "subheader.html" . }}
<section id="main">
<div>
@@ -121,16 +121,16 @@ defined.
</div>
</section>
- {{ template "partials/footer.html" }}
+ {{ partial "footer.html" }}
### Example taxonomy template (tag.html)
This content template is used for [spf13.com](http://spf13.com).
It makes use of [partial templates](/templates/partials). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
- {{ template "partials/header.html" . }}
- {{ template "partials/subheader.html" . }}
+ {{ partial "header.html" . }}
+ {{ partial "subheader.html" . }}
<section id="main">
<div>
@@ -141,7 +141,7 @@ defined.
</div>
</section>
- {{ template "partials/footer.html" }}
+ {{ partial "footer.html" }}
## Ordering Content
@@ -14,9 +14,14 @@ weight: 80
It's not a requirement to have this, but in practice it's very
convenient to split out common template portions into a partial template
that can be included anywhere. As you create the rest of your templates
-you will include templates from the /layout/partials directory. Hugo
-doesn't know anything about partials, it's simply a convention that you
-may likely find beneficial.
+you will include templates from the /layout/partials directory.
+
+Partials are especially important for themes as it gives users an opportunity
+to overwrite just a small part of your theme, while maintaining future compatibility.
+
+In fact theme developers may want to include a few partials with empty html
+files in the theme just so end users have an easy place to inject their
+customized content.
I've found it helpful to include a header and footer template in
@@ -32,6 +37,21 @@ like good names to use for inclusion in your other templates.
By ensuring that we only reference [variables](/layout/variables/)
used for both nodes and pages we can use the same partials for both.
+## Partial vs Template
+
+Version v0.12 of Hugo introduced the partial call inside the template system.
+This is a change to the way partials were handled previously inside the
+template system. This is a change to hthe way partials were handled previously.
+Previously Hugo didn’t treat partials specially and you could include a partial
+template with the `template` call in the standard template language.
+
+With the addition of the theme system in v0.11 it became apparent that a theme
+& override aware partial was needed.
+
+When using Hugo v0.12 and above please use the `partial` call (and leave out
+the “partial/” path). The old approach will still work, but won’t benefit from
+the ability to have users override the partial theme file with local layouts.
+
## example header.html
This header template is used for [spf13.com](http://spf13.com).
@@ -40,14 +60,14 @@ This header template is used for [spf13.com](http://spf13.com).
<head>
<meta charset="utf-8">
- {{ template "partials/meta.html" . }}
+ {{ partial "meta.html" . }}
<base href="{{ .Site.BaseUrl }}">
<title> {{ .Title }} : spf13.com </title>
<link rel="canonical" href="{{ .Permalink }}">
{{ if .RSSlink }}<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
- {{ template "partials/head_includes.html" . }}
+ {{ partial "head_includes.html" . }}
</head>
<body lang="en">
@@ -70,8 +70,8 @@ content tagged with each tag.
.Data.Terms is an map of terms => [contents]
- {{ template "partials/header.html" . }}
- {{ template "partials/subheader.html" . }}
+ {{ partial "header.html" . }}
+ {{ partial "subheader.html" . }}
<section id="main">
<div>
@@ -86,7 +86,7 @@ content tagged with each tag.
</div>
</section>
- {{ template "partials/footer.html" }}
+ {{ partial "footer.html" }}
## Ordering
@@ -97,8 +97,8 @@ number of content assigned to that key or alphabetically.
## Example indexes.html file (alphabetical)
- {{ template "partials/header.html" . }}
- {{ template "partials/subheader.html" . }}
+ {{ partial "header.html" . }}
+ {{ partial "subheader.html" . }}
<section id="main">
<div>
@@ -111,12 +111,12 @@ number of content assigned to that key or alphabetically.
</ul>
</div>
</section>
- {{ template "partials/footer.html" }}
+ {{ partial "footer.html" }}
## Example indexes.html file (ordered)
- {{ template "partials/header.html" . }}
- {{ template "partials/subheader.html" . }}
+ {{ partial "header.html" . }}
+ {{ partial "subheader.html" . }}
<section id="main">
<div>
@@ -130,5 +130,5 @@ number of content assigned to that key or alphabetically.
</div>
</section>
- {{ template "partials/footer.html" }}
+ {{ partial "footer.html" }}
@@ -42,6 +42,15 @@ The default single file layout is located at `layouts/_default/single.html`.
The default list file layout is located at `layouts/_default/list.html`
+### Partial Templates
+
+Theme creators should liberally use [partial templates](/templates/partials)
+throughout their theme files. Not only is a good DRY practice to include shared
+code, but partials are a special template type that enables the themes end user
+to be able to overwrite just a small piece of a file or inject code into the
+theme from their local /layouts. These partial templates are perfect for easy
+injection into the theme with minimal maintenance to ensure future
+compatibility.
### Static
@@ -12,7 +12,6 @@ weight: 40
Hugo themes permit you to supplement or override any template or file
from within your working directory.
-
## Replacing Static files
If you would like to include a different file than the theme ships
@@ -27,12 +26,17 @@ in the same relative path /static/js/jQuery.min.js.
Anytime Hugo looks for a matching template it will first check the
working directory before looking in the theme directory. If you would
like to modify a template simply create that template in your local
-layouts directory. In the [template documentation](/templates/overview/)
+layouts directory. In the [template documentation](/templates/overview)
each different template type explains the rules it uses to determine
which template to use.
+This is especially helpful when the theme creator used [partial
+templates](/templates/partials). These partial templates are perfect for easy
+injection into the theme with minimal maintenance to ensure future
+compatibility.
+
**warning.. This only works for templates that Hugo knows about. If the
-theme creates partial template files in a creatively named directory
+theme imports template files in a creatively named directory
Hugo won’t know to look for the local /layouts first**
## Replace an archetype
@@ -1,3 +1,3 @@
-{{ template "partials/header.html" . }}
+{{ partial "header.html" . }}
{{ .Content }}
-{{ template "partials/footer.html" . }}
+{{ partial "footer.html" . }}
View
@@ -1,6 +1,7 @@
package hugolib
import (
+ "bytes"
"errors"
"html"
"html/template"
@@ -14,8 +15,11 @@ import (
"github.com/eknkc/amber"
"github.com/spf13/hugo/helpers"
+ jww "github.com/spf13/jwalterweatherman"
)
+var localTemplates *template.Template
+
func Eq(x, y interface{}) bool {
return reflect.DeepEqual(x, y)
}
@@ -192,6 +196,8 @@ func NewTemplate() Template {
errors: make([]*templateErr, 0),
}
+ localTemplates = &templates.Template
+
funcMap := template.FuncMap{
"urlize": helpers.Urlize,
"sanitizeurl": helpers.SanitizeUrl,
@@ -215,6 +221,7 @@ func NewTemplate() Template {
"lower": func(a string) string { return strings.ToLower(a) },
"upper": func(a string) string { return strings.ToUpper(a) },
"title": func(a string) string { return strings.Title(a) },
+ "partial": Partial,
}
templates.Funcs(funcMap)
@@ -223,6 +230,36 @@ func NewTemplate() Template {
return templates
}
+func Partial(name string, context interface{}) template.HTML {
+ if strings.HasPrefix("partials/", name) {
+ name = name[8:]
+ }
+ return ExecuteTemplateToHTML(context, "partials/"+name, "theme/partials/"+name)
+}
+
+func ExecuteTemplate(context interface{}, layouts ...string) *bytes.Buffer {
+ buffer := new(bytes.Buffer)
+ worked := false
+ for _, layout := range layouts {
+ if localTemplates.Lookup(layout) != nil {
+ localTemplates.ExecuteTemplate(buffer, layout, context)
+ worked = true
+ break
+ }
+ }
+ if !worked {
+ jww.ERROR.Println("Unable to render", layouts)
+ jww.ERROR.Println("Expecting to find a template in either the theme/layouts or /layouts in one of the following relative locations", layouts)
+ }
+
+ return buffer
+}
+
+func ExecuteTemplateToHTML(context interface{}, layouts ...string) template.HTML {
+ b := ExecuteTemplate(context, layouts...)
+ return template.HTML(string(b.Bytes()))
+}
+
func (t *GoHtmlTemplate) LoadEmbedded() {
t.EmbedShortcodes()
t.EmbedTemplates()

0 comments on commit c297d74

Please sign in to comment.