views.md (4444B)
1 ---
2 title: Content View Templates
3 # linktitle: Content Views
4 description: Hugo can render alternative views of your content, which is especially useful in list and summary views.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [templates]
9 keywords: [views]
10 menu:
11 docs:
12 parent: "templates"
13 weight: 70
14 weight: 70
15 sections_weight: 70
16 draft: false
17 aliases: []
18 toc: true
19 ---
20
21 These alternative **content views** are especially useful in [list templates][lists].
22
23 The following are common use cases for content views:
24
25 * You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
26 * 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.
27
28 ## Create a Content View
29
30 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 `posts` 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.
31
32 ```
33 ▾ layouts/
34 ▾ posts/
35 li.html
36 single.html
37 summary.html
38 ▾ project/
39 li.html
40 single.html
41 summary.html
42 ```
43
44 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.
45
46
47 ```
48 ▾ layouts/
49 ▾ _default/
50 li.html
51 single.html
52 summary.html
53 ```
54
55 ## Which Template Will be Rendered?
56
57 The following is the [lookup order][lookup] for content views:
58
59 1. `/layouts/<TYPE>/<VIEW>.html`
60 2. `/layouts/_default/<VIEW>.html`
61 3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
62 4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
63
64 ## Example: Content View Inside a List
65
66 The following example demonstrates how to use content views inside of your [list templates][lists].
67
68 ### `list.html`
69
70 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:
71
72 {{< code file="layouts/_default/list.html" download="list.html" >}}
73 <main id="main">
74 <div>
75 <h1 id="title">{{ .Title }}</h1>
76 {{ range .Pages }}
77 {{ .Render "summary"}}
78 {{ end }}
79 </div>
80 </main>
81 {{< /code >}}
82
83 ### `summary.html`
84
85 Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
86
87 {{< code file="layouts/_default/summary.html" download="summary.html" >}}
88 <article class="post">
89 <header>
90 <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
91 <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
92 </header>
93 {{ .Summary }}
94 <footer>
95 <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
96 </footer>
97 </article>
98 {{< /code >}}
99
100 ### `li.html`
101
102 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" }}`).
103
104 {{< code file="layouts/_default/li.html" download="li.html" >}}
105 <li>
106 <a href="{{ .Permalink }}">{{ .Title }}</a>
107 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
108 </li>
109 {{< /code >}}
110
111 [lists]: /templates/lists/
112 [lookup]: /templates/lookup-order/
113 [pagevars]: /variables/page/
114 [render]: /functions/render/
115 [single]: /templates/single-page-templates/
116 [spf]: https://spf13.com
117 [spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
118 [spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
119 [spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
120 [summaries]: /content-management/summaries/
121 [taxonomylists]: /templates/taxonomy-templates/