alerts, toast amd breadcrum

template-helpers.md

@@ -0,0 +1,226 @@
+# 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>
+```