mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-14 12:34:44 -04:00
Update order significance section, add counter section
- Fix the order significance explanation for resources - Add a sub-section on use of :counter in name and title - Make the YAML and TOML resources example match - Minor typo fixes
This commit is contained in:
Kaushal Modi
Bjørn Erik Pedersen
parent
3b18365092
commit
830576f866
@ -1,6 +1,6 @@
|
||||
---
|
||||
title : "Page Resources"
|
||||
description : "Page Resources are files included in a page bundle. You can use them in your template and add metadata"
|
||||
description : "Page Resources are files included in a page bundle. You can use them in your template and add metadata."
|
||||
date : 2018-01-24T13:10:00-05:00
|
||||
lastmod : 2018-01-26T13:45:08-05:00
|
||||
categories : ["content management"]
|
||||
@ -17,7 +17,7 @@ menu :
|
||||
## Properties
|
||||
|
||||
ResourceType
|
||||
: The main type of the resource. For exemple a file of MIME type `image/jpg` has for ResourceType `image`.
|
||||
: The main type of the resource. For example, a file of MIME type `image/jpg` has for ResourceType `image`.
|
||||
|
||||
Name
|
||||
: The filename (relative path to the bundle). It can be overwritten with the resource's Front Matter metadata.
|
||||
@ -26,31 +26,31 @@ Title
|
||||
: Same as filename. It can be overwritten with the resource's Front Matter metadata.
|
||||
|
||||
Permalink
|
||||
: The absolute URL of the resource.
|
||||
: The absolute URL of the resource. This gets a value only where the _ResourceType_ is **not** `page`.
|
||||
|
||||
RelPermalink
|
||||
: The relative URL of the resource.
|
||||
: The relative URL of the resource. This gets a value only where the _ResourceType_ is **not** `page`.
|
||||
|
||||
## Methods
|
||||
ByType
|
||||
: Retrieve the page resources of the passed type.
|
||||
|
||||
```go
|
||||
{{ .Resources.ByType "images" }}
|
||||
{{ .Resources.ByType "image" }}
|
||||
```
|
||||
Match
|
||||
: Retrieve all the page resources whose Name matches the [Glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) passed as parameter. The matching is case insensitive.
|
||||
: Retrieve all the page resources (as a slice) whose `Name` matches the Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)) passed as parameter. The matching is case-insensitive.
|
||||
|
||||
```go
|
||||
{{ .Resources.Match "images/*" }}
|
||||
```
|
||||
|
||||
GetMatch
|
||||
: Same as Match but will only retrieve the first matching resource.
|
||||
: Same as `Match` but will only retrieve the first matching resource.
|
||||
|
||||
### Pattern Matching
|
||||
```go
|
||||
//Using Match/GetMatch to find this images/sunset.jpg ?
|
||||
// Using Match/GetMatch to find this images/sunset.jpg ?
|
||||
.Resources.Match "images/sun*" ✅
|
||||
.Resources.Match "**/Sunset.jpg" ✅
|
||||
.Resources.Match "images/*.jpg" ✅
|
||||
@ -63,7 +63,7 @@ GetMatch
|
||||
|
||||
## Metadata
|
||||
|
||||
Page Resources metadata is managed from their page's Front Matter with an array named `resources`. Batch assign is made possible using glob pattern matching.
|
||||
Page Resources metadata is managed from their page's Front Matter with an array/table parameter named `resources`. Batch assign is made possible using glob pattern matching.
|
||||
|
||||
### Available metadata
|
||||
|
||||
@ -82,53 +82,44 @@ params
|
||||
`{{ .Params.credits }}`
|
||||
|
||||
### Example
|
||||
#### `resources` parameter in YAML
|
||||
~~~yaml
|
||||
title: Application
|
||||
date : 2018-01-25
|
||||
resources :
|
||||
- src : "images/header.*"
|
||||
name : "header"
|
||||
- src : "**.pdf"
|
||||
title = "PDF file #:counter"
|
||||
params :
|
||||
icon : "pdf"
|
||||
- src : "**.docx"
|
||||
title : "Word file #:counter"
|
||||
params :
|
||||
icon : "word"
|
||||
- src : "documents/photo_specs.pdf"
|
||||
title : "Photo Specifications"
|
||||
params:
|
||||
icon : "image"
|
||||
icon : "photo"
|
||||
- src : "documents/guide.pdf"
|
||||
title : "Instruction Guide"
|
||||
- src : "documents/checklist.pdf"
|
||||
title : "Document Checklist"
|
||||
- src : "documents/payment.docx"
|
||||
title : "Proof of Payment"
|
||||
- src : "**.pdf"
|
||||
name : "pdf-file-:counter"
|
||||
params :
|
||||
icon : "pdf"
|
||||
- src : "**.docx"
|
||||
params :
|
||||
icon : "word"
|
||||
~~~
|
||||
|
||||
#### `resources` parameter in TOML
|
||||
~~~toml
|
||||
title = Application
|
||||
date : 2018-01-25
|
||||
[[resources]]
|
||||
src = "images/header.*"
|
||||
name = "header"
|
||||
[[resources]]
|
||||
src = "**.pdf"
|
||||
title = "PDF file #:counter"
|
||||
[resources.params]
|
||||
icon = "pdf"
|
||||
[[resources]]
|
||||
src = "**.docx"
|
||||
title = "Word file #:counter"
|
||||
[resources.params]
|
||||
icon = "word"
|
||||
[[resources]]
|
||||
src = "documents/photo_specs.pdf"
|
||||
title = "Photo Specifications"
|
||||
[resources.params]
|
||||
icon = "photo"
|
||||
[resources.params]
|
||||
icon = "photo"
|
||||
[[resources]]
|
||||
src = "documents/guide.pdf"
|
||||
title = "Instruction Guide"
|
||||
@ -138,19 +129,53 @@ date : 2018-01-25
|
||||
[[resources]]
|
||||
src = "documents/payment.docx"
|
||||
title = "Proof of Payment"
|
||||
~~~
|
||||
[[resources]]
|
||||
src = "**.pdf"
|
||||
name = "pdf-file-:counter"
|
||||
[resources.params]
|
||||
icon = "pdf"
|
||||
[[resources]]
|
||||
src = "**.docx"
|
||||
[resources.params]
|
||||
icon = "word"
|
||||
~~~
|
||||
|
||||
|
||||
From the metadata example above:
|
||||
|
||||
- `header.jpg` will receive a new `Name` and won't be retrieved by `.Match "*/header.jpg"` anymore but something like `.Match "header"`.
|
||||
- `documents/photo_specs.pdf` will get the `image` icon
|
||||
- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will receive a unique Title
|
||||
- Every pdf in the bundle exepct documents/photo_specs.pdf` will receive the `pdf` icon along with a Title using the keyword `:counter`
|
||||
- Every docx in the bundle will receive the `word` icon along with a Title using the keyword `:counter`
|
||||
- `header.jpg` will receive a new `Name` and won't be retrieved by `.Match "*/header.jpg"` anymore, but something like `.Match "header"`.
|
||||
- `documents/photo_specs.pdf` will get the `photo` icon.
|
||||
- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will receive `Title` as set by `title`.
|
||||
- Every pdf in the bundle except `documents/photo_specs.pdf` will receive the `pdf` icon.
|
||||
- All pdf files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#counter). That will cause the retrieved pdf files to have names `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
|
||||
- Every docx in the bundle will receive the `word` icon.
|
||||
|
||||
{{% warning %}}
|
||||
The __order matters__, every metadata key/value pair assigned overwrites any previous ones assigned to the same `src` target. As in the example above broad targets rules will usually be defined before the narrower ones.
|
||||
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. For example, in the above example, `.Params.icon` is already 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.
|
||||
{{%/ warning %}}
|
||||
|
||||
### `:counter` placeholder in `name` and `title` {#counter}
|
||||
|
||||
The `:counter` is a special placeholder recognized in `name` and `title` parameters in the `resources` Front Matter.
|
||||
|
||||
If the `name` value contains the `":counter"` string, a "name-counter" is initialized to 1, and if the `title` value contains the same string, a separate "title-counter" is initialized to 1 as well.
|
||||
|
||||
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:
|
||||
|
||||
~~~toml
|
||||
[[resources]]
|
||||
src = "*specs.pdf"
|
||||
title = "Specifications #:counter"
|
||||
[[resources]]
|
||||
src = "**.pdf"
|
||||
name = "pdf-file-:counter"
|
||||
~~~
|
||||
|
||||
the `Name` and `Title` will be assigned to the resource files as follows:
|
||||
|
||||
| Resource file | `Name` | `Title` |
|
||||
|-------------------|-------------------|-----------------------|
|
||||
| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
|
||||
| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
|
||||
| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specifications #1"` |
|
||||
| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specifications #2"` |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user