djblets.forms.widgets¶

Custom widgets for Django form fields.

This module contains widgets that correspond to fields provided in djblets.forms.fields.

class AmountSelectorWidget(unit_choices: List[Tuple[Optional[int], str]], number_attrs: Optional[Dict[str, Any]] = None, select_attrs: Optional[Dict[str, Any]] = None, attrs: Optional[Dict[str, Any]] = None)¶

Bases: MultiWidget

A widget for editing an amount and its unit of measurement.

New in version 3.3.

template_name = 'djblets_forms/amount_selector_widget.html'¶

The name of the template used to render the widget.

__init__(unit_choices: List[Tuple[Optional[int], str]], number_attrs: Optional[Dict[str, Any]] = None, select_attrs: Optional[Dict[str, Any]] = None, attrs: Optional[Dict[str, Any]] = None) → None¶

Initialize the widget.

Parameters:

• unit_choices (list of tuple) –

  The unit choices for the field. This should be a list of tuples with the following entries:

  Tuple:

  0 (int or None):

  The conversion factor of the unit to the base unit. The base unit must always have this value set to 1. For the rest of the units, this will be the number that you need to multiply a value in the base unit by in order to convert it to the given unit.

  1 (str):

  The name for the unit.

  The list of unit choices should start with the base unit and have the rest of the units follow in increasing order of magnitude. You may set a conversion factor of None for a unit choice, which will allow you to save the value for this widget as None instead of as an integer amount. The None unit choice should be placed at the end of the list.

• number_attrs (dict, optional) – Additional HTML element attributes for the NumberInput widget.

• select_attrs (dict, optional) – Additional HTML element attributes for the Select widget.

• attrs (dict, optional) – Additional HTML element attributes for the MultiWidget parent.

decompress(value: Optional[int]) → Tuple[Optional[int], Optional[int]]¶

Break up the value into an amount and unit tuple.

This assumes that the value is stored in the base unit, and will find the most appropriate unit to display and convert the amount to that unit. The most appropriate unit is the largest unit where the amount can be converted to a whole number.

Parameters:

value (int or None) – The stored value.

Returns:

A tuple of:

0 (int or None):

The amount in the unit.

1 (int or None):

The integer representation of the unit.

Return type:

Tuple

value_from_datadict(data: Dict[str, Any], files: Dict[str, Any], name: str) → Optional[int]¶

Return a value for the field from a submitted form.

This serializes the data POSTed for the form into an integer that the field can use and validate. This will convert the integer value to the base unit.

Args:

data (dict):

The dictionary containing form data.

files (dict):

The dictionary containing uploaded files.

name (str):

The field name for the value to load.

Returns:

The value to save in the field.

Return type:

int or None

class ConditionsWidget(choices, mode_widget, choice_widget, operator_widget, choice_kwargs=None, attrs=None)¶

Bases: Widget

A widget used to request a list of conditions from the user.

This is used by ConditionsField() to allow the user to specify a list of possible conditions, composed of choices, operators, and values.

The conditions are displayed as rows of fields. Each row contains a <select> for the condition choice, operator choice, and a choice-provided field for a value.

Additional conditions can be added by the user dynamically.

choices¶

The condition choices for the field.

Type:

djblets.conditions.choices.ConditionChoices

mode_widget¶

The widget for selecting the mode.

Type:

django.forms.widgets.RadioSelect

choice_widget¶

The widget for selecting choices. One of these will be rendered for every row.

Type:

django.forms.widgets.Select

operator_widget¶

The widget for selecting operators. One of these will be rendered for every row.

Type:

django.forms.widgets.Select

choice_kwargs¶

Optional keyword arguments to pass to each BaseConditionChoice constructor. This is useful for more advanced conditions that need additional data from the form.

This can be updated dynamically by the form during initialization.

Type:

dict

template_name = 'djblets_forms/conditions_widget.html'¶

The name of the template used to render the widget.

__init__(choices, mode_widget, choice_widget, operator_widget, choice_kwargs=None, attrs=None)¶

Initialize the widget.

Parameters:

• choices (djblets.conditions.choices.ConditionChoices) – The condition choices for the field.

• mode_widget (django.forms.widgets.RadioSelect) – The widget for selecting the mode.

• choice_widget (django.forms.widgets.Select) – The widget for selecting choices. One of these will be rendered for every row.

• operator_widget (django.forms.widgets.Select) – The widget for selecting operators. One of these will be rendered for every row.

• choice_kwargs (dict) – Optional keyword arguments to pass to each BaseConditionChoice constructor. This is useful for more advanced conditions that need additional data from the form.

• attrs (dict, optional) – Additional HTML element attributes for the widget.

value_from_datadict(data, files, name)¶

Return a value for the field from a submitted form.

This serializes the data POSTed for the form into a format that the field can use and validate.

Parameters:

• data (django.http.request.QueryDict) – The dictionary containing form data.

• files (django.http.request.QueryDict) – The dictionary containing uploaded files.

• name (unicode) – The field name for the value to load.

Returns:

The value from the form data.

Return type:

object

render(name, value, attrs=None, renderer=None)¶

Render the widget to HTML.

This will serialize all the choices, operators, and existing conditions and render an HTML representation, along with setting up JavaScript support for configuring the conditions.

Parameters:

• name (unicode) – The base form field name of the widget.

• value (dict) – The serialized condition set for the field.

• attrs (dict, optional) – Additional HTML element attributes for the fields.

• renderer (django.forms.renderers.BaseRenderer, optional) – The form renderer.

Returns:

The rendered HTML for the widget.

Return type:

django.utils.safestring.SafeText

get_context(name, value, attrs)¶

Return context for the widget.

This will serialize all the choices, operators, and existing conditions needed to render the widget.

Parameters:

• name (unicode) – The base form field name of the widget.

• value (dict) – The serialized condition set for the field.

• attrs (dict) – Additional HTML element attributes for the fields.

Returns:

The context data for the widget.

Return type:

dict

__deepcopy__(memo)¶

Return a deep copy of the widget.

This will return a deep copy of this widget and all subwidgets, so that a particular form instance can easily manipulate state without affecting other instances.

Only the state that may be manipulated by an instance will be deep copied.

Parameters:

memo (dict) – The memo dictionary used to track IDs to objects.

Returns:

A deep copy of this widget’s instance.

Return type:

ConditionsWidget

class CopyableTextInput(attrs=None)¶

Bases: TextInput

A TextInput widget that renders a link to copy its contents.

template_name = 'djblets_forms/copyable_text_input.html'¶

render(name, value, attrs=None, renderer=None)¶

Render the widget.

Parameters:

• name (unicode) – The name of the widget.

• value (unicode) – The value of the widget.

• attrs (dict) – The attributes of the widget.

• renderer (django.forms.renderers.BaseRenderer, optional) – The form renderer.

Returns:

The rendered widget.

Return type:

django.utils.safestring.SafeText

class ListEditWidget(attrs=None, sep=', ', value_widget=<class 'django.forms.widgets.TextInput'>)¶

Bases: Widget

A widget for editing a list of values.

template_name = 'djblets_forms/list_edit_widget.html'¶

__init__(attrs=None, sep=', ', value_widget=<class 'django.forms.widgets.TextInput'>)¶

Initialize the widget.

Changed in version 3.0: Added the value_widget parameter and the ability for this widget to handle any list of values instead of only strings.

Parameters:

• attrs (dict, optional) – A dictionary containing HTML attributes to be set on the rendered widget.

• sep (str, optional) – The item separator.

• value_widget (django.forms.widgets.Widget, optional) – The widget for the values in the list.

render(name, value, attrs=None, renderer=None)¶

Render the widget.

Changed in version 3.0: The value parameter can be a string or a list of any type of values.

Parameters:

• name (str) – The field name.

• value (list or str) – The field value.

• attrs (dict, optional) – Additional attributes.

• renderer (django.forms.renderers.BaseRenderer, optional) – The form renderer.

Returns:

The rendered widget.

Return type:

django.utils.safestring.SafeText

get_context(name, value, attrs)¶

Return context for the widget.

This will serialize all the values in the list of values using the value_widget.

New in version 3.0.

Parameters:

• name (str) – The base form field name of the widget.

• value (dict) – The list of values.

• attrs (dict) – Additional HTML element attributes for the fields.

Returns:

The context data for the widget.

Return type:

dict

value_from_datadict(data, files, name)¶

Return a value for the field from a submitted form.

This serializes the data POSTed for the form into a format that the field can use and validate.

New in version 3.0.

Parameters:

• data (django.http.request.QueryDict) – The dictionary containing form data.

• files (django.http.request.QueryDict) – The dictionary containing uploaded files.

• name (str) – The field name for the value to load.

Returns:

The list of values for the field or a string of separated values for legacy behavior.

Return type:

list or str

id_for_label(id_)¶

Return the main ID to use for this widget.

This intentionally returns None since there are multiple fields under this widget.

Parameters:

id (str) – The ID of the element.

Returns:

None so that no for= attribute is rendered on the label.

Return type:

str

class RelatedObjectWidget(multivalued=True)¶

Bases: HiddenInput

A base class form widget that lets people select one or more objects.

This is a base class. Extended classes must define their own render() method, to render their own widget with their own data.

This should be used with relatedObjectSelectorView.es6.js, which extends a Backbone view to display data.

is_hidden = False¶

__init__(multivalued=True)¶

Initialize the RelatedObjectWidget.

Parameters:

• local_site_name (unicode, optional) – The name of the LocalSite where the widget is being rendered.

• multivalued (bool, optional) – Whether or not the widget should allow selecting multiple values.