named

package
v0.901.1 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 10 Imported by: 1

Documentation

Overview

Package named provides named boolean values and collections used by select, option, and radio widgets.

Names are browser form values and must be non-empty valid UTF-8 strings without U+0000 (NUL). Labels are html/template.HTML and are rendered as trusted HTML; escape user-controlled text before passing it to NewBool or BoolArray.Add.

A single-select BoolArray is the standard shared selection model for github.com/linkdata/jaws/lib/ui.Select and github.com/linkdata/jaws/lib/ui.RequestWriter.RadioGroup. A BoolArray created with NewBoolArray(true) implements MultiSelectHandler for github.com/linkdata/jaws/lib/ui.MultiSelect. Use distinct option names.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func RenderBoolOption added in v0.500.0

func RenderBoolOption(elem *jaws.Element, w io.Writer, nb *Bool, params []any) error

RenderBoolOption renders nb as an HTML <option> element into w.

The option value is always Bool.Name and takes precedence over any value attribute in params.

func UpdateBoolOption added in v0.500.0

func UpdateBoolOption(elem *jaws.Element, nb *Bool)

UpdateBoolOption updates a rendered <option>'s live selected state to match nb.

Types

type Bool

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

Bool stores a named boolean value with an HTML representation.

A Bool must have a non-empty, valid UTF-8 name without U+0000 (NUL). Its zero value is therefore not ready for use; construct values with NewBool or BoolArray.Add.

Bool values are safe for concurrent use.

func NewBool

func NewBool(nba *BoolArray, name string, html template.HTML, checked bool) *Bool

NewBool returns a Bool with the given name, HTML and checked state.

name must be a non-empty, valid UTF-8 string without U+0000 (NUL).

The html argument is rendered as trusted HTML (it is the label shown in select lists and checkboxes) and is not escaped. When it is derived from untrusted user input it must be pre-escaped, e.g. template.HTML(template.HTMLEscapeString(s)).

nba is the Bool's sole array association. Pass nil for a standalone Bool. To insert it with BoolArray.WriteLocked, pass that array as nba.

If nba is non-nil, changing the value through Bool.JawsSet may dirty the associated BoolArray and deselect sibling values in single-select mode.

func (*Bool) Array

func (nb *Bool) Array() *BoolArray

Array returns the BoolArray associated with nb, or nil.

The association is fixed when nb is created and does not report current membership. In particular, removing nb through BoolArray.WriteLocked does not change this result. See BoolArray.WriteLocked for the restrictions on using a removed Bool.

func (*Bool) Checked

func (nb *Bool) Checked() (checked bool)

Checked reports whether nb is checked.

func (*Bool) HTML

func (nb *Bool) HTML() template.HTML

HTML returns the trusted HTML label for nb.

func (*Bool) JawsGet

func (nb *Bool) JawsGet(elem *jaws.Element) bool

JawsGet returns whether nb is checked.

func (*Bool) JawsGetHTML

func (nb *Bool) JawsGetHTML(elem *jaws.Element) (h template.HTML)

JawsGetHTML returns the trusted HTML label for nb.

func (*Bool) JawsSet

func (nb *Bool) JawsSet(elem *jaws.Element, checked bool) error

JawsSet sets this Bool's checked state and updates affected UI. Other Bools with the same name are unchanged. In a single-select array, checking this Bool clears Bools with different names.

If Bool.Array is non-nil, the associated array is used without checking whether nb is currently one of its members. See BoolArray.WriteLocked for the restrictions on using a removed Bool.

It returns jaws.ErrValueUnchanged if no checked state changes.

func (*Bool) Name

func (nb *Bool) Name() string

Name returns nb's selection key, used as an HTML option value.

func (*Bool) Set

func (nb *Bool) Set(checked bool) (changed bool)

Set changes the checked state and reports whether it changed.

Unlike Bool.JawsSet, Set does not dirty elements or clear other names. Use JawsSet for widget-driven updates.

func (*Bool) String

func (nb *Bool) String() string

String returns a string representation of the Bool suitable for debugging.

type BoolArray

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

BoolArray stores the data required to support HTML select elements and sets of HTML radio buttons. It is safe to use from multiple goroutines concurrently.

The zero value is a ready-to-use empty single-select array. Use NewBoolArray to allow multiple checked values.

Example (MultiSelect)
package main

import (
	"fmt"
	"html/template"

	"github.com/linkdata/jaws/lib/named"
)

func main() {
	choices := named.NewBoolArray(true).
		Add("red", template.HTML("Red")).
		Add("green", template.HTML("Green"))

	choices.Set("red", true)
	choices.Set("green", true)
	fmt.Println(choices.JawsGetValues(nil))

}
Output:
[red green]
Example (SingleSelect)
package main

import (
	"fmt"
	"html/template"

	"github.com/linkdata/jaws/lib/named"
)

func main() {
	choices := named.NewBoolArray(false).
		Add("red", template.HTML("Red")).
		Add("green", template.HTML("Green"))

	fmt.Println(choices.Set("green", true))
	fmt.Println(choices.Get(), choices.IsChecked("red"), choices.IsChecked("green"))

	choices.Set("missing", true)
	fmt.Println(choices.Get())

}
Output:
true
green false true

func NewBoolArray

func NewBoolArray(multi bool) *BoolArray

NewBoolArray returns an empty BoolArray.

If multi is false, setting one value clears other names in the array. If multi is true, multiple values may be checked at the same time. Pass a single-select array to github.com/linkdata/jaws/lib/ui.NewSelect and github.com/linkdata/jaws/lib/ui.RequestWriter.RadioGroup; neither supports multi-select arrays. Pass a multi-select array to github.com/linkdata/jaws/lib/ui.NewMultiSelect.

func (*BoolArray) Add

func (nba *BoolArray) Add(name string, html template.HTML) *BoolArray

Add adds a Bool with the given name and trusted HTML text and returns nba.

name must be a non-empty, valid UTF-8 string without U+0000 (NUL).

The html argument is rendered as trusted HTML and is not escaped; pre-escape it (e.g. template.HTML(template.HTMLEscapeString(s))) when it is derived from untrusted user input. See NewBool.

Use distinct names for options rendered in a select or radio group.

func (*BoolArray) Count

func (nba *BoolArray) Count(name string) (n int)

Count returns the number of Bool values in the set that have the given name.

func (*BoolArray) Get

func (nba *BoolArray) Get() (name string)

Get returns the name of the first checked Bool.

It returns an empty string if none are checked. Use BoolArray.JawsGetValues to read all checked values when multiple values may be checked.

func (*BoolArray) IsChecked

func (nba *BoolArray) IsChecked(name string) (state bool)

IsChecked returns true if any Bool in the set with the given name is checked. Returns false if the name is not found.

func (*BoolArray) JawsContains

func (nba *BoolArray) JawsContains(elem *jaws.Element) (contents []jaws.UI)

JawsContains returns the option widgets for a select backed by nba.

func (*BoolArray) JawsGet

func (nba *BoolArray) JawsGet(elem *jaws.Element) string

JawsGet returns the currently selected name.

func (*BoolArray) JawsGetValues added in v0.807.0

func (nba *BoolArray) JawsGetValues(elem *jaws.Element) (names []string)

JawsGetValues returns the names of all checked Bools in array order. The returned slice is independent of nba and is nil when nothing is checked.

func (*BoolArray) JawsSet

func (nba *BoolArray) JawsSet(elem *jaws.Element, name string) error

JawsSet selects every Bool named name and updates affected UI. In single-select mode, it clears Bools with other names, or clears all Bools if name is absent. It returns jaws.ErrValueUnchanged if no state changed.

func (*BoolArray) JawsSetValues added in v0.807.0

func (nba *BoolArray) JawsSetValues(elem *jaws.Element, names []string) error

JawsSetValues replaces the selected names and updates affected UI. Unknown names are ignored; nil or empty names clear the selection. It returns jaws.ErrValueUnchanged if no checked state changed.

Use NewBoolArray(true) for multiple selections. In single-select mode, only the first matching name in array order is selected, including all its Bools.

func (*BoolArray) ReadLocked

func (nba *BoolArray) ReadLocked(fn func(nbl []*Bool))

ReadLocked calls fn with the BoolArray locked for reading.

The provided slice is read-only, valid only for the duration of fn, and must not be retained. The *Bool values remain usable as described below.

fn must not call other BoolArray methods or Bool.JawsSet: those re-acquire the same non-reentrant nba mutex and deadlock. It may inspect the provided slice and call the *Bool methods that take only the Bool's own mutex — the reads Bool.Name, Bool.HTML, Bool.JawsGet, Bool.Checked, Bool.String (and similar) and the write Bool.Set. Bool.Set mutates the Bool under the Bool's own mutex, which the nba read lock held here does not serialize, so concurrent callers must coordinate any such writes themselves.

func (*BoolArray) Set

func (nba *BoolArray) Set(name string, state bool) (changed bool)

Set updates every Bool named name and reports whether any state changed. In single-select mode, setting state to true clears Bools with other names; an absent name clears all Bools regardless of state.

func (*BoolArray) String

func (nba *BoolArray) String() string

String returns a string representation of the BoolArray suitable for debugging.

func (*BoolArray) WriteLocked

func (nba *BoolArray) WriteLocked(fn func(nbl []*Bool) []*Bool)

WriteLocked calls fn with the BoolArray locked for writing and replaces its contents with the values fn returns.

Nil entries are removed from fn's result in place, preserving order, before it is copied. The backing array passed to fn is cleared before return, so retained aliases contain nil values.

Every non-nil Bool returned by fn must have nba as its Bool.Array. WriteLocked does not change that association.

Omitting a Bool does not change Bool.Array. Removal is supported only after its live UI elements are removed and no event can remain in flight. Reinsert it before calling Bool.JawsSet.

fn must not call methods on nba or Bool.JawsSet on an associated Bool; doing so deadlocks. It may return pre-checked Bools or call other Bool methods, including Bool.Set; WriteLocked does not change checked states after fn returns.

type MultiSelectHandler added in v0.807.0

type MultiSelectHandler interface {
	jaws.Container
	JawsGetValues(*jaws.Element) []string
	JawsSetValues(*jaws.Element, []string) error
}

MultiSelectHandler renders multi-select options and stores selected values.

Rendered option values must be distinct and non-empty. JawsGetValues returns the selected values; JawsSetValues replaces the entire selection, with nil or an empty slice clearing it. BoolArray created with NewBoolArray(true) is the standard implementation.

type SelectHandler

type SelectHandler interface {
	jaws.Container
	bind.Setter[string]
}

SelectHandler renders single-select options and stores one selected value.

Rendered option values must be non-empty. A string that matches no rendered option value represents no selection. BoolArray is the standard implementation when created with NewBoolArray(false) or its zero value. It returns an empty string when no Bool is checked.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL