226 lines
4 KiB
Markdown
226 lines
4 KiB
Markdown
# Go Template Helpers
|
|
|
|
Custom `html/template` FuncMap extensions that bring Liquid-like expressiveness to Go server-side templates.
|
|
|
|
---
|
|
|
|
## String Helpers
|
|
|
|
### `capitalize`
|
|
|
|
Uppercases the first letter of a string and lowercases the rest.
|
|
|
|
```html
|
|
<h2>{{capitalize .Title}}</h2>
|
|
```
|
|
|
|
---
|
|
|
|
### `truncate`
|
|
|
|
Cuts a string to at most `n` characters and appends `…` if trimmed. Designed for pipeline use — pass `n` first.
|
|
|
|
```html
|
|
<p>{{.Excerpt | truncate 120}}</p>
|
|
```
|
|
|
|
---
|
|
|
|
### `prepend`
|
|
|
|
Adds a prefix to the beginning of a string. Designed for pipeline use — pass the prefix first.
|
|
|
|
```html
|
|
<a href="{{.Slug | prepend "/articles/"}}">Read more</a>
|
|
```
|
|
|
|
---
|
|
|
|
### `strAppend`
|
|
|
|
Adds a suffix to the end of a string. Designed for pipeline use — pass the suffix first.
|
|
|
|
```html
|
|
<a href="{{.Slug | strAppend ".html"}}">Read more</a>
|
|
```
|
|
|
|
---
|
|
|
|
### `split`
|
|
|
|
Divides a string into a slice of substrings by a separator. Designed for pipeline use — pass the separator first. Useful combined with `range` or `join`.
|
|
|
|
```html
|
|
{{range split "," .TagString}}
|
|
<span class="tag">{{.}}</span>
|
|
{{end}}
|
|
```
|
|
|
|
---
|
|
|
|
### `join`
|
|
|
|
Concatenates a string slice into a single string with a separator.
|
|
|
|
```html
|
|
<p class="tags">{{join .Tags " · "}}</p>
|
|
```
|
|
|
|
---
|
|
|
|
## Number Helpers
|
|
|
|
### `fmtNumber`
|
|
|
|
Formats an integer or float with thousands separators using the English locale.
|
|
|
|
```html
|
|
<span>{{fmtNumber .Views}} views</span>
|
|
<span>$ {{fmtNumber .Price}}</span>
|
|
```
|
|
|
|
---
|
|
|
|
## Date & Time Helpers
|
|
|
|
### `fmtDate`
|
|
|
|
Formats a `time.Time` value using a named layout or any custom Go layout string.
|
|
|
|
| Named layout | Output example |
|
|
|---|---|
|
|
| `"short"` | `02 Jan 2006` |
|
|
| `"long"` | `02 January 2006` |
|
|
| `"iso"` | `2006-01-02` |
|
|
| `"datetime"` | `02 Jan 2006 15:04` |
|
|
|
|
```html
|
|
<time>{{fmtDate .PublishedAt "short"}}</time>
|
|
<time>{{fmtDate .PublishedAt "02/01/2006"}}</time>
|
|
```
|
|
|
|
---
|
|
|
|
### `timeAgo`
|
|
|
|
Returns a human-readable relative time string from now (`"just now"`, `"3 hours ago"`, `"2 days ago"`, etc.).
|
|
|
|
```html
|
|
<span class="meta">Published {{timeAgo .PublishedAt}}</span>
|
|
```
|
|
|
|
---
|
|
|
|
## Collection Helpers
|
|
|
|
### `first`
|
|
|
|
Returns the first element of a slice, or `nil` if the slice is empty.
|
|
|
|
```html
|
|
{{with first .Articles}}
|
|
<h2>{{capitalize .Title}}</h2>
|
|
{{end}}
|
|
```
|
|
|
|
---
|
|
|
|
### `last`
|
|
|
|
Returns the last element of a slice, or `nil` if the slice is empty.
|
|
|
|
```html
|
|
{{with last .Articles}}
|
|
<p>Latest: {{capitalize .Title}}</p>
|
|
{{end}}
|
|
```
|
|
|
|
---
|
|
|
|
### `sliceOf`
|
|
|
|
Returns a sub-range of a slice from index `start` (inclusive) to `end` (exclusive).
|
|
|
|
```html
|
|
{{range sliceOf .Articles 0 3}}
|
|
<li>{{capitalize .Title}}</li>
|
|
{{end}}
|
|
```
|
|
|
|
---
|
|
|
|
### `contains`
|
|
|
|
Reports whether an item is present in a slice, or a substring exists within a string.
|
|
|
|
```html
|
|
{{if contains .Tags "go"}}
|
|
<span class="badge">Go</span>
|
|
{{end}}
|
|
|
|
{{if contains .Bio "engineer"}}
|
|
<p>Engineering post</p>
|
|
{{end}}
|
|
```
|
|
|
|
---
|
|
|
|
## Logic Helpers
|
|
|
|
### `defaultVal`
|
|
|
|
Returns a fallback value if the given value is nil or its zero value.
|
|
|
|
```html
|
|
<p>{{defaultVal "No subtitle" .Subtitle}}</p>
|
|
```
|
|
|
|
---
|
|
|
|
### `ternary`
|
|
|
|
Returns `trueVal` if the condition is true, `falseVal` otherwise. Pass the true value first, then the false value, then the condition.
|
|
|
|
```html
|
|
<span>{{ternary "Active" "Inactive" .IsActive}}</span>
|
|
```
|
|
|
|
---
|
|
|
|
### `coalesce`
|
|
|
|
Returns the first non-empty, non-nil value from a list of arguments.
|
|
|
|
```html
|
|
<h3>{{coalesce .Nickname .FullName "Anonymous"}}</h3>
|
|
```
|
|
|
|
---
|
|
|
|
## Struct Helpers
|
|
|
|
### `hasField`
|
|
|
|
Reports whether a struct has a field with the given name. Useful for rendering shared templates across different data types.
|
|
|
|
```html
|
|
{{if hasField . "Subtitle"}}
|
|
<p class="subtitle">{{.Subtitle}}</p>
|
|
{{end}}
|
|
```
|
|
|
|
---
|
|
|
|
## Pipeline Chaining
|
|
|
|
Helpers designed for pipeline use (`truncate`, `prepend`, `strAppend`, `split`) accept their configuration argument first and the input string last, so they compose naturally with `|`.
|
|
|
|
```html
|
|
{{/* chain multiple helpers */}}
|
|
<td>{{.Title | capitalize | truncate 40}}</td>
|
|
|
|
{{/* build a URL from a slug */}}
|
|
<a href="{{.Slug | prepend "/blog/" | strAppend ".html"}}">
|
|
{{.Title | capitalize}}
|
|
</a>
|
|
```
|