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.

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>
  <optgroup label="L - M">
    <option value="Lautém">Lautém</option>
    <option value="Manatuto">Manatuto</option>
    <option value="Manufahi">Manufahi</option>
  </optgroup>
  <optgroup label="V - Z">
    <option value="Viqueque">Viqueque</option>
  </optgroup>
</select>

...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)

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 not group by first letter)	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

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)

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

CSS Classes

Example:

HTML:

<div class="s3-groupedopts-widget">
  <div class="s3-groupedopts-label expanded">A - K</div>
  <table class="s3-groupedopts-widget" style="">
    <tbody>
      <tr>
        <td>
          <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>
        </td>
        <td>
          <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>
        </td>
        <td>
          <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>
        </td>
      </tr>
    </tbody>
  </table>
  <div class="s3-groupedopts-label">L - M</div>
  <table class="s3-groupedopts-widget" style="display: none;">
    ...
  </table>
  <div class="s3-groupedopts-label">V - Z</div>
  <table class="s3-groupedopts-widget" style="display: none;">
    ...
  </table>
</div>

Explanations:

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.

---

• S3 API Guide
• DeveloperGuidelines