Documentation
¶
Overview ¶
Package slots provides experimental named regions backed by child partials.
A slot is a part of a page that a template places by name with {{ slot "name" }}. Slots are looked up from the partial that places them through its ancestors, so a content template can place a slot set on the layout. With options, a slot can also be answered on its own when a partial request targets it (CheckContracts, OmitOOB), or follow every partial response out of band (OOB), or load after the page (Deferred). Glob sets a slot for every file of a directory.
Index ¶
- func DeferredSlot(name string, args ...any) (template.HTML, error)
- func FileName(file string) string
- func FuncMap() template.FuncMap
- func Glob(parent *partial.Partial, pattern string, opts ...Option) error
- func HasSlot(name string, ctx ...*partial.RenderContext) bool
- func Name(p *partial.Partial) string
- func RequiredSlot(name string, ctx ...*partial.RenderContext) (template.HTML, error)
- func Set(parent *partial.Partial, name string, child *partial.Partial, opts ...Option) *partial.Partial
- func Slot(name string, ctx ...*partial.RenderContext) template.HTML
- func Stage() partial.RenderStage
- type Option
- type PlaceholderData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DeferredSlot ¶ added in v0.15.0
DeferredSlot renders a named slot from a render context as one that loads after the page, as Deferred does, whatever the slot's options: on a full page a placeholder that requests the slot from the page's address, and the request for the slot's ID renders the slot, alone when it is standalone (such as with OmitOOB). The placeholder is the slot's own (see Placeholder), or the default one. "reveal" after the name loads it when it scrolls into view, such as htmx's hx-trigger="revealed"; "load", or nothing, as soon as the page loads. Without a request, such as in a render for an e-mail, the slot renders in place. A slot that is not set renders nothing; an out-of-band slot (OOB) cannot be deferred.
It lets a template defer one slot of many set alike, such as a fragment of the slots Glob sets for a directory:
<aside>{{ deferredSlot "popular" "reveal" }}</aside>
go-doc:sig func(name string, mode ...string) (html/template.HTML, error)
func FileName ¶ added in v0.15.0
FileName is the name Glob gives the slot of a file: its base name without its extension, such as "menu" for regions/menu.gohtml.
func Glob ¶ added in v0.15.0
Glob sets a slot on parent for every template file pattern matches in parent's file system, such as "regions/*.gohtml": named after the file without its extension ("menu" for regions/menu.gohtml), rendered by a partial with that ID and the file as its template, with opts (see Set). The files are found as partial.Partial.Glob finds them: with the template cache, once per file system; without, at every call, so new files show. The slots are set in the order of the file names, which is the order slots set with OOB go out of band. It returns an error for a malformed pattern.
err := slots.Glob(root, "fragments/*.gohtml", slots.CheckContracts(), slots.OmitOOB())
func HasSlot ¶
func HasSlot(name string, ctx ...*partial.RenderContext) bool
HasSlot reports whether a named slot exists in a render context.
go-doc:sig func(name string) bool
func RequiredSlot ¶ added in v0.15.0
RequiredSlot renders a named slot from a render context, as Slot does, and fails for a slot that is not set.
go-doc:sig func(name string) (html/template.HTML, error)
func Set ¶
func Set(parent *partial.Partial, name string, child *partial.Partial, opts ...Option) *partial.Partial
Set registers child as the slot name of parent, which templates of parent and of the partials rendered under it place with {{ slot "name" }}. A slot of the same name set on a nearer partial replaces it.
By default the child is registered on parent (see Partial.With), so a partial request that targets the child's ID gets it as any registered child: with the out-of-band regions of its ancestors. Options change that:
// A layout part sent along with every partial response. slots.Set(root, "cart", cart, slots.OOB()) // A part of the page answered on its own, when the page can render it. slots.Set(root, "comments", comments, slots.CheckContracts(), slots.OmitOOB())
func Slot ¶
func Slot(name string, ctx ...*partial.RenderContext) template.HTML
Slot renders a named slot from a render context.
go-doc:sig func(name string) html/template.HTML
func Stage ¶
func Stage() partial.RenderStage
Stage gives templates the slot helpers, bound to the active render context and made only for the templates that call them, and answers partial requests for standalone slots (see CheckContracts).
{{ slot "name" }} renders nothing for a slot that is not set; {{ requiredSlot "name" }} fails the template for it, such as a theme's template that places a fragment the page must have. {{ hasSlot "name" }} tells whether it is set. {{ deferredSlot "name" }} places a slot that loads after the page, as if it were Deferred, and {{ deferredSlot "name" "reveal" }} one that loads when it scrolls into view: the template that places a slot decides, such as for one of the slots Glob sets for a directory of fragments.
Types ¶
type Option ¶ added in v0.15.0
type Option func(*options)
Option configures a slot; see Set.
func CheckContracts ¶ added in v0.15.0
func CheckContracts() Option
CheckContracts makes the slot standalone, answering only when it can render in the tree: its typed roots find their values and its dot has its @dot type (see partial.Runtime.CheckContracts). Otherwise the request is treated as one for an unknown target, which the tree's target fallback answers, if it has one (see partial.Partial.SetTargetFallback).
A standalone slot answers partial requests that target its ID, rendered as a child of the partial being written, through the slots Stage, which must be in use. It is not registered as a child of the partial it is set on: it is found by its ID from the partial being written and its ancestors. Use it for parts of a page that are requested on their own, such as a comment thread a form updates.
func Data ¶ added in v0.15.0
Data gives the slot data of its own for its placeholder, as PlaceholderData.Data, such as the heading of a dashboard panel, so one placeholder template serves several deferred slots:
slots.Set(root, "recent", recent, slots.Placeholder(panel), slots.Data(Heading{Title: "Recent"}))
The data is the placeholder's only; the slot's partial keeps its own dot.
func Deferred ¶ added in v0.15.0
func Deferred() Option
Deferred makes the slot load after the page: on a full page {{ slot }} renders a placeholder that requests the slot from the page's own address, through the connector, such as htmx's hx-get with hx-trigger="load", and the request for the slot's ID renders the slot alone, as a standalone slot answers it (see CheckContracts). A slot whose data is expensive, such as a panel of a dashboard with a lazy dot (see partial.DotFuncOf), then costs nothing for the page itself. It makes the slot standalone; add CheckContracts or OmitOOB as for any standalone slot. Without a request, such as in a render for an e-mail, the slot renders in place.
The default placeholder is an empty <div> with the slot's ID, the connector's attributes and aria-busy="true" (a <turbo-frame> with Turbo); Placeholder renders one of the application's own.
slots.Set(root, "recent", recent, slots.Deferred(), slots.OmitOOB())
func OOB ¶ added in v0.15.0
func OOB() Option
OOB makes the slot a region that follows every partial response: placed by {{ slot }} on a full page, and sent out of band along with the target of every partial request, such as a cart count in the header (see Partial.WithOOB and SetAlwaysSwapOOB). A request for the partial the slot is set on gets it where that partial's template places it, else out of band. Its template marks its element as out of band with {{ oobAttr }}.
func OmitOOB ¶ added in v0.15.0
func OmitOOB() Option
OmitOOB makes the slot standalone (see CheckContracts), and answers partial requests for it with the slot alone, without the out-of-band regions of the tree (see partial.RenderContext.OmitOOB).
func Placeholder ¶ added in v0.15.0
Placeholder renders the placeholder of a deferred slot with p, with a PlaceholderData dot, such as a panel that shows it is loading:
<section id="{{ .ID }}" class="panel"{{ .Attrs }} aria-busy="true">Loading…</section>
Its element must carry the ID and the attributes. p renders as a child of the partial that places the slot, from its file system; p is not changed. It implies Deferred.
type PlaceholderData ¶ added in v0.15.0
type PlaceholderData struct {
// ID is the ID of the slot's partial, which the placeholder's
// element carries, so its request targets the slot.
ID string
// Name is the slot's name.
Name string
// URL is the address the placeholder requests: that of the page.
URL string
// Attrs are the connector's attributes that make the element
// request the slot and swap it in, such as hx-get, hx-trigger,
// hx-target and hx-swap for htmx.
Attrs template.HTMLAttr
// Data is the data of the slot's own that Data gives it, such as
// the heading of a dashboard panel, so one placeholder template
// serves several slots; nil without.
Data any
}
PlaceholderData is the dot of the placeholder of a deferred slot; see Placeholder.
Source Files