ChoiceWidget

This class provides a base implementation for widgets that allow users to select from a predefined set of choices. It manages the generation of option groups and individual options, supporting both single and multiple selections through configurable attributes. The class also handles the normalization of choice data and the mapping of values to their corresponding HTML attributes.

Attributes

Attribute	Type	Description
allow_multiple_selected	boolean = false	Boolean flag indicating if the widget supports selecting more than one option simultaneously.
input_type	string = null	The HTML input type attribute used when rendering the widget's options.
template_name	string = null	The path to the template used to render the main widget structure.
option_template_name	string = null	The path to the template used to render individual choice options within the widget.
add_id_index	boolean = true	Determines whether an incrementing index should be appended to the HTML ID of each option.
checked_attribute	dict = {"checked": true}	A dictionary containing the HTML attribute name and value to apply when an option is selected.
option_inherits_attrs	boolean = true	Specifies if individual options should inherit the base attributes defined on the widget instance.

---

Constructor

Signature

def ChoiceWidget(
    attrs: dict = None,
    choices: iterable = ()
) - > null

Parameters

Name	Type	Description
attrs	dict = None	A dictionary of HTML attributes to be added to the rendered widget.
choices	iterable = ()	An iterable of choices to be used by the widget.

---

Methods

---

subwidgets()

@classmethod
def subwidgets(
    name: string,
    value: any,
    attrs: dict
) - > generator

Yield all "subwidgets" of this widget. Used to enable iterating options from a BoundField for choice widgets.

Parameters

Name	Type	Description
name	string	The name attribute of the HTML input element.
value	any	The current value(s) of the widget used to determine which options are selected.
attrs	dict	Additional HTML attributes to be applied to the subwidgets.

Returns

Type	Description
generator	A generator yielding individual option dictionaries for the widget.

---

options()

@classmethod
def options(
    name: string,
    value: any,
    attrs: dict
) - > generator

Yield a flat list of options for this widget.

Parameters

Name	Type	Description
name	string	The name attribute of the HTML input element.
value	any	The current value(s) of the widget.
attrs	dict	Additional HTML attributes for the options.

Returns

Type	Description
generator	A generator yielding flattened option dictionaries from all optgroups.

---

optgroups()

@classmethod
def optgroups(
    name: string,
    value: any,
    attrs: dict
) - > list

Return a list of optgroups for this widget.

Parameters

Name	Type	Description
name	string	The name attribute of the HTML input element.
value	any	The current value(s) of the widget used to mark options as selected.
attrs	dict	Additional HTML attributes for the optgroup elements.

Returns

Type	Description
list	A list of tuples containing group names, subgroups of options, and group indices.

---

create_option()

@classmethod
def create_option(
    name: string,
    value: any,
    label: string,
    selected: boolean,
    index: integer,
    subindex: integer,
    attrs: dict
) - > dict

Builds a dictionary representing a single choice option, including its attributes, label, and selection state.

Parameters

Name	Type	Description
name	string	The name attribute of the input.
value	any	The value of the specific option.
label	string	The human-readable text displayed for the option.
selected	boolean	Whether this option should be marked as selected or checked.
index	integer	The positional index of the option within the choice list.
subindex	integer	The index of the option within a nested group, if applicable.
attrs	dict	Base HTML attributes to merge with option-specific attributes.

Returns

Type	Description
dict	A dictionary containing the configuration and metadata for rendering a single option template.

---

get_context()

@classmethod
def get_context(
    name: string,
    value: any,
    attrs: dict
) - > dict

Constructs the template context for rendering the widget, including the calculated optgroups.

Parameters

Name	Type	Description
name	string	The name of the form field.
value	any	The current value of the field.
attrs	dict	HTML attributes to be included in the context.

Returns

Type	Description
dict	A dictionary containing the widget state and optgroups for template rendering.

---

id_for_label()

@classmethod
def id_for_label(
    id_: string,
    index: string
) - > string

Use an incremented id for each option where the main widget references the zero index.

Parameters

Name	Type	Description
id_	string	The base ID of the widget.
index	string	The index suffix to append to the base ID.

Returns

Type	Description
string	The generated HTML ID string for a specific option.

---

value_from_datadict()

@classmethod
def value_from_datadict(
    data: dict,
    files: dict,
    name: string
) - > any

Extracts the widget's value from a submission dictionary, handling both single and multiple selection logic.

Parameters

Name	Type	Description
data	dict	The dictionary of submitted form data (e.g., request.POST).
files	dict	The dictionary of submitted file data.
name	string	The name of the field to look up in the data.

Returns

Type	Description
any	The submitted value or list of values associated with the widget name.

---

format_value()

@classmethod
def format_value(
    value: any
) - > list

Return selected values as a list.

Parameters

Name	Type	Description
value	any	The raw value to be formatted for the widget.

Returns

Type	Description
list	A list of string-formatted values representing the current selection.

---

choices()

@classmethod
def choices() - > list

Gets or sets the choices for the widget, ensuring they are normalized into a standard format upon assignment.

Returns

Type	Description
list	The normalized list of choices available for the widget.

---