= 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}}}. 

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

{{{#!text/html
<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''':

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

{{{#!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||

== CSS Classes ==

'''Example''':
  [[Image(groupedopts2.png)]]

'''HTML''':

{{{#!text/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.

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