Utilities¶

Newforms exposes various utilities you may want to make use of when working with forms, as well as some implementation details which you may need to make use of for customisation purposes.

formData(form)¶

Creates an object representation of a form’s elements’ contents.

Arguments:	form – a form DOM node or a String specifying a form’s `id` or `name` attribute. If a String is given, `id` is tried before `name` when attempting to find the form in the DOM. An error will be thrown if the form can’t be found.
Returns:	an object representing the data present in the form, with input names as properties. Inputs with multiple values or duplicate names will have a list of values set.

validateAll(form, formsAndFormsets)¶

Extracts data from a <form> using formData() and validates it with a list of Forms and/or FormSets.

Arguments:	form – the `<form>` into which any given forms and formsets have been rendered – this can be a React `<form>` component or a real `<form>` DOM node. formsAndFormsets (Array) – a list of Form and/or FormSet instances to be used to validate the `<form>`‘s input data.
Returns:	`true` if the `<form>`‘s input data are valid according to all given forms and formsets

util.formatToArray(str, obj[, options])¶

Replaces '{placeholders}' in a string with same-named properties from a given Object, but interpolates into and returns an Array instead of a String.

By default, any resulting empty strings are stripped out of the Array before it is returned. To disable this, pass an options object with a 'strip' property which is false.

This is useful for simple templating which needs to include ReactElement objects.

Arguments:	str (String) – a String containing placeholder names surrounded by `{` `}` obj (Object) – an Object whose properties will provide replacements for placeholders options (Object) – an options Object which can be used to disable stripping of empty strings from the resulting Array before it is returned by passing `{strip: false}`

util.makeChoices(list, submitValueProp, displayValueProp)¶

Creates a list of [submitValue, displayValue] choice pairs from a list of objects.

If any of the property names correspond to a function in an object, the function will be called with the object as the this context.

Arguments:	list (Array) – a list of objects submitValueProp (String) – the name of the property in each object holding the value to be submitted/returned when it’s a selected choice. displayValueProp (String) – the name of the property in each object holding the value to be displayed for selection by the user.

class ErrorObject(errors)¶

A collection of field errors that knows how to display itself in various formats.

Prototype Functions

ErrorObject#set(field, error)¶: Sets a field’s errors.

ErrorObject#get(field)¶: Gets errors for the given field.

ErrorObject#hasField(field)¶: Returns true if errors have been set for the given field.

ErrorObject#length()¶: Returns the number of fields errors have been set for.

ErrorObject#isPopulated()¶: Returns true if any fields have error details set.

ErrorObject#render()¶: Default rendering is as a list.

ErrorObject#asUl()¶: Displays error details as a list. Returns undefined if this object isn’t populated with any errors.

ErrorObject#asText()¶: Displays error details as text.

ErrorObject#asData()¶: Creates an “unwrapped” version of the data in the ErrorObject - a plain Object with lists of ValidationErrors as its properties.

ErrorObject#toJSON()¶: Creates a representation of all the contents of the ErrorObject for serialisation, to be called by JSON.stringify() if this object is passed to it.

class ErrorList(list)¶

A list of errors which knows how to display itself in various formats.

Prototype Functions

ErrorList#extend(errorList)¶: Adds more errors from the given list.

ErrorList#first()¶: Returns the first error message held in the list, or undefined if the list was empty.

New in version 0.9.

ErrorList#messages()¶: Returns the list of error messages held in the list, converting them from ValidationErrors to strings first if necessary.

ErrorList#length()¶: Returns the number of errors in the list.

ErrorList#isPopulated()¶: Returns true if the list contains any errors.

ErrorList#render()¶: Default rendering is as a list.

ErrorList#asUl()¶: Displays errors as a list. Returns undefined if this list isn’t populated with any errors.

ErrorList#asText()¶: Displays errors as text.

ErrorList#asData()¶: Creates an “unwrapped” version of the data in the ErrorList - a plain Array containing ValidationErrors.

ErrorList#toJSON()¶: Creates a representation of all the contents of the ErrorList for serialisation, to be called by JSON.stringify() if this object is passed to it.