= S3GroupedOptionsWidget =
[[TOC]]

== Introduction ==

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

||'''!MultipleOptionsWidget'''||'''S3GroupedOptionsWidget'''||
||[[Image(groupedopts3.png)]]||[[Image(groupedopts1.png)]]||

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

||'''!MultipleOptionsWidget'''||'''S3GroupedOptionsWidget'''||
||[[Image(groupedopts4.png)]]||[[Image(groupedopts2.png)]]||

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

{{{#!python
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''':

{{{#!python
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''':

{{{#!js
$('#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||

----
- [wiki:S3 S3 API Guide]
- DeveloperGuidelines