Formsets API¶
FormSet
¶
-
class
FormSet
([kwargs])¶ A collection of instances of the same Form.
Arguments: - kwargs (Object) – configuration options.
FormSet options
New in version 0.11: FormSet options and defaulting from the prototype replace the use of
formsetFactory
, which was removed in version 0.12.The following options configure the FormSet itself.
Default values can be pre-configured by extending the FormSet with
FormSet.extend()
to set them as prototype props.Alternatively the base
FormSet
can be used directly, passing all FormSet and Form arguments at the same time.Arguments: - form (Function) – the constructor for the Form to be managed.
- kwargs.extra (Number) – the number of extra forms to be displayed – defaults to
1
. - kwargs.canOrder (Boolean) – if
true
, forms can be ordered – defaults tofalse
. - kwargs.canDelete (Boolean) – if
true
, forms can be deleted – defaults tofalse
. - kwargs.maxNum (Number) – the maximum number of forms to be displayed – defaults to
DEFAULT_MAX_NUM
. - kwargs.validateMax (Boolean) – if
true
, validation will also check that the number of forms in the data set, minus those marked for deletion, is less than or equal tomaxNum
. - kwargs.minNum (Number) – the minimum number of forms to be displayed – defaults to
0
. - kwargs.validateMin (Boolean) – if
true
, validation will also check that the number of forms in the data set, minus those marked for deletion, is greater than or equal tominNum
.
Form options
The following options are used when constructing forms for the formset.
Arguments: - kwargs.data (Array.<Object>) – list of input form data for each form, where property names are field names. A formset with data is considered to be “bound” and ready for use validating and coercing the given data.
- kwargs.files (Array.<Object>) – list of input file data for each form.
- kwargs.autoId (String) – a template for use when automatically generating
id
attributes for fields, which should contain a{name}
placeholder for the field name. Defaults toid_{name}
. - kwargs.prefix (String) – a prefix to be applied to the name of each field in each form instance.
- kwargs.onChange (Function) –
A callback to indicate to the a React component that the formset has changed, e.g. when another form is added to the formset.
This will be passed as the Form constructor’s onChange argument when creating the formset’s forms.
New in version 0.9: Replaces
kwargs.onStateChange
- kwargs.initial (Array.<Object>) – a list of initial form data objects, where property names are field names
– if a field’s value is not specified in
data
, these values will be used when rendering field widgets. - kwargs.errorConstructor (Function) – the constructor function to be used when creating error details - defaults
to
ErrorList()
. - kwargs.validation (Function) –
A value to be passed as the Form constructor’s validation argument when creating the formset’s forms – defaults to
null
.New in version 0.6.
- kwargs.managementFormCssClass (String) – a CSS class to be applied when rendering
FormSet#managementForm()
, as default rendering methods place its hidden fields in an additonal form row just for hidden fields, to ensure valid markup is generated.
-
FormSet.
extend
(prototypeProps[, constructorProps])¶ Creates a new constructor which inherits from FormSet.
Arguments: - prototypeProps (Object) – Default FormSet options and other prototype properties for the new formset, such as a custom clean method.
- constructorProps (Object) – properties to be set directly on the new constructor function.
Prototype Properties
-
FormSet#prefixFormat
¶ This string defines the format used to generate a
prefix
for forms in the formset to ensure they have uniquename
attributes. It must contain{prefix}
and{index}
placeholders.The default format is
'{prefix}-{index}'
.Type String:
Instance Properties
Formset options documented in
kwargs
above are set as instance properties.The following instance properties are also available:
-
formset.
isInitialRender
¶ Determines if this formset has been given input data which can be validated, or if it will display as blank or with configured initial values the first time it’s redered.
false
if the formset was instantiated withkwargs.data
orkwargs.files
,true
otherwise.
Prototype Functions
Prototype functions for retrieving forms and information about forms which will be displayed.
-
FormSet#managementForm
()¶ Creates and returns the ManagementForm instance for this formset.
A ManagementForm contains hidden fields which are used to keep track of how many form instances are displayed on the page.
- Browser-specific
- On the browser, ManagementForms will only ever contain
initial
data reflecting the formset’s own configuration properties.
-
FormSet#totalFormCount
()¶ Determines the number of form instances this formset contains, based on either submitted management data or initial configuration, as appropriate.
- Browser-specific
- On the browser, only the formset’s own form count configuration will be consulted.
-
FormSet#initialFormCount
()¶ Determines the number of initial form instances this formset contains, based on either submitted management data or initial configuration, as appropriate.
- Browser-specific
- On the browser, only the formset’s own form count configuration will be consulted.
-
FormSet#forms
()¶ Returns a list of this formset’s form instances.
-
FormSet#addAnother
()¶ Increments
formset.extra
and adds another form to the formset.
-
FormSet#removeForm
(index)¶ Decrements
formset.extra
and removes the form at the specified index from the formset.You must ensure the UI never lets the user remove anything but extra forms.
New in version 0.9.
-
FormSet#initialForms
()¶ Returns a list of all the initial forms in this formset.
-
FormSet#extraForms
()¶ Returns a list of all the extra forms in this formset.
-
FormSet#emptyForm
()¶ Creates an empty version of one of this formset’s forms which uses a placeholder
'__prefix__'
prefix – this is intended for cloning on the client to add more forms when newforms is only being used on the server.
Prototype functions for validating and getting information about the results of validation, and for retrieving forms based on submitted data:
-
FormSet#validate
([form[, callback(err, isValid, cleanedData)]])¶ Forces the formset to revalidate from scratch. If a
<form>
is given, data from it will be set on the formset’s forms. Otherwise, validation will be done with each form’s current input data.Arguments: - form – a
<form>
DOM node – if React’s representation of the<form>
is given, itsgetDOMNode()
function will be called to get the real DOM node. - Boolean, Object) callback (function(Error,) –
Callback for asynchronous validation.
This argument is required if the formdet or its form uses asynchronous validation - an Error will be thrown if it’s not given in this case.
The callback should be an errback with the signature
(err, isValid, cleanedData)
.
Returns: true
if the formset’s forms’ data is valid,false
otherwise.New in version 0.9.
Changed in version 0.10: Added callback argument for async validation.
- form – a
-
FormSet#setData
(data)¶ Updates the formset’s
formset.data
(andformset.isInitialRender
, if necessary) and triggers form cleaning and validation, returning the result offormset.isValid()
.Arguments: - data (Object) – new input data for the formset.
Returns: true
if the formset has no errors after validating the updated data,false
otherwise.New in version 0.5.
-
FormSet#setFormData
(formData)¶ Alias for
FormSet#setData()
, to keep the FormSet API consistent with the Form API.New in version 0.6.
-
FormSet#cleanedData
()¶ Returns a list of
form.cleanedData
objects for every form inFormSet#forms()
.Changed in version 0.9: No longer returns cleaned data for extra forms which haven’t been modified.
Changed in version 0.10: No longer includes cleaned data from incomplete extra forms.
-
FormSet#deletedForms
()¶ Returns a list of forms that have been marked for deletion.
-
FormSet#orderedForms
()¶ Returns a list of forms in the order specified by the incoming data.
Throws an Error if ordering is not allowed.
-
FormSet#addError
(errpr)¶ Adds an error that isn’t associated with a particular form.
The
error
argument can be a simple string, or an instance ofValidationError()
.New in version 0.9.
-
FormSet#nonFormErrors
()¶ Returns an
ErrorList()
of errors that aren’t associated with a particular form – i.e., fromFormSet#clean()
or externally viaFormSet#addError()
.Returns an empty
ErrorList()
if there are none.
-
FormSet#errors
()¶ Returns a list of form error for every form in the formset.
-
FormSet#totalErrorCount
()¶ Returns the number of errors across all forms in the formset.
-
FormSet#isValid
()¶ Returns
true
if every form in the formset is valid.
-
FormSet#fullClean
()¶ Cleans all of this.data and populates formset error objects.
-
FormSet#clean
()¶ Hook for doing any extra formset-wide cleaning after
Form.clean()
has been called on every form.Any
ValidationError()
raised by this method will not be associated with a particular form; it will be accesible via :js:func:FormSet#nonFormErrors
-
FormSet#hasChanged
()¶ Returns
true
if any form differs from initial.
Prototype functions for use in rendering forms.
-
FormSet#getDefaultPrefix
()¶ Returns the default base prefix for each form:
'form'
.
-
FormSet#addFields
(form, index)¶ A hook for adding extra fields on to a form instance.
Arguments: - form (Form) – the form fields will be added to.
- index (Number) – the index of the given form in the formset.
-
FormSet#addPrefix
(index)¶ Returns a formset prefix with the given form index appended.
Arguments: - index (Number) – the index of a form in the formset.
-
FormSet#isMultipart
()¶ Returns
true
if the formset needs to be multipart-encoded, i.e. it has aFileInput()
. Otherwise,false
.
-
DEFAULT_MAX_NUM
¶ The default maximum number of forms in a formet is
1000
, to protect against memory exhaustion.