API

See Specifying options for details of the defaultOptions object.

init(options, target)

Initialise formsets

Arguments

  • options (options) – The options for initialising the formset. Default values are taken from defaultOptions

  • target (String|NodeList) – The target formset or formsets. This can be a querySelector argument, a single DOM element, or list of DOM elements. If not provided, searches based on options.

Returns

Array – A list of instantiated Formset classes.

class Formset(rootEl, options)

Manage a formset

Instantiate a new formset

Arguments

  • rootEl (rootEl) – The root DOM element for the formset, as from document.getElementById or document.querySelector, for example.

  • options (options) – The options for the formset. There are no default values; you should provide these from defaultOptions

Formset.Formset

Instantiate a new formset

Formset.atMax

True if we’re at (or above) the maximum number of forms

Formset.atMin

True if we’re at (or below) the minimum number of forms

Formset.numForms

Get or set the current number of active forms

Setting this will not change how many forms exist - it is for internal use after adding or removing a form.

Formset._e(msg)

Raise an exception and attach the formset element we’re working with

Arguments

  • msg (String) – Error message

Formset.activateForm(form)

Called when a new form has been added to the formset, or an existing form has been undeleted.

Arguments

  • form (Form) – The form instance being activated

Formset.addForm()

Create and insert a new form, and let all forms know the formset has changed

Formset.collectForms(rootEl)

Collect the existing form containers and turn them into Form instances

Called by the constructor when first initialising

Arguments

  • rootEl (rootEl) – The root

Formset.createForm(id)

Create a new form DOM object from the template form

Arguments

  • id (int) – The unique ID for the form

Returns

HTMLElement – the new form root element, not attached to the DOM

Formset.deactivateForm(form)

Called when the form has been marked for deletion

The form itself stays in place and will be submitted in its deleted state so it can be removed from the database if necessary.

Arguments

  • form (Form) – The form instance being deactivated

Formset.destroyedForm(form)

Called when a form has been destroyed and removed from the DOM

Arguments

  • form (Form) – The form instance being deleted

Formset.event(name, form)

Raise an event

Arguments

  • name (string) – The name of the event, eg "click"

  • form (Form|null) – The form instance to raise an event on

Formset.getAddEl()

Create a new add button element, add it to the end of the formset root element, and bind its event handler to call Formset.addform()

Called by the constructor during initialisation.

Returns

HTMLElement – The new button element

Formset.insertForm(id, formRoot)

Insert a form into the formset

Arguments

  • id (int) – The unique ID for the form

  • formRoot (HTMLElement) – The root element of the form, as returned by Formset.createForm

Returns

Form – The Form class instance

Formset.render()

Re-render formset and forms

class Form(formset, rootEl, options)

A form within the formset.

This is used by the Formset class to represent individual forms, and is not intended for direct use.

Represent a form within a formset

Arguments

  • formset (Formset) – The formset the form is attached to.

  • rootEl (rootEl) – The root DOM element for the form, as from document.getElementById or document.querySelector, for example.

  • options (options) – The options for the formset. There are no default values.

Form.Form

Represent a form within a formset

Form.isDeleted

Check if the form is marked as deleted

Form.templatePrefix

type: string

Form prefix used in the template form

This is used to exclude it from the active forms found by formSelector

Default: the default Django prefix __prefix__ - see https://docs.djangoproject.com/en/4.2/topics/forms/formsets/#empty-form

Form.deleted()

Handle the change event when this form’s delete checkbox has been ticked and the form marked for deletion

Form.destroy()

Destroy the element and raise a formset-destroyForm event

Call when the form is no longer needed and can be completely removed

Form.getDeleteEl()

Get the delete input field for the form and add event listeners

Returns

HTMLElement – Delete input field

Form.getFields()

Get a list of the field elements in the form

Returns

Array – List of form field HTMLElements

Form.getValues()

Get a lookup table of all field values, in the same order as getFields

Returns

object – Field name to value lookup table

Form.hasContent(fieldDefaults)

Check if the form has any content which doesn’t match defaults

The default values must be passed as a dict, and can only be found if there’s a template form specified - without that we won’t know if the values were present when the page loaded/refreshed

Arguments

  • fieldDefaults (object) – Field name to value, from getValues()

Returns

bool – True if the form has content that doesn’t match fieldDefaults

Form.render()

Render the form whenever the formset changes or renders

Form.undeleted()

Handle the change event when this form’s delete checkbox has been unticked and the form no longer marked for deletion