hugo/docs/content/content-management/page-resources.md
2018-01-31 11:08:08 +01:00

5.3 KiB

title description date categories keywords weight draft toc linktitle menu
Page Resources Page Resources -- images, other pages, documents etc. -- have page-relative URLs and their own metadata. 2018-01-24
content management
bundle
content
resources
4003 false true Page Resources
docs
parent weight
content-management 31

Properties

ResourceType
The main type of the resource. For example, a file of MIME type image/jpg has for ResourceType image.
Name
Default value is the filename (relative to the owning page). Can be set in front matter.
Title
Default blank. Can be set in front matter.
Permalink
The absolute URL to the resource. Resources of type page will have no value.
RelPermalink
The relative URL to the resource. Resources of type page will have no value.

Methods

ByType
Returns the page resources of the given type.
{{ .Resources.ByType "image" }}
Match
Returns all the page resources (as a slice) whose Name matches the given Glob pattern (examples). The matching is case-insensitive.
{{ .Resources.Match "images/*" }}
GetMatch
Same as Match but will return the first match.

Pattern Matching

// Using Match/GetMatch to find this images/sunset.jpg ?
.Resources.Match "images/sun*" 
.Resources.Match "**/Sunset.jpg" 
.Resources.Match "images/*.jpg" 
.Resources.Match "**.jpg" 
.Resources.Match "*" 🚫
.Resources.Match "sunset.jpg" 🚫
.Resources.Match "*sunset.jpg" 🚫

Page Resources Metadata

Page Resources' metadata is managed from their page's front matter with an array/table parameter named resources. You can batch assign values using a wildcards.

{{% note %}} Resources of type page get Title etc. from their own front matter. {{% /note %}}

name
Sets the value returned in Name.

{{% warning %}} The methods Match and GetMatch use Name to match the resources. {{%/ warning %}}

title
Sets the value returned in Title
params
A map of custom key/values.

Resources metadata: YAML Example

title: Application
date : 2018-01-25
resources :
- src : "images/sunset.jpg"
  name : "header"
- src : "documents/photo_specs.pdf"
  title : "Photo Specifications"
  params:
    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 metadata: TOML Example

title = Application
date : 2018-01-25
[[resources]]
  src = "images/sunset.jpg"
  name = "header"
[[resources]]
  src = "documents/photo_specs.pdf"
  title = "Photo Specifications"
  [resources.params]
    icon = "photo"
[[resources]]
  src = "documents/guide.pdf"
  title = "Instruction Guide"
[[resources]]
  src = "documents/checklist.pdf"
  title = "Document Checklist"
[[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 example above:

  • sunset.jpg will receive a new Name and can now be found with .GetMatch "header".
  • documents/photo_specs.pdf will get the photo icon.
  • documents/checklist.pdf, documents/guide.pdf and documents/payment.docx will get Title as set by title.
  • Every PDF in the bundle except documents/photo_specs.pdf will get the pdf icon.
  • All PDF files will get a new Name. The name parameter contains a special placeholder :counter, so the Name will be pdf-file-1, pdf-file-2, pdf-file-3.
  • Every docx in the bundle will receive the word icon.

{{% warning %}} 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 %}}

The :counter placeholder in name and title

The :counter is a special placeholder recognized in name and title parameters resources.

The counter starts at 1 the first time they are used in either name or title.

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:

[[resources]]
  src = "*specs.pdf"
  title = "Specification #: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 "Specification #1"
photo_specs.pdf "pdf-file-4.pdf "Specification #2"