wiki:S3/S3GroupedOptionsWidget

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

--

S3GroupedOptionsWidget

Introduction

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

MultipleOptionsWidgetS3GroupedOptionsWidget

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

MultipleOptionsWidgetS3GroupedOptionsWidget

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:

ParameterTypeExplanationDefault
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 no group lexicographically)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

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

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

Parameters:

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

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

Options:

OptionTypeExplanationDefault
columnsintegernumber of columns1

Functions:

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


Attachments (4)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.