Documentation
¶
Overview ¶
Package urlparam provides enhanced URL parameter synchronization for Vango.
URLParam 2.0 supports:
- Push/Replace history modes
- Debouncing for search inputs
- Multiple encoding options (Flat, JSON, Comma)
- Complex type support (structs, arrays)
Example:
// Search input - replaces history, debounced
searchQuery := setup.URLParam(&s, "q", "", urlparam.Replace, urlparam.Debounce(300*time.Millisecond))
// Filter struct - flat encoding (empty key is valid for flat struct mode)
filters := setup.URLParam(&s, "", Filters{}, urlparam.WithEncoding(urlparam.EncodingFlat))
// Tag array - comma encoding (requires a non-empty key)
tags := setup.URLParam(&s, "tags", []string{}, urlparam.WithEncoding(urlparam.EncodingComma))
Index ¶
- Variables
- type Encoding
- type InitialURLState
- type Navigator
- type URLMode
- type URLParam
- func (u *URLParam[T]) Get() T
- func (u *URLParam[T]) Peek() T
- func (u *URLParam[T]) Reset()
- func (u *URLParam[T]) Set(value T)
- func (u *URLParam[T]) SetFromURL(params map[string]string) error
- func (u *URLParam[T]) SetNavigator(fn func(params map[string]string, mode URLMode))
- func (u *URLParam[T]) Update(fn func(T) T)
- type URLParamOption
Constants ¶
This section is empty.
Variables ¶
var InitialParamsKey = &struct{ name string }{"InitialURLParams"}
InitialParamsKey is the context key for initial URL params. The session sets this from the client handshake payload.
NavigatorKey is the context key for the URL navigator. The session sets this on the root owner so URLParam can queue patches.
Functions ¶
This section is empty.
Types ¶
type InitialURLState ¶
type InitialURLState struct {
// contains filtered or unexported fields
}
InitialURLState holds the current URL state for URLParam hydration. The session keeps this updated from handshake, route navigation, and URL delta patches so late-mounted URLParams hydrate from current state.
func NewInitialURLState ¶
func NewInitialURLState(path string, params map[string]string) *InitialURLState
NewInitialURLState creates a URL state snapshot.
func (*InitialURLState) ApplyDelta ¶
func (s *InitialURLState) ApplyDelta(delta map[string]string)
ApplyDelta applies URL delta semantics to the current params. Empty-string values delete keys; omitted keys remain unchanged.
type Navigator ¶
type Navigator struct {
// contains filtered or unexported fields
}
Navigator handles URL updates for URLParam. It queues URL patches that are sent to the client along with DOM patches.
func NewNavigator ¶
NewNavigator creates a navigator that queues patches via the provided function. The session passes in a closure that appends to its pending patch buffer.
func (*Navigator) Navigate ¶
Navigate queues a URL update patch. The patch will be sent to the client with other DOM patches in the same tick.
func (*Navigator) QueuePatch ¶
QueuePatch queues an arbitrary patch to be sent with the next render frame. This is intended for experimental features that need client-side integration without direct access to the session patch buffer.
type URLParam ¶
type URLParam[T any] struct { // contains filtered or unexported fields }
URLParam represents a reactive value synchronized with URL parameters.
func SetupParam ¶
func SetupParam[P any, T any](s *vango.SetupCtx[P], key string, defaultValue T, opts ...URLParamOption) *URLParam[T]
SetupParam creates a new URL parameter during Setup. It allocates state using setup helpers and does not rely on hook slots.
Key rules:
- key must be non-empty for scalar/default, JSON, comma, and flat non-struct values.
- key may be empty only for flat struct bindings (field tags/names become query keys).
func (*URLParam[T]) Get ¶
func (u *URLParam[T]) Get() T
Get returns the current value. In a tracking context, this will subscribe the listener to changes.
func (*URLParam[T]) Peek ¶
func (u *URLParam[T]) Peek() T
Peek returns the current value without subscribing.
func (*URLParam[T]) Set ¶
func (u *URLParam[T]) Set(value T)
Set updates the value and synchronizes with the URL.
func (*URLParam[T]) SetFromURL ¶
SetFromURL updates the value from URL parameters. This is called during initialization to sync with the current URL.
func (*URLParam[T]) SetNavigator ¶
SetNavigator sets the navigation function for URL updates. This is called during component initialization.
type URLParamOption ¶
type URLParamOption interface {
// contains filtered or unexported methods
}
URLParamOption is a functional option for configuring URL parameters.
var ( // Push creates a new history entry (default behavior). Push URLParamOption = modeOption{/* contains filtered or unexported fields */} // Replace updates URL without creating history entry (use for filters, search). Replace URLParamOption = modeOption{/* contains filtered or unexported fields */} )
Mode options as values (not functions) to avoid collision with navigation methods.
func Debounce ¶
func Debounce(d time.Duration) URLParamOption
Debounce delays URL updates by the specified duration. Use this for search inputs to avoid spamming the history.
Example:
searchQuery := setup.URLParam(&s, "q", "", urlparam.Replace, urlparam.Debounce(300*time.Millisecond))
func WithEncoding ¶
func WithEncoding(e Encoding) URLParamOption
WithEncoding sets the encoding for complex types. Spec shows: vango.Encoding(vango.URLEncodingFlat) Due to import cycles, the actual call is: urlparam.WithEncoding(urlparam.EncodingFlat)
Example:
filters := setup.URLParam(&s, "", Filters{}, urlparam.WithEncoding(urlparam.EncodingFlat))
Source Files