1.22.1 Procedures

Procedure: segmented-control KEY: #:label #:name #:id #:options #:selected #:required #:disabled #:help-text #:error #:valid #:full-width? #:classes #:label-css #:help-classes #:error-css #:valid-css ¶

Render a segmented control: a radio group drawn as one bar of choices.

The control is a ‘<fieldset>‘ named by its ‘<legend>‘, holding one radio per choice. It therefore behaves exactly like every other choice in a form – one tab stop, arrow keys to move, the chosen row announced as checked – and it submits its value with scripting off. Nothing about the bar is a script: the highlight follows the checked radio in the stylesheet.

Keep the set small. A segmented control says "one of these few, and you can see them all"; a list of more than about five choices reads better as a ‘select’ or as radios stacked down the page.

label

The name of the group, rendered as a ‘<legend>‘.

name

The form field name.

id

An explicit identifier for the group; defaults to name.

options

A list of strings or (value . label) pairs.

selected

The value that starts chosen; the first choice when nothing is given.

required

Whether a choice has to be made.

disabled

Whether the whole control is disabled.

help-text

Optional helper copy, linked with aria-describedby.

error

Optional validation message, announced with role="alert".

valid

#t to mark the control as answered, or a string to say so in words.

full-width?

Stretch the bar across its container and share the width between choices.

classes

Classes for the field wrapper.

label-css

Classes for the legend.

help-classes

Classes for the helper copy.

error-css

Classes for the error message.

valid-css

Classes for the success message.

(segmented-control #:label "Range"
                   #:name "range"
                   #:options '((day . "Day") (week . "Week") (month . "Month"))
                   #:selected "week")

Procedure: segmented-item KEY: #:value #:label #:name #:id #:checked #:disabled #:classes ¶

Render one choice of a segmented control.

A page normally asks for the whole control with segmented-control and never writes an item itself; this is exported for the case where a page has to lay the choices out around something else (a divider, a disabled group).

The item is a ‘<label>‘ holding its own radio, so the label and the control are one target, and the stylesheet can style the checked state with a sibling selector rather than a script.

value

The value submitted when this choice is chosen.

label

The text shown on the choice.

name

The shared form field name identifying the group.

id

An explicit identifier; defaults to one derived from value.

checked

Whether this choice starts chosen.

disabled

Whether this choice cannot be chosen.

classes

Classes for the label.

(segmented-item #:value "day" #:label "Day" #:name "range" #:checked #t)