page-resources.md (7274B)
1 ---
2 title : "Page Resources"
3 description : "Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata."
4 date: 2018-01-24
5 categories: ["content management"]
6 keywords: [bundle,content,resources]
7 weight: 4003
8 draft: false
9 toc: true
10 linktitle: "Page Resources"
11 menu:
12 docs:
13 parent: "content-management"
14 weight: 31
15 ---
16 Page resources are only accessible from [page bundles]({{< relref
17 "/content-management/page-bundles" >}}), those directories with `index.md` or
18 `_index.md` files at their root. Page resources are only available to the
19 page with which they are bundled.
20
21 In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
22
23 ```text
24 content
25 └── post
26 ├── first-post
27 │ ├── images
28 │ │ ├── a.jpg
29 │ │ ├── b.jpg
30 │ │ └── c.jpg
31 │ ├── index.md (root of page bundle)
32 │ ├── latest.html
33 │ ├── manual.json
34 │ ├── notice.md
35 │ ├── office.mp3
36 │ ├── pocket.mp4
37 │ ├── rating.pdf
38 │ └── safety.txt
39 └── second-post
40 └── index.md (root of page bundle)
41 ```
42
43 ## Properties
44
45 ResourceType
46 : The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
47
48 {{< new-in "0.80.0" >}} Note that we in Hugo `v0.80.0` fixed a bug where non-image resources (e.g. video) would return the MIME sub type, e.g. `json`.
49
50 Name
51 : Default value is the filename (relative to the owning page). Can be set in front matter.
52
53 Title
54 : Default value is the same as `.Name`. Can be set in front matter.
55
56 Permalink
57 : The absolute URL to the resource. Resources of type `page` will have no value.
58
59 RelPermalink
60 : The relative URL to the resource. Resources of type `page` will have no value.
61
62 Content
63 : The content of the resource itself. For most resources, this returns a string
64 with the contents of the file. Use this to create inline resources.
65
66 ```go-html-template
67 {{ with .Resources.GetMatch "script.js" }}
68 <script>{{ .Content | safeJS }}</script>
69 {{ end }}
70
71 {{ with .Resources.GetMatch "style.css" }}
72 <style>{{ .Content | safeCSS }}</style>
73 {{ end }}
74
75 {{ with .Resources.GetMatch "img.png" }}
76 <img src="data:{{ .MediaType }};base64,{{ .Content | base64Encode }}">
77 {{ end }}
78 ```
79
80 MediaType
81 : The MIME type of the resource, such as `image/jpeg`.
82
83 MediaType.MainType
84 : The main type of the resource's MIME type. For example, a file of MIME type `application/pdf` has for MainType `application`.
85
86 MediaType.SubType
87 : The subtype of the resource's MIME type. For example, a file of MIME type `application/pdf` has for SubType `pdf`. Note that this is not the same as the file extension - PowerPoint files have a subtype of `vnd.mspowerpoint`.
88
89 MediaType.Suffixes
90 : A slice of possible suffixes for the resource's MIME type.
91
92 ## Methods
93 ByType
94 : Returns the page resources of the given type.
95
96 ```go
97 {{ .Resources.ByType "image" }}
98 ```
99 Match
100 : Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive.
101
102 ```go
103 {{ .Resources.Match "images/*" }}
104 ```
105
106 GetMatch
107 : Same as `Match` but will return the first match.
108
109 ### Pattern Matching
110 ```go
111 // Using Match/GetMatch to find this images/sunset.jpg ?
112 .Resources.Match "images/sun*" ✅
113 .Resources.Match "**/sunset.jpg" ✅
114 .Resources.Match "images/*.jpg" ✅
115 .Resources.Match "**.jpg" ✅
116 .Resources.Match "*" 🚫
117 .Resources.Match "sunset.jpg" 🚫
118 .Resources.Match "*sunset.jpg" 🚫
119
120 ```
121
122 ## Page Resources Metadata
123
124 The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
125
126 {{% note %}}
127 Resources of type `page` get `Title` etc. from their own front matter.
128 {{% /note %}}
129
130 name
131 : Sets the value returned in `Name`.
132
133 {{% warning %}}
134 The methods `Match` and `GetMatch` use `Name` to match the resources.
135 {{%/ warning %}}
136
137 title
138 : Sets the value returned in `Title`
139
140 params
141 : A map of custom key/values.
142
143
144 ### Resources metadata example
145
146 {{< code-toggle copy="false">}}
147 title: Application
148 date : 2018-01-25
149 resources :
150 - src : "images/sunset.jpg"
151 name : "header"
152 - src : "documents/photo_specs.pdf"
153 title : "Photo Specifications"
154 params:
155 icon : "photo"
156 - src : "documents/guide.pdf"
157 title : "Instruction Guide"
158 - src : "documents/checklist.pdf"
159 title : "Document Checklist"
160 - src : "documents/payment.docx"
161 title : "Proof of Payment"
162 - src : "**.pdf"
163 name : "pdf-file-:counter"
164 params :
165 icon : "pdf"
166 - src : "**.docx"
167 params :
168 icon : "word"
169 {{</ code-toggle >}}
170
171 From the example above:
172
173 - `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`.
174 - `documents/photo_specs.pdf` will get the `photo` icon.
175 - `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`.
176 - Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon.
177 - All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
178 - Every docx in the bundle will receive the `word` icon.
179
180 {{% warning %}}
181 The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
182 {{%/ warning %}}
183
184 ### The `:counter` placeholder in `name` and `title`
185
186 The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`.
187
188 The counter starts at 1 the first time they are used in either `name` or `title`.
189
190 For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
191
192 {{< code-toggle copy="false">}}
193 [[resources]]
194 src = "*specs.pdf"
195 title = "Specification #:counter"
196 [[resources]]
197 src = "**.pdf"
198 name = "pdf-file-:counter"
199 {{</ code-toggle >}}
200
201 the `Name` and `Title` will be assigned to the resource files as follows:
202
203 | Resource file | `Name` | `Title` |
204 |-------------------|-------------------|-----------------------|
205 | checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
206 | guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
207 | other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
208 | photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |