Widget

This class provides a base implementation for HTML form widgets, handling the rendering of data into HTML and the extraction of values from submitted data. It manages widget attributes, localization, and template context generation to ensure consistent behavior across different input types. Key features include support for multipart forms, subwidget iteration, and custom attribute building for HTML elements.

Attributes

Attribute	Type	Description
needs_multipart_form	boolean = False	Determines does this widget need multipart form
is_localized	boolean = False	Boolean flag indicating if the widget's value should be localized using current locale settings during rendering.
is_required	boolean = False	Boolean flag that determines if the widget is rendered with a required HTML attribute.
supports_microseconds	boolean = True	Boolean flag indicating whether the widget is capable of handling and displaying microsecond precision for temporal values.
use_fieldset	boolean = False	Boolean flag determining whether the widget should be grouped within a fieldset element when rendered.

---

Constructor

Signature

def Widget(
    attrs: dict = None
)

Parameters

Name	Type	Description
attrs	dict = None	A dictionary containing HTML attributes to be set on the rendered widget.

---

Methods

---

is_hidden()

@classmethod
def is_hidden() - > boolean

Determines if the widget is of a hidden input type, which affects how it is rendered and whether it uses required attributes.

Returns

Type	Description
boolean	True if the widget's input type is 'hidden', otherwise False.

---

subwidgets()

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

Yields the subwidgets that compose this widget, typically used for complex widgets like radio buttons or checkboxes.

Parameters

Name	Type	Description
name	string	The name of the field to be used in the subwidget context.
value	any	The value to be formatted and assigned to the subwidgets.
attrs	dict	Additional HTML attributes to be applied to the subwidgets.

Returns

Type	Description
generator	A generator yielding context dictionaries for each subwidget.

---

format_value()

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

Return a value as it should appear when rendered in a template.

Parameters

Name	Type	Description
value	any	The raw data value to be formatted for display in the HTML template.

Returns

Type	Description
string	The localized or string-converted value, or None if the input is empty.

---

get_context()

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

Constructs the dictionary of data required to render the widget template, including attributes, name, and formatted value.

Parameters

Name	Type	Description
name	string	The name of the form field.
value	any	The value of the field to be rendered.
attrs	dict	HTML attributes to merge with the widget's default attributes.

Returns

Type	Description
dict	A dictionary containing the widget's state and configuration for template rendering.

---

render()

@classmethod
def render(
    name: string,
    value: any,
    attrs: dict,
    renderer: object
) - > string

Render the widget as an HTML string.

Parameters

Name	Type	Description
name	string	The name of the form field.
value	any	The value to be displayed in the widget.
attrs	dict	Optional HTML attributes to include on the rendered element.
renderer	object	The template renderer engine used to generate the HTML output.

Returns

Type	Description
string	A safe HTML string representing the widget.

---

build_attrs()

@classmethod
def build_attrs(
    base_attrs: dict,
    extra_attrs: dict
) - > dict

Build an attribute dictionary.

Parameters

Name	Type	Description
base_attrs	dict	The primary dictionary of HTML attributes.
extra_attrs	dict	Additional attributes to merge into or override the base attributes.

Returns

Type	Description
dict	A merged dictionary containing both base and extra HTML attributes.

---

value_from_datadict()

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

Given a dictionary of data and this widget's name, return the value of this widget or None if it's not provided.

Parameters

Name	Type	Description
data	dict	The dictionary of submitted form data (e.g., request.POST).
files	dict	The dictionary of submitted file data (e.g., request.FILES).
name	string	The name of the widget used as the key in the data dictionary.

Returns

Type	Description
any	The value associated with the widget name from the submitted data.

---

value_omitted_from_data()

@classmethod
def value_omitted_from_data(
    data: dict,
    files: dict,
    name: string
) - > boolean

Checks if the widget's name is missing from the provided data dictionary, indicating the field was not submitted.

Parameters

Name	Type	Description
data	dict	The dictionary of submitted form data.
files	dict	The dictionary of submitted file data.
name	string	The name of the widget to check for in the data.

Returns

Type	Description
boolean	True if the name is not present in the data, False otherwise.

---

id_for_label()

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

Return the HTML ID attribute of this Widget for use by a < label >, given the ID of the field. Return an empty string if no ID is available.

Parameters

Name	Type	Description
id_	string	The base ID of the form field.

Returns

Type	Description
string	The ID string to be used in a label's 'for' attribute.

---

use_required_attribute()

@classmethod
def use_required_attribute(
    initial: any
) - > boolean

Determines whether the widget should include the HTML 'required' attribute based on its visibility.

Parameters

Name	Type	Description
initial	any	The initial value of the field, used to determine if the required attribute is necessary.

Returns

Type	Description
boolean	True if the widget is not hidden and should use the required attribute, otherwise False.

---