ClearableFileInput

This class provides a file upload widget that includes an additional checkbox to clear the current file value. It extends the standard file input by displaying the currently uploaded file and allowing users to either replace it with a new upload or remove it entirely. The widget manages the logic for detecting contradictions between new uploads and clear requests during form submission.

Attributes

Attribute	Type	Description
clear_checkbox_label	string = _("Clear")	The text label displayed next to the checkbox used to clear the current file selection.
initial_text	string = _("Currently")	The text label used to prefix the link or reference to the currently uploaded file.
input_text	string = _("Change")	The text label used to describe the file input field when an initial file is already present.
template_name	string = "django/forms/widgets/clearable_file_input.html"	The path to the HTML template used to render the clearable file input widget.
checked	boolean = false	A boolean flag indicating whether the clear checkbox is currently selected based on submitted data.
use_fieldset	boolean = false	Determines whether the widget should be rendered within a fieldset element for grouping related inputs.

---

Methods

---

clear_checkbox_name()

@classmethod
def clear_checkbox_name(
    name: string
) - > string

Given the name of the file input, return the name of the clear checkbox input.

Parameters

Name	Type	Description
name	string	The name of the file input field

Returns

Type	Description
string	The name attribute for the clear checkbox, generated by appending a suffix to the file input name

---

clear_checkbox_id()

@classmethod
def clear_checkbox_id(
    name: string
) - > string

Given the name of the clear checkbox input, return the HTML id for it.

Parameters

Name	Type	Description
name	string	The name of the clear checkbox input

Returns

Type	Description
string	The HTML id attribute for the clear checkbox element

---

is_initial()

@classmethod
def is_initial(
    value: object
) - > boolean

Return whether value is considered to be initial value.

Parameters

Name	Type	Description
value	object	The value to check for initial file state

Returns

Type	Description
boolean	True if the value exists and has a valid URL attribute, indicating an existing file

---

format_value()

@classmethod
def format_value(
    value: object
) - > object

Return the file object if it has a defined url attribute.

Parameters

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

Returns

Type	Description
object	The file object if it is considered an initial value, otherwise None

---

get_context()

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

Builds the template context for rendering the widget, including checkbox metadata and labels.

Parameters

Name	Type	Description
name	string	The name of the form field
value	object	The current value of the field
attrs	dict	HTML attributes to be added to the widget

Returns

Type	Description
dict	A dictionary containing widget attributes, checkbox names, IDs, and display text for the template

---

value_from_datadict()

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

Extracts the file upload or clear signal from the submitted data, handling contradictions between new uploads and the clear checkbox.

Parameters

Name	Type	Description
data	dict	The dictionary of POST data
files	dict	The dictionary of uploaded files
name	string	The name of the form field

Returns

Type	Description
object	The uploaded file, False if the file should be cleared, or a contradiction marker if both actions were attempted

---

value_omitted_from_data()

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

Determines if the field's data is missing from the submission, accounting for both the file input and the clear checkbox.

Parameters

Name	Type	Description
data	dict	The dictionary of POST data
files	dict	The dictionary of uploaded files
name	string	The name of the form field

Returns

Type	Description
boolean	True if neither the file input nor the clear checkbox are present in the submitted data

---