Version 14 (modified by Dominic König, 11 years ago) ( diff )




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


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


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/

It renders a normal SELECT element (with or without optgroups, depending on the size-parameter):

<select multiple="multiple">
  <optgroup label="A - K">
    <option value="Ainaro">Ainaro</option>
    <option value="Dili">Dili</option>
    <option value="Kuala Lumpur">Kuala Lumpur</option>
  <optgroup label="L - M">
    <option value="Lautém">Lautém</option>
    <option value="Manatuto">Manatuto</option>
    <option value="Manufahi">Manufahi</option>
  <optgroup label="V - Z">
    <option value="Viqueque">Viqueque</option>

...and then injects a JavaScript to apply the jQueryUI groupedopts() widget.

Options can also receive a "title" attribute which is used by groupedopts() to render a hover-tooltip for these options.

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)


optionslist of tuples [(value, label)], or as dict {value: label}the options, None to auto-detect the options from the Field during renderingNone
multiplebooleanmultiple options can be selected (False will render radio-buttons instead of checkboxes)True
sizeintegerthe maximum number of option in merged letter-groups (None to not group by first letter)12
colsintegerthe number of options per row3
help_fieldstring 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 dictNone
nonebooleanRender "None" as regular optionFalse

Note: if there are fewer total options than size, options will not be grouped by first letter at all.

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

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


fieldFieldthe 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:



columnsintegernumber of columns1


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

CSS Classes



<div class="s3-groupedopts-widget">
  <div class="s3-groupedopts-label expanded">A - K</div>
  <table class="s3-groupedopts-widget" style="">
          <input id="s3-groupedopts-option-1-0" class="s3-groupedopts-option" type="checkbox" value="Ainaro" name="s3-groupedopts-2">
          <label for="s3-groupedopts-option-1-0">Ainaro</label>
          <input id="s3-groupedopts-option-1-1" class="s3-groupedopts-option" type="checkbox" value="Dili" name="s3-groupedopts-2">
          <label for="s3-groupedopts-option-1-1">Dili</label>
          <input id="s3-groupedopts-option-1-2" class="s3-groupedopts-option" type="checkbox" value="Kuala Lumpur" name="s3-groupedopts-2">
          <label for="s3-groupedopts-option-1-2">Kuala Lumpur</label>
  <div class="s3-groupedopts-label">L - M</div>
  <table class="s3-groupedopts-widget" style="display: none;">
  <div class="s3-groupedopts-label">V - Z</div>
  <table class="s3-groupedopts-widget" style="display: none;">


The whole widget is either a DIV.s3-groupedopts-widget with embedded TABLE.s3-groupedopts-widget elements (one table for each letter-group), or just a TABLE.s3-groupedopts-widget (if there are no letter groups).

Every letter group is a DIV.s3-groupedopts-label containing the group label, followed by the respective TABLE.s3-groupedopts-widget with the options. An expanded group label has an additional expanded-class.

Every option is a INPUT.s3-groupedopts-option followed by a LABEL element that refers to it.

Every option has a unique ID generated by the jQueryUI widget.

Attachments (4)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.