Documentation
¶
Overview ¶
Package named provides named boolean values and collections used by select, option and radio widgets.
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() (h 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() (s string)
- func (nb *Bool) Set(checked bool) (changed bool)
- func (nb *Bool) String() string
- type BoolArray
- func (nba *BoolArray) Add(name string, text 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
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 selected attribute 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.
Lock ordering invariant: when both locks are needed, the owning BoolArray's mutex is always acquired before the Bool's mutex (as done here and by the BoolArray methods, which lock nba.mu then call into Bool). Any new method must preserve this array-before-bool order to avoid deadlocks.
Note that the elem.Dirty calls below run while nba.mu is still held (via the deferred Unlock); Dirty takes the outermost jaws Jaws.mu. This is the deliberate value-tier reverse edge documented in the jaws package "Locking" section, and is safe only because no holder of Jaws.mu ever calls back into these methods.
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.
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 text 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.
func (*BoolArray) ReadLocked ¶
ReadLocked calls fn with the BoolArray locked for reading.
fn must not call other BoolArray methods, which would re-acquire the same non-reentrant lock and deadlock; operate only on the provided slice. Calling methods on the *Bool elements is safe because they use a separate mutex taken in array-before-bool order.
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.
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 (it would deadlock); operate only on the provided slice and its *Bool elements.
Source Files