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.
BoolArray is the standard shared selection model for github.com/linkdata/jaws/lib/ui.Select and github.com/linkdata/jaws/lib/ui.RequestWriter.RadioGroup.
Index ¶
- func RenderBoolOption(elem *jaws.Element, w io.Writer, nb *Bool, params []any) error
- func UpdateBoolOption(elem *jaws.Element, nb *Bool)
- type Bool
- func (nb *Bool) Array() *BoolArray
- func (nb *Bool) Checked() (checked bool)
- func (nb *Bool) HTML() template.HTML
- func (nb *Bool) JawsGet(elem *jaws.Element) (yes bool)
- func (nb *Bool) JawsGetHTML(elem *jaws.Element) (h template.HTML)
- func (nb *Bool) JawsSet(elem *jaws.Element, checked bool) (err error)
- func (nb *Bool) Name() string
- func (nb *Bool) Set(checked bool) (changed bool)
- func (nb *Bool) String() string
- type BoolArray
- func (nba *BoolArray) Add(name string, html template.HTML) *BoolArray
- func (nba *BoolArray) Count(name string) (n int)
- func (nba *BoolArray) Get() (name string)
- func (nba *BoolArray) IsChecked(name string) (state bool)
- func (nba *BoolArray) JawsContains(elem *jaws.Element) (contents []jaws.UI)
- func (nba *BoolArray) JawsGet(elem *jaws.Element) string
- func (nba *BoolArray) JawsSet(elem *jaws.Element, name string) (err error)
- func (nba *BoolArray) ReadLocked(fn func(nbl []*Bool))
- func (nba *BoolArray) Set(name string, state bool) (changed bool)
- func (nba *BoolArray) String() string
- func (nba *BoolArray) WriteLocked(fn func(nbl []*Bool) []*Bool)
- type SelectHandler
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RenderBoolOption ¶ added in v0.500.0
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
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 ¶
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)).
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 ¶
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) JawsGetHTML ¶
JawsGetHTML returns the trusted HTML label for nb.
func (*Bool) JawsSet ¶
JawsSet sets the checked state and dirties the affected element tags.
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) Set ¶
Set changes the checked state and reports whether it changed.
Unlike Bool.JawsSet, Set does not dirty any elements and does not deselect siblings in single-select mode; it only changes this value. Single-select consistency (at most one checked value) is an invariant maintained by going through JawsSet, so prefer JawsSet for widget-driven updates.
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 choose multi-select.
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.IsChecked("red"), choices.IsChecked("green"))
}
Output: true true
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")).
Add("green", template.HTML("Green duplicate"))
fmt.Println(choices.Set("green", true))
fmt.Println(choices.Get(), choices.Count("green"), choices.IsChecked("red"), choices.IsChecked("green"))
choices.Set("missing", true)
fmt.Println(choices.Get())
}
Output: true green 2 false true
func NewBoolArray ¶
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.
func (*BoolArray) Add ¶
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.
Note that while it is legal to have multiple Bool values with the same name because HTML allows it, it is usually not a good idea.
func (*BoolArray) Count ¶
Count returns the number of Bool values in the set that have the given name.
func (*BoolArray) Get ¶
Get returns the name of the first checked Bool.
It returns an empty string if none are checked. Use BoolArray.ReadLocked to inspect all checked values when multiple values may be checked.
func (*BoolArray) IsChecked ¶
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 ¶
JawsContains returns the option widgets for a select backed by nba.
func (*BoolArray) JawsSet ¶
JawsSet selects name and dirties the changed Bool values and nba itself.
This mirrors Bool.JawsSet: every Bool whose checked state changes is dirtied in addition to the array tag, so consumers that bind individual Bools (such as radio buttons) update, not only the cascading github.com/linkdata/jaws/lib/ui.Select widget that re-renders from the array tag.
In single-select mode a name matching no Bool still succeeds (returns nil) by deselecting the current selection, as documented for BoolArray.Set, leaving the selected name empty. A nil return therefore means "the selection changed", not "name is now selected".
func (*BoolArray) ReadLocked ¶
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 ¶
Set sets the checked state for Bool values with the given name.
Matching is by name, so values are addressed as logical options rather than individually: every Bool sharing the name is set together, and in single-select mode the at-most-one-checked invariant holds per distinct name (selecting a name deselects all values with a different name, but leaves same-named siblings checked). If the given name matches no values in single-select mode, everything will be deselected.
The result reports whether the selection changed, not that name became checked: a non-matching name in single-select mode deselects all and returns true. Use BoolArray.IsChecked or BoolArray.Get to read the resulting state.
func (*BoolArray) String ¶
String returns a string representation of the BoolArray suitable for debugging.
func (*BoolArray) WriteLocked ¶
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.
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 call other Bool methods, including Bool.Set.
type SelectHandler ¶
SelectHandler renders select options and stores the selection as a string.
Rendered option values must be non-empty. A string that matches no rendered option value represents no selection. BoolArray is the standard implementation and returns an empty string when no Bool is checked.
Source Files