hugo/docs/content/en/templates/views.md

122 lines
4.3 KiB
Markdown
Raw Normal View History

---
title: Content View Templates
# linktitle: Content Views
description: Hugo can render alternative views of your content, which is especially useful in list and summary views.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templates]
keywords: [views]
menu:
docs:
parent: "templates"
weight: 70
weight: 70
sections_weight: 70
draft: false
aliases: []
toc: true
---
These alternative **content views** are especially useful in [list templates][lists].
The following are common use cases for content views:
* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
## Create a Content View
Squashed 'docs/' changes from f887bd7b..1d052b16 1d052b16 Update hosting-on-netlify.md 28b96bec Remove double brackets in Netlify hosting tutorial 373ed38b Update deployment instructions from hugo > 0.20 on Netlify 1bbb41ca Generate static assets on deploy in Nanobox tutorial 816d207f Add missing backtick in templates/views.md bf88e772 Add nanobox as a deployment option 9c37b4cc Change config's syntax order matching description d3cb05a7 Fix wrongly named default value of publishDir 4be85c54 Add link to showcase a theme setup via config file 46837195 Init and update of submodules in .gitlab-ci.yml 9e7c2827 Add CSS lang argument to code block 85aad56e Abstract the type in the lookup order 4e1e43e9 Fix broken Pygments url 65b4e79b Correct GitLab project pipelines URL 94af72b5 Fix .Data.Terms usage in taxonomy template example eb371e52 functions: Fix lang.NumFmt docs a745cd6c Fix layouts' folder name in template primer e181e637 Correct typo on GitHub pages guide (#151) 28698500 Remove HTML special chars from Windows install example 96b1f5b5 Remove not needed escape slashes in urls.md 2e05043f Add upgrade instructions using homebrew 2a14624d Fix alias in countrunes.md 5e26bb97 Update docker image for build/publish 01424887 List the internal templates a3ef5be9 Remove string concatenation from add (math) sample 43d12b44 Fix typo 89bafa49 Change to Asciidoc URI 4e14071e Removes an extra bracket (>) in single-page-templates.md 0938e423 Fix typo in http2 server push blog fac55121 Fix typo in deployment with rsync tutorial git-subtree-dir: docs git-subtree-split: 1d052b16a1290ada12f1e28c7c0c373f86741071
2017-09-05 16:09:40 +00:00
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
```
▾ layouts/
▾ post/
li.html
single.html
summary.html
▾ project/
li.html
single.html
summary.html
```
Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
```
▾ layouts/
▾ _default/
li.html
single.html
summary.html
```
## Which Template Will be Rendered?
The following is the [lookup order][lookup] for content views:
1. `/layouts/<TYPE>/<VIEW>.html`
2. `/layouts/_default/<VIEW>.html`
3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
## Example: Content View Inside a List
The following example demonstrates how to use content views inside of your [list templates][lists].
### `list.html`
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
{{< code file="layouts/_default/list.html" download="list.html" >}}
<main id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</main>
{{< /code >}}
### `summary.html`
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
{{< code file="layouts/_default/summary.html" download="summary.html" >}}
<article class="post">
<header>
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
<div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
</header>
{{ .Summary }}
<footer>
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
</footer>
</article>
{{< /code >}}
### `li.html`
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
{{< code file="layouts/_default/li.html" download="li.html" >}}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{< /code >}}
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
[pagevars]: /variables/page/
[render]: /functions/render/
[single]: /templates/single-page-templates/
[spf]: http://spf13.com
[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
[summaries]: /content-management/summaries/
Squashed 'docs/' changes from f887bd7b..1d052b16 1d052b16 Update hosting-on-netlify.md 28b96bec Remove double brackets in Netlify hosting tutorial 373ed38b Update deployment instructions from hugo > 0.20 on Netlify 1bbb41ca Generate static assets on deploy in Nanobox tutorial 816d207f Add missing backtick in templates/views.md bf88e772 Add nanobox as a deployment option 9c37b4cc Change config's syntax order matching description d3cb05a7 Fix wrongly named default value of publishDir 4be85c54 Add link to showcase a theme setup via config file 46837195 Init and update of submodules in .gitlab-ci.yml 9e7c2827 Add CSS lang argument to code block 85aad56e Abstract the type in the lookup order 4e1e43e9 Fix broken Pygments url 65b4e79b Correct GitLab project pipelines URL 94af72b5 Fix .Data.Terms usage in taxonomy template example eb371e52 functions: Fix lang.NumFmt docs a745cd6c Fix layouts' folder name in template primer e181e637 Correct typo on GitHub pages guide (#151) 28698500 Remove HTML special chars from Windows install example 96b1f5b5 Remove not needed escape slashes in urls.md 2e05043f Add upgrade instructions using homebrew 2a14624d Fix alias in countrunes.md 5e26bb97 Update docker image for build/publish 01424887 List the internal templates a3ef5be9 Remove string concatenation from add (math) sample 43d12b44 Fix typo 89bafa49 Change to Asciidoc URI 4e14071e Removes an extra bracket (>) in single-page-templates.md 0938e423 Fix typo in http2 server push blog fac55121 Fix typo in deployment with rsync tutorial git-subtree-dir: docs git-subtree-split: 1d052b16a1290ada12f1e28c7c0c373f86741071
2017-09-05 16:09:40 +00:00
[taxonomylists]: /templates/taxonomy-templates/