Documentation
¶
Overview ¶
Package named provides named boolean values and collections used by select, option and radio widgets.
Labels are represented as template.HTML and are rendered as trusted HTML. When labels come from user-controlled text, escape them before constructing the Bool or BoolArray entry.
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. It is the single source of <option> markup shared by BoolArray's options and by ui.Option, so attribute/escaping behavior cannot drift between them.
func UpdateBoolOption ¶ added in v0.500.0
UpdateBoolOption updates a rendered <option>'s live selected state to match nb. It is the single source of the option's update behavior.
Types ¶
type Bool ¶
type Bool struct {
// contains filtered or unexported fields
}
Bool stores a named boolean value with an HTML representation.
Bool values are safe for concurrent use.
func NewBool ¶
NewBool returns a Bool with the given name, HTML and checked state.
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 containing BoolArray and deselect sibling values in single-select mode.
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.
It returns jaws.ErrValueUnchanged if checked already matched the current state. Affected tags are dirtied after the value locks have been released, matching BoolArray.JawsSet.
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. Returns itself.
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 Bool in the group that has its checked value set to true. Returns an empty string if none are true.
In case you can have more than one selected or you need to distinguish between a blank name and the fact that none are set to true, use BoolArray.ReadLocked to inspect the data directly.
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.
fn must not call other BoolArray methods or Bool.JawsSet: those re-acquire the same non-reentrant nba mutex and deadlock. It may operate on 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 the internal []*Bool slice with the return value.
As with BoolArray.ReadLocked, fn must not call other BoolArray methods or Bool.JawsSet (they re-acquire the same non-reentrant nba mutex and deadlock); operate only on the provided slice and the *Bool methods that take just the Bool's own mutex (see BoolArray.ReadLocked). The exclusive lock held here serializes Bool.Set across concurrent WriteLocked calls.
Source Files