mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
Squashed 'docs/' changes from 417593493..4d936aee6
4d936aee6 Fix function signatures 8182a27ed Simplify example usage of apply function git-subtree-dir: docs git-subtree-split: 4d936aee622b779ef5541154750b51051dc0bf14
This commit is contained in:
Bjørn Erik Pedersen
parent
3710a5ec7e
commit
aaaf1c8df5
4 changed files with 55 additions and 133 deletions
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: collections.Apply
|
||||
linkTitle: apply
|
||||
description: Given an array or slice, `apply` returns a new slice with a function applied over it.
|
||||
description: Returns a new collection with each element transformed by the given function.
|
||||
categories: [functions]
|
||||
keywords: []
|
||||
menu:
|
||||
|
|
@ -9,8 +9,8 @@ menu:
|
|||
parent: functions
|
||||
function:
|
||||
aliases: [apply]
|
||||
returnType: any
|
||||
signatures: ['collections.Apply COLLECTION FUNCTION [PARAM...]']
|
||||
returnType: '[]any'
|
||||
signatures: [collections.Apply COLLECTION FUNCTION PARAM...]
|
||||
relatedFunctions:
|
||||
- collections.Apply
|
||||
- collections.Delimit
|
||||
|
|
@ -21,95 +21,17 @@ relatedFunctions:
|
|||
aliases: [/functions/apply]
|
||||
---
|
||||
|
||||
`apply` expects at least three arguments, depending on the function being applied.
|
||||
The `apply` function takes three or more arguments, depending on the function being applied to the collection elements.
|
||||
|
||||
1. The first argument is the sequence to operate on.
|
||||
2. The second argument is the name of the function as a string, which must be the name of a valid [template function].
|
||||
3. After that, the arguments to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against.
|
||||
The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element.
|
||||
|
||||
Here is an example of a content file with `names:` as a front matter field:
|
||||
|
||||
{{< code-toggle file="content/example.md" fm=true copy=false >}}
|
||||
title: Example
|
||||
names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You can then use `apply` as follows:
|
||||
|
||||
```go-html-template
|
||||
{{ apply .Params.names "urlize" "." }}
|
||||
{{ $s := slice "hello" "world" }}
|
||||
|
||||
{{ $s = apply $s "strings.FirstUpper" "." }}
|
||||
{{ $s }} → [Hello World]
|
||||
|
||||
{{ $s = apply $s "strings.Replace" "." "l" "_" }}
|
||||
{{ $s }} → [He__o Wor_d]
|
||||
```
|
||||
|
||||
Which will result in the following:
|
||||
|
||||
```
|
||||
"derek-perkins", "joe-bergevin", "tanner-linsley"
|
||||
```
|
||||
|
||||
This is *roughly* equivalent to using the following with [`range`]:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Params.names }}{{ . | urlize }}{{ end }}
|
||||
```
|
||||
|
||||
However, it is not possible to provide the output of a range to the [`delimit`]function, so you need to `apply` it.
|
||||
|
||||
If you have `post-tag-list.html` and `post-tag-link.html` as [partials], you *could* use the following snippets, respectively:
|
||||
|
||||
{{< code file="layouts/partials/post-tag-list.html" copy=false >}}
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $len := len . }}
|
||||
{{ if eq $len 1 }}
|
||||
{{ partial "post-tag-link.html" (index . 0) }}
|
||||
{{ else }}
|
||||
{{ $last := sub $len 1 }}
|
||||
{{ range first $last . }}
|
||||
{{ partial "post-tag-link.html" . }},
|
||||
{{ end }}
|
||||
{{ partial "post-tag-link.html" (index . $last) }}
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file="layouts/partials/post-tag-link.html" copy=false >}}
|
||||
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
|
||||
{{< /code >}}
|
||||
|
||||
This works, but the complexity of `post-tag-list.html` is fairly high. The Hugo template needs to perform special behavior for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like `Tags: tag1 , tag2 , tag3` because of the way that the HTML is generated and then interpreted by a browser.
|
||||
|
||||
This first version of `layouts/partials/post-tag-list.html` separates all of the operations for ease of reading. The combined and DRYer version is shown next:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $sort := sort . }}
|
||||
{{ $links := apply $sort "partial" "post-tag-link.html" "." }}
|
||||
{{ $clean := apply $links "chomp" "." }}
|
||||
{{ delimit $clean ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [`chomp`] stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example:
|
||||
|
||||
{{< code file="layouts/partials/post-tag-list.html" >}}
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ delimit (apply (apply (sort .) "partial" "post-tag-link.html" ".") "chomp" ".") ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
`apply` does not work when receiving the sequence as an argument through a pipeline.
|
||||
{{% /note %}}
|
||||
|
||||
[`chomp`]: /functions/strings/chomp/
|
||||
[`delimit`]: /functions/collections/delimit/
|
||||
[template function]: /functions/
|
||||
[`range`]: /functions/go-template/range/
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@ See [images.Filter](#filter) for how to apply these filters to an image.
|
|||
|
||||
{{< new-in "0.119.0" >}}
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Process SRC SPEC
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
A general purpose image processing function.
|
||||
|
||||
|
|
@ -36,9 +36,9 @@ This filter has all the same options as the [Process](/content-management/image-
|
|||
|
||||
## Overlay
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Overlay SRC X Y
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Overlay creates a filter that overlays the source image at position x y, e.g:
|
||||
|
||||
|
|
@ -60,9 +60,9 @@ The above will overlay `$logo` in the upper left corner of `$img` (at position `
|
|||
|
||||
{{< new-in "0.119.0" >}}
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Opacity SRC OPACITY
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Opacity creates a filter that changes the opacity of an image.
|
||||
The OPACITY parameter must be in range (0, 1).
|
||||
|
|
@ -84,9 +84,9 @@ This filter is most useful for target formats that support transparency, e.g. PN
|
|||
|
||||
Using the `Text` filter, you can add text to an image.
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Text TEXT MAP)
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
The following example will add the text `Hugo rocks!` to the image with the specified color, size and position.
|
||||
|
||||
|
|
@ -115,27 +115,27 @@ You can load a custom font if needed. Load the font as a Hugo `Resource` and set
|
|||
|
||||
## Brightness
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Brightness PERCENTAGE
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Brightness creates a filter that changes the brightness of an image.
|
||||
The percentage parameter must be in range (-100, 100).
|
||||
|
||||
### ColorBalance
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.ColorBalance PERCENTAGERED PERCENTAGEGREEN PERCENTAGEBLUE
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
ColorBalance creates a filter that changes the color balance of an image.
|
||||
The percentage parameters for each color channel (red, green, blue) must be in range (-100, 500).
|
||||
|
||||
## Colorize
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Colorize HUE SATURATION PERCENTAGE
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Colorize creates a filter that produces a colorized version of an image.
|
||||
The hue parameter is the angle on the color wheel, typically in range (0, 360).
|
||||
|
|
@ -144,18 +144,18 @@ The percentage parameter specifies the strength of the effect, it must be in ran
|
|||
|
||||
## Contrast
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Contrast PERCENTAGE
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Contrast creates a filter that changes the contrast of an image.
|
||||
The percentage parameter must be in range (-100, 100).
|
||||
|
||||
## Gamma
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Gamma GAMMA
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Gamma creates a filter that performs a gamma correction on an image.
|
||||
The gamma parameter must be positive. Gamma = 1 gives the original image.
|
||||
|
|
@ -163,75 +163,75 @@ Gamma less than 1 darkens the image and gamma greater than 1 lightens it.
|
|||
|
||||
## GaussianBlur
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.GaussianBlur SIGMA
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
GaussianBlur creates a filter that applies a gaussian blur to an image.
|
||||
|
||||
## Grayscale
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Grayscale
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Grayscale creates a filter that produces a grayscale version of an image.
|
||||
|
||||
## Hue
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Hue SHIFT
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Hue creates a filter that rotates the hue of an image.
|
||||
The hue angle shift is typically in range -180 to 180.
|
||||
|
||||
## Invert
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Invert
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Invert creates a filter that negates the colors of an image.
|
||||
|
||||
## Pixelate
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Pixelate SIZE
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Pixelate creates a filter that applies a pixelation effect to an image.
|
||||
|
||||
## Saturation
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Saturation PERCENTAGE
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Saturation creates a filter that changes the saturation of an image.
|
||||
|
||||
## Sepia
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Sepia PERCENTAGE
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Sepia creates a filter that produces a sepia-toned version of an image.
|
||||
|
||||
## Sigmoid
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.Sigmoid MIDPOINT FACTOR
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Sigmoid creates a filter that changes the contrast of an image using a sigmoidal function and returns the adjusted image.
|
||||
It's a non-linear contrast change useful for photo adjustments as it preserves highlight and shadow detail.
|
||||
|
||||
## UnsharpMask
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.UnsharpMask SIGMA AMOUNT THRESHOLD
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
UnsharpMask creates a filter that sharpens an image.
|
||||
The sigma parameter is used in a gaussian function and affects the radius of effect.
|
||||
|
|
@ -243,9 +243,9 @@ The threshold parameter controls the minimum brightness change that will be shar
|
|||
|
||||
### Filter
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
IMAGE | images.Filter FILTERS...
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
Can be used to apply a set of filters to an image:
|
||||
|
||||
|
|
@ -261,9 +261,9 @@ Parses the image and returns the height, width, and color model.
|
|||
|
||||
The `imageConfig` function takes a single parameter, a file path (_string_) relative to the _project's root directory_, with or without a leading slash.
|
||||
|
||||
{{% funcsig %}}
|
||||
{{< funcsig >}}
|
||||
images.ImageConfig PATH
|
||||
{{% /funcsig %}}
|
||||
{{< /funcsig >}}
|
||||
|
||||
```go-html-template
|
||||
{{ with (imageConfig "favicon.ico") }}
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
{{- if $.Params.function.returnType }}
|
||||
{{- $signature = printf "%s ⟼ %s" . $.Params.function.returnType }}
|
||||
{{- end }}
|
||||
<pre class="f5 mb4 ph3 pv2 bg-light-gray" style="border-left:4px solid #0594CB;">
|
||||
<pre class="f5 mb4 ph3 pv2 bg-light-gray overflow-x-auto" style="border-left:4px solid #0594CB;">
|
||||
{{- $signature -}}
|
||||
</pre>
|
||||
{{- end }}
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
<h4 class="minor mb1 pt2 primary-color-dark">Syntax</h4>
|
||||
<pre class="f5 mb4 ph3 pv2 bg-light-gray" style="border-left:4px solid #0594CB;">
|
||||
<pre class="f5 mb4 ph3 pv2 bg-light-gray overflow-x-auto" style="border-left:4px solid #0594CB;">
|
||||
{{- .Inner -}}
|
||||
</pre>
|
||||
</pre>
|
||||
|
|
|
|||
Loading…
Reference in a new issue