interactions

package
v0.15.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 1, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package interactions contains optional client-interaction template helpers.

The core go-partial package does not register these helpers automatically. Applications opt in with: 

root.SetFunc(interactions.FuncMap())

Index

Constants

View Source 
const (
	// SwapInnerHTML replaces the target element's inner HTML.
	SwapInnerHTML = string(connector.SwapInnerHTML)
	// SwapOuterHTML replaces the target element itself.
	SwapOuterHTML = string(connector.SwapOuterHTML)
)
View Source 
const ClientName = "partial-interactions.js"

ClientName is the name of the browser client in the file system of go-partial's clients package.

View Source 
const RenderKindInteraction partial.RenderKind = "interaction"

RenderKindInteraction is the renderer kind used for interaction markup.

Variables

This section is empty.

Functions

func Async 

func Async(runtime *partial.Runtime, value any, args ...any) template.HTML

Async renders an async interaction. Pass either an endpoint string with optional key/value parameters or an Interaction configured in Go.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTML go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTML

func AsyncAttrs added in v0.15.0 

func AsyncAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

AsyncAttrs returns the attributes of an async interaction, for an element of the template's own, such as <section {{ asyncAttrs runtime "/stats" }}>. Without a target or id, the element itself is the target. Arguments are those of Async.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

func Attrs added in v0.15.0 

func Attrs(kind connector.InteractionKind, value any, runtime *partial.Runtime, args ...any) template.HTMLAttr

Attrs returns the connector attributes of an interaction, without the wrapper element Render adds, for an element of the template's own; the attributes start with a space. Without a target or id, the interaction targets the element it is placed on (connector.TargetSelf). An invalid interaction returns a data-partial-error attribute with the error.

func AttrsFuncMap added in v0.15.0 

func AttrsFuncMap() template.FuncMap

AttrsFuncMap returns the interaction helpers that write attributes on an element of the template's own: asyncAttrs, revealAttrs, pollAttrs, onAttrs, streamAttrs, refreshAttrs, submitAttrs, liveAttrs, clientAttrs, noBoost and confirmAttr. Their names end in Attrs or say what they write, so they do not clash with an application's functions, such as a "poll" of its own, as FuncMap's async, poll or on may. 

root.SetFunc(interactions.AttrsFuncMap())

func ClientAttrs added in v0.15.0 

func ClientAttrs(runtime *partial.Runtime, pairs ...any) template.HTMLAttr

ClientAttrs returns the connector's attributes for how its client library treats a link or form of the template's own, or the elements in a body or container (see connector.Attr), from key/value pairs: "confirm" asks a question first, "boost" is "on" or "off", "target" and "swap" say where and how the response is swapped in: <a href="/logout" {{ clientAttrs runtime "confirm" "Log out?" "boost" "off" }}>.

For settings of a whole page, "inherit" "true" gives them to the element's descendants, "disableWhileRequest" names the elements disabled while a request is under way, and "keepOnServerError" "true" leaves the page as it is on a 5xx response: 

<body {{ clientAttrs runtime "inherit" "true" "boost" "on" "target" "#content" "swap" "outerHTML"
        "disableWhileRequest" "find button[type='submit']" "keepOnServerError" "true" }}>

"submitConfirm" asks a question before a submit button sends its form, with the browser client of this package (ClientScript) where the client library cannot: <button type="submit" {{ clientAttrs runtime "submitConfirm" "Delete for good?" }}>.

"reloadOnError" "true" makes a link or form whose request gets a 5xx status, or no answer, load as a whole page, so the visitor sees what went wrong rather than nothing, also with "keepOnServerError": a link is followed and a GET form submitted again by the browser itself. A POST, PUT, PATCH or DELETE form is never sent twice: the server's HTML error page replaces the page; without one the page stays and partial:reload-on-error:failed is dispatched on the form. It is the same attribute with every connector (connector.ReloadOnErrorAttr), which the browser client of this package reads; on the body it applies to every link and form.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, pairs ...any) html/template.HTMLAttr

func ClientScript added in v0.15.0 

func ClientScript() []byte

ClientScript returns the browser client of the attributes that client libraries cannot do themselves: a submit button with data-partial-confirm (clientAttrs "submitConfirm", or connector.Attr.SubmitConfirm) asks its question before it sends its form, with htmx, Unpoly or none. Turbo reads data-turbo-confirm from the button itself.

A page with a <dialog data-partial-confirm-dialog> asks these questions, and htmx's hx-confirm, in that dialog instead of with window.confirm, which some embedded browsers never show. The question goes into the dialog's element with data-partial-confirm-question, and a button with value="confirm" answers yes; Escape or another button answers no.

A link or form in or with data-partial-reload-on-error (clientAttrs "reloadOnError", or connector.Attr.ReloadOnError) whose request gets a 5xx status or no answer loads as a whole page instead: a link is followed and a GET form submitted again by the browser itself. A POST, PUT, PATCH or DELETE is never sent twice: the HTML error page the server answered replaces the page; without one, or without an answer, the page stays and partial:reload-on-error:failed is dispatched on the link or form. It handles the requests of htmx 2 and 4, and those of Unpoly and Turbo that get no answer.

The error page written in place of the page keeps the page's Content-Security-Policy: under a policy without 'unsafe-inline', the page's style-src needs the hash of the error page's inline <style>, such as ext/errors' StyleHash for go-partial's built-in error page, or the application answers with an error template that has no inline style.

The client needs no build step and no other library; serve it from the file system of go-partial's clients package, or include it in your own bundle.

func ConfirmAttr added in v0.15.0 

func ConfirmAttr(runtime *partial.Runtime, question string) template.HTMLAttr

ConfirmAttr returns the attribute that asks question before a link is followed or a form submitted, such as hx-confirm with htmx: <button {{ confirmAttr runtime "Delete this page?" }}>.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, question string) html/template.HTMLAttr

func FuncMap 

func FuncMap() template.FuncMap

FuncMap returns the optional interaction template helpers: those that render an element of their own (async, reveal, poll, on, stream, prefetch and refresh) and those of AttrsFuncMap. The names of the first are generic, so an application that only writes attributes on elements of its own registers AttrsFuncMap instead, leaving names such as "poll" free for its own functions.

func LiveAttrs added in v0.15.0 

func LiveAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

LiveAttrs returns the attributes of an input that requests the endpoint as the user types, such as a search box: <input type="search" name="q" {{ liveAttrs runtime "/search" "target" "#results" "delay" "300ms" "pushURL" "true" }}>. htmx gets hx-get with an input trigger, Unpoly up-autosubmit with up-watch-delay; Turbo, which has none, data attributes for a script. "include" sends the values of other elements, such as "closest form".

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

func NoBoost added in v0.15.0 

func NoBoost(runtime *partial.Runtime) template.HTMLAttr

NoBoost returns the attribute that makes the browser load a link or submit a form itself, such as hx-boost="false" with htmx or data-turbo="false" with Turbo: <a href="/download" {{ noBoost runtime }}>.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime) html/template.HTMLAttr

func On 

func On(runtime *partial.Runtime, value any, args ...any) template.HTML

On renders an interaction that refreshes when a browser event is dispatched. Pass either an Interaction or an event name followed by an endpoint.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, event string, endpoint string, params ...any) html/template.HTML go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTML

func OnAttrs added in v0.15.0 

func OnAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

OnAttrs returns the attributes of an event-driven interaction for an element of the template's own; see AsyncAttrs and On.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, event string, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

func Poll 

func Poll(runtime *partial.Runtime, value any, args ...any) template.HTML

Poll renders an interaction that refreshes on an interval. When an endpoint string is used, a single extra argument is treated as the interval.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTML go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTML

func PollAttrs added in v0.15.0 

func PollAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

PollAttrs returns the attributes of a polling interaction for an element of the template's own; see AsyncAttrs. A single argument after an endpoint string is the interval, as with Poll.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

func Prefetch 

func Prefetch(runtime *partial.Runtime, value any, args ...any) template.HTML

Prefetch renders a non-visual prefetch hint.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTML go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTML

func Refresh 

func Refresh(runtime *partial.Runtime, value any, args ...any) template.HTML

Refresh renders a control that explicitly refreshes a target.

go-doc:include go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTML go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTML

func RefreshAttrs added in v0.15.0 

func RefreshAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

RefreshAttrs returns the attributes of a refresh control for an element of the template's own, such as a link; see AsyncAttrs.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

func Render 

func Render(kind connector.InteractionKind, value any, runtime *partial.Runtime, args ...any) template.HTML

func Reveal 

func Reveal(runtime *partial.Runtime, value any, args ...any) template.HTML

Reveal renders an interaction that loads when the element enters the viewport.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTML go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTML

func RevealAttrs added in v0.15.0 

func RevealAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

RevealAttrs returns the attributes of a reveal interaction for an element of the template's own; see AsyncAttrs.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

func Stage 

func Stage(markup ...MarkupRenderer) partial.RenderStage

Stage returns a partial render stage for interaction markup.

func Stream 

func Stream(runtime *partial.Runtime, value any, args ...any) template.HTML

Stream renders an SSE-backed interaction placeholder.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTML go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTML

func StreamAttrs added in v0.15.0 

func StreamAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

StreamAttrs returns the attributes of an SSE-backed interaction for an element of the template's own; see AsyncAttrs.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

func SubmitAttrs added in v0.15.0 

func SubmitAttrs(runtime *partial.Runtime, value any, args ...any) template.HTMLAttr

SubmitAttrs returns the attributes of a form that submits to the endpoint and swaps the response into its target, such as <form method="post" action="{{ .Action }}" {{ submitAttrs runtime .Action "target" "#comments" "swap" "outerHTML" }}>: hx-post for htmx, up-submit for Unpoly, and a data-turbo-frame for a target with Turbo. Without a target or id, the form itself is the target. "method" picks another method, such as "delete"; "include", "pushURL" and "replaceURL" are written in the connector's syntax.

go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, endpoint string, params ...any) html/template.HTMLAttr go-doc:sig func(runtime *github.com/donseba/go-partial.Runtime, interaction github.com/donseba/go-partial/exp/interactions.Interaction) html/template.HTMLAttr

Types

type Data 

type Data struct {
	Runtime     *partial.Runtime
	Interaction connector.Interaction
	Attrs       map[string]string
}

Data is the render payload for RenderKindInteraction.

type Interaction 

type Interaction struct {
	// contains filtered or unexported fields
}

Interaction is an optional builder for connector-aware client interactions. Register values with partial.SetContract("interaction", ...).

func NewAsync 

func NewAsync(endpoint string) Interaction

NewAsync creates an async interaction contract value.

func NewOn 

func NewOn(event string, endpoint string) Interaction

NewOn creates an event-driven interaction contract value.

func NewPoll 

func NewPoll(endpoint string) Interaction

NewPoll creates a polling interaction contract value.

func NewPrefetch 

func NewPrefetch(endpoint string) Interaction

NewPrefetch creates a prefetch interaction contract value.

func NewRefresh 

func NewRefresh(endpoint string) Interaction

NewRefresh creates a refresh-control interaction contract value.

func NewReveal 

func NewReveal(endpoint string) Interaction

NewReveal creates a reveal interaction contract value.

func NewStream 

func NewStream(endpoint string) Interaction

NewStream creates an SSE-backed interaction contract value.

func (Interaction) As 

func (i Interaction) As(name string) Interaction

As sets the contract name for this interaction.

func (Interaction) ContractName 

func (i Interaction) ContractName() string

ContractName returns the contract name used when registering the interaction.

func (Interaction) Every 

func (i Interaction) Every(interval time.Duration) Interaction

Every sets the polling interval.

func (Interaction) EveryString 

func (i Interaction) EveryString(interval string) Interaction

EveryString sets the polling interval from a raw connector interval string.

func (Interaction) From 

func (i Interaction) From(source string) Interaction

From sets the event source option for event-driven interactions.

func (Interaction) ID 

func (i Interaction) ID(id string) Interaction

ID sets the element ID used by the rendered interaction.

func (Interaction) Interaction 

func (i Interaction) Interaction() connector.Interaction

Interaction returns the connector interaction represented by the builder.

func (Interaction) Option 

func (i Interaction) Option(key string, value any) Interaction

Option sets a connector option.

func (Interaction) Param 

func (i Interaction) Param(key string, value any) Interaction

Param sets a URL/path parameter used when resolving the endpoint.

func (Interaction) Placeholder 

func (i Interaction) Placeholder(placeholder string) Interaction

Placeholder sets the placeholder markup text rendered before content loads.

func (Interaction) Swap 

func (i Interaction) Swap(swap string) Interaction

Swap sets the connector swap strategy.

func (Interaction) Target 

func (i Interaction) Target(target string) Interaction

Target sets the client-side target selector.

func (Interaction) Trigger 

func (i Interaction) Trigger(trigger string) Interaction

Trigger sets the browser event or connector trigger.

type MarkupRenderer 

type MarkupRenderer func(runtime *partial.Runtime, interaction connector.Interaction, attrs map[string]string) (template.HTML, error)

MarkupRenderer renders connector interaction attributes into final HTML.

func DefaultMarkupRenderer 

func DefaultMarkupRenderer() MarkupRenderer

DefaultMarkupRenderer renders small, unstyled wrappers around connector attributes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.