S3GroupedOptionsWidget

Introduction

The S3GroupedOptionsWidget renders a SELECT element as table of radiobuttons/checkboxes:

MultipleOptionsWidget	S3GroupedOptionsWidget

The widget can also automatically group options lexicographically (by first letter):

MultipleOptionsWidget	S3GroupedOptionsWidget

The main use-case for S3GroupedOptionsWidget is filter forms where the user typically selects multiple options. However, the widget can also be used for single-option SELECTs - in this case the options would be rendered as radio buttons instead of checkboxes so the user can only select one option.

Python Widget Class

The S3GroupedOptionsWidget is implemented in /modules/s3/s3widgets.py.

The instance of this class receives the widget options:

from s3.s3widgets import S3GroupedOptionsWidget

instance = S3GroupedOptionsWidget(options=None, multiple=True, size=None, cols=None, help_field=None, none=None)

Parameters:

Parameter	Type	Explanation	Default
options	list of tuples [(value, label)], or as dict {value: label}	the options, None to auto-detect the options from the Field during rendering	None
multiple	boolean	multiple options can be selected (False will render radio-buttons instead of checkboxes)	True
size	integer	the maximum number of option in merged letter-groups (None to no group lexicographically)	12
cols	integer	the number of options per row	3
help_field	string or dict {value: tooltip-string}	field in the referenced table (if field is a foreign key) to retrieve a tooltip text for each option (to be shown when hovering over the option label), or a dict of tooltips, or a callable returning such a dict	None
none	boolean	Render "None" as regular option	False

To render the HTML for the widget and inject the necessary JavaScript, call the widget like:

widget = instance(field, value, **attributes)

Parameters:

Parameter	Type	Explanation	Default
field	Field	the field to select options for (required)	-
value		the current value(s) selected (required)	-
attributes		HTML-attributes for the widget, e.g. "_class" or "_id"	-

JQuery UI Widget

The S3GroupedOptionsWidget uses the groupedopts() widget in jquery.ui.groupedopts.js. This jQueryUI-widget-factory based widget renders a normal SELECT element as one or multiple groups of checkboxes.

The widget is instantiated for an element like:

$('#example').groupedopts({columns=3})

Options:

Option	Type	Explanation	Default
columns	integer	number of columns	1

Functions:

Function	Example	Explanation
refresh	$('example').groupedopts('refresh')	Re-draw the widget from the current options/status of the underlying SELECT, e.g. to refresh the widget after Ajax-update of the SELECT
destroy	$('example').groupedopts('destroy')	Removes the widget and shows the underlying SELECT

---

• S3 API Guide
• DeveloperGuidelines