swap

Documentation

Overview

package swap provides a builder for the hx-swap attribute value.

Index

• type Builder
  • func New() *Builder
  • func (s *Builder) Clear(modifier Modifier) *Builder
  • func (s *Builder) FocusScroll(value bool) *Builder
  • func (s *Builder) IgnoreTitle() *Builder
  • func (s *Builder) Scroll(scrollDirection ScrollDirection) *Builder
  • func (s *Builder) ScrollElement(selector string, scrollDirection ScrollDirection) *Builder
  • func (s *Builder) Settle(wait time.Duration) *Builder
  • func (s *Builder) Show(scrollDirection ScrollDirection) *Builder
  • func (s *Builder) ShowElement(extendedSelector ShowSelector, scrollDirection ScrollDirection) *Builder
  • func (s *Builder) ShowNone() *Builder
  • func (s *Builder) Strategy(strategy Strategy) *Builder
  • func (s *Builder) String() string
  • func (s *Builder) Swap(wait time.Duration) *Builder
  • func (s *Builder) Transition() *Builder
• type Modifier
• type ScrollDirection
• type ShowSelector
• type Strategy

Examples

• Builder.Clear
• Builder.FocusScroll
• Builder.FocusScroll (Disable)
• Builder.IgnoreTitle
• Builder.Scroll
• Builder.ScrollElement
• Builder.Settle (Timing)
• Builder.Show
• Builder.Show (Window)
• Builder.ShowElement
• Builder.ShowNone
• Builder.Strategy
• Builder.Swap (Timing)
• Builder.Transition
• New (Default)

Types

type Builder

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

Builder is a builder to create a new hx-swap attribute.

func New

func New() *Builder

New starts a builder chain for creating a new hx-swap attribute. It contains methods to add and remove modifiers from the swap. Subsequent calls can override previous modifiers of the same type - for instance, .Scroll(Top).Scroll(Bottom) will result in `hx-swap="scroll:bottom"`. Pass to [htmx.HX.SwapExtended] to set the swap attribute on an element.

Example (Default)

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New()),
	)
}

Output:

hx-swap='innerHTML'

func (*Builder) Clear

func (s *Builder) Clear(modifier Modifier) *Builder

Clear removes a modifier entirely from the builder. Used to undo an previously set modifier.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().Transition().Clear(swap.Transition)),
	)
}

Output:

hx-swap='innerHTML'

func (*Builder) FocusScroll

func (s *Builder) FocusScroll(value bool) *Builder

FocusScroll overrides the behavior of scrolling of a focused element after a swap.

htmx preserves focus between requests for inputs that have a defined id attribute. By default htmx prevents auto-scrolling to focused inputs between requests which can be unwanted behavior on longer requests when the user has already scrolled away. To enable focus scroll you can use focus-scroll:true.

Alternatively, if you want the page to automatically scroll to the focused element after each request you can change the htmx global configuration value htmx.config.defaultFocusScroll to true. Then disable it for specific requests using focus-scroll:false.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().FocusScroll(true)),
	)
}

Output:

hx-swap='innerHTML focus-scroll:true'

Example (Disable)

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().FocusScroll(false)),
	)
}

Output:

hx-swap='innerHTML focus-scroll:false'

func (*Builder) IgnoreTitle

func (s *Builder) IgnoreTitle() *Builder

IgnoreTitle turns off the default title behavior, where htmx will update the title of the page if it finds a <title> tag in the response content.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().IgnoreTitle()),
	)
}

Output:

hx-swap='innerHTML ignoreTitle:true'

func (*Builder) Scroll

func (s *Builder) Scroll(scrollDirection ScrollDirection) *Builder

Scroll will scroll the target element to the top/bottom after the swap.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().Scroll(swap.Top)),
	)
}

Output:

hx-swap='innerHTML scroll:top'

func (*Builder) ScrollElement

func (s *Builder) ScrollElement(selector string, scrollDirection ScrollDirection) *Builder

ScrollElement will scroll the selected element to the top/bottom after the swap. The selector is a CSS selector that identifies the element to scroll.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().ScrollElement("#example", swap.Top)),
	)
}

Output:

hx-swap='innerHTML scroll:#example:top'

func (*Builder) Settle

func (s *Builder) Settle(wait time.Duration) *Builder

Settle modifies the time between the swap and the settle logic. This attribute can be used to synchronize htmx with the timing of CSS transition effects.

Example (Timing)

package main

import (
	"fmt"
	"time"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().Settle(500 * time.Millisecond)),
	)
}

Output:

hx-swap='innerHTML settle:500ms'

func (*Builder) Show

func (s *Builder) Show(scrollDirection ScrollDirection) *Builder

Show will scroll the viewport to show the target element after the swap.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().Show(swap.Bottom)),
	)
}

Output:

hx-swap='innerHTML show:bottom'

Example (Window)

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().ShowElement(swap.ShowWindow, swap.Top)),
	)
}

Output:

hx-swap='innerHTML show:window:top'

func (*Builder) ShowElement

func (s *Builder) ShowElement(extendedSelector ShowSelector, scrollDirection ScrollDirection) *Builder

ShowElement will scroll the viewport to show the selected element after the swap. The selector is a CSS selector that identifies the element to show.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().ShowElement("#example", swap.Bottom)),
	)
}

Output:

hx-swap='innerHTML show:#example:bottom'

func (*Builder) ShowNone

func (s *Builder) ShowNone() *Builder

ShowNone will disable the default show:top behavior for boosted links and forms. You can disable it globally with htmx.config.scrollIntoViewOnBoost, or you can use hx-swap="show:none" on an element basis.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().ShowNone()),
	)
}

Output:

hx-swap='innerHTML show:none'

func (*Builder) Strategy

func (s *Builder) Strategy(strategy Strategy) *Builder

Strategy allows you to specify how the response will be swapped in relative to the target of an AJAX request. If you do not specify the option, the default is htmx.config.defaultSwapStyle (innerHTML).

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().Strategy(swap.OuterHTML)),
	)
}

Output:

hx-swap='outerHTML'

func (*Builder) String

func (s *Builder) String() string

String returns the final hx-swap string.

func (*Builder) Swap

func (s *Builder) Swap(wait time.Duration) *Builder

Swap modifies the amount of time that htmx will wait after receiving a response to swap the content. This attribute can be used to synchronize htmx with the timing of CSS transition effects.

Example (Timing)

package main

import (
	"fmt"
	"time"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().Swap(500 * time.Millisecond)),
	)
}

Output:

hx-swap='innerHTML swap:500ms'

func (*Builder) Transition

func (s *Builder) Transition() *Builder

Transition enables the new View Transitions API when a swap occurs. You can also enable this feature globally by setting the htmx.config.globalViewTransitions config setting to true.

Example

package main

import (
	"fmt"

	"github.com/will-wow/typed-htmx-go/htmx"
	"github.com/will-wow/typed-htmx-go/htmx/swap"
)

var hx = htmx.NewStringAttrs()

func main() {
	fmt.Println(
		hx.SwapExtended(swap.New().Transition()),
	)
}

Output:

hx-swap='innerHTML transition:true'

type Modifier

type Modifier string

Modifier is an enum of the possible hx-swap modifiers.

const (
	Transition  Modifier = "transition"
	Swap        Modifier = "swap"
	Settle      Modifier = "settle"
	IgnoreTitle Modifier = "ignoreTitle"
	Scroll      Modifier = "scroll"
	Show        Modifier = "show"
	FocusScroll Modifier = "focus-scroll"
)

type ScrollDirection

type ScrollDirection string

ScrollDirection specifies the direction to scroll/show an element after a swap.

const (
	Top    ScrollDirection = "top"
	Bottom ScrollDirection = "bottom"
)

type ShowSelector

type ShowSelector string

A ShowSelector is a CSS selector that identifies the element to show. Includes the non-standard "window" value to scroll the viewport to the top/bottom after a swap.

const (
	ShowWindow ShowSelector = "window"
)

type Strategy

type Strategy string

Strategy specifies how the response will be swapped in relative to the target of an AJAX request.

const (
	InnerHTML   Strategy = "innerHTML"   // Replace the inner html of the target element
	OuterHTML   Strategy = "outerHTML"   // Replace the entire target element with the response
	BeforeBegin Strategy = "beforebegin" // Insert the response before the target element
	AfterBegin  Strategy = "afterbegin"  // Insert the response before the first child of the target element
	BeforeEnd   Strategy = "beforeend"   // Insert the response after the last child of the target element
	AfterEnd    Strategy = "afterend"    // Insert the response after the target element
	Delete      Strategy = "delete"      // Deletes the target element regardless of the response
	None        Strategy = "none"        // Does not append content from response (out of band items will still be processed).
)