newforms

https://newforms.readthedocs.io/en/latest/
Admin
newforms is an isomorphic JavaScript form-handling library for React that manages form rendering,...
Tokens:50,906
Snippets:534
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install and Require newforms

Source: https://newforms.readthedocs.io/en/latest/index.html

Installation via npm and basic module requirement for Node.js environments.

```bash
npm install newforms
```

```javascript
var forms = require('newforms')
```

--------------------------------

### Render RenderFormSet component

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Examples of initializing RenderFormSet using either a Form constructor or a FormSet constructor.

```jsx
<RenderFormSet form={MyForm} extra="3" ref="myFormset"/>

<RenderFormSet formset={MyFormSet} ref="myFormset"/>
```

--------------------------------

### Dynamic Choices with ProjectBookingForm

Source: https://newforms.readthedocs.io/en/latest/fields.html

Example of creating a form with dynamic choices for projects using a custom form constructor and the `makeChoices` helper.

```APIDOC
## Dynamic choices
A common pattern for providing dynamic choices (or indeed, dynamic anything) is to provide your own form constructor and pass in whatever data is required to make changes to `form.fields` as the form is being instantiated.
Newforms provides a `util.makeChoices()` helper function for creating choice pairs from a list of objects using named properties:
```javascript
var ProjectBookingForm = forms.Form.extend({
  project: forms.ChoiceField(),
  hours: forms.DecimalField({minValue: 0, maxValue: 24, maxdigits: 4, decimalPlaces: 2}),
  date: forms.DateField(),

  constructor: function(projects, kwargs) {
    // Call the constructor of whichever form you're extending so that the
    // forms.Form constructor eventually gets called - this.fields doesn't
    // exist until this happens.
    forms.Form.call(this, kwargs)

    // Now that this.fields is a thing, make whatever changes you need to -
    // in this case, we're going to creata a list of pairs of project ids
    // and names to set as the project field's choices.
    this.fields.project.setChoices(forms.util.makeChoices(projects, 'id', 'name'))
  }
})

var projects = [
  {id: 1, name: 'Project 1'}
, {id: 2, name: 'Project 2'}
, {id: 3, name: 'Project 3'}
]
var form = new ProjectBookingForm(projects, {autoId: false})
print(reactHTML((form.boundField('project').render()))
/* =>
<select name=\"project\">
<option value=\"1\">Project 1</option>
<option value=\"2\">Project 2</option>
<option value=\"3\">Project 3</option>
</select>
*/
```

Server-side example of using a form with dynamic choices:
```javascript
// Users are assigned to projects and they're booking time, so we need to:
// 1. Display choices for the projects they're assigned to
// 2. Validate that the submitted project id is one they've been assigned to
var form
var display = function() { res.render('book_time', {form: form}) }
req.user.getProjects(function(err, projects) {
  if (err) { return next(err) }
  if (req.method == 'POST') {
    form = new ProjectBookingForm(projects, {data: req.body})
    if (form.isValid()) {
      return ProjectService.saveHours(user, form.cleanedData, function(err) {
        if (err) { return next(err) }
        return res.redirect('/time/book/')
      })
    }
  }
  else {
    form = new ProjectBookingForm(projects)
  }
  display(form)
})
```
```

--------------------------------

### Define a Signup Form with Fields and Custom Validation

Source: https://newforms.readthedocs.io/en/latest/react_client.html

This example shows how to define a form with email, password, and terms fields, including a custom 'clean' method for cross-field validation.

```javascript
var SignupForm = forms.Form.extend({
  email: forms.EmailField(),
  password: forms.CharField({widget: forms.PasswordInput}),
  confirm: forms.CharField({label: 'Confirm password', widget: forms.PasswordInput}),
  terms: forms.BooleanField({
    label: 'I have read and agree to the Terms and Conditions',
    errorMessages: {required: 'You must accept the terms to continue'}
  }),

  clean: function() {
    if (this.cleanedData.password && this.cleanedData.confirm &&
        this.cleanedData.password != this.cleanedData.confirm) {
      throw forms.ValidationError('Passwords do not match.')
    }
  }
})
```

--------------------------------

### GenericIPAddressField() IPv6 Normalization Example

Source: https://newforms.readthedocs.io/en/latest/fields.html

Demonstrates IPv6 address normalization according to RFC 4291, including IPv4-mapped addresses. All characters are converted to lowercase.

```python
from django.forms import GenericIPAddressField

ip_field = GenericIPAddressField()

# Example of IPv6 normalization
print(ip_field.normalize('2001:0::0:01'))
# Output: 2001::1

# Example of IPv4-mapped address normalization
print(ip_field.normalize('::ffff:0a0a:0a0a'))
# Output: ::ffff:10.10.10.10
```

--------------------------------

### Define ChoiceField choices

Source: https://newforms.readthedocs.io/en/latest/fields_api.html

Example of the structure for the choices argument in a ChoiceField.

```javascript
{choices: [[1, 'One'], [2, 'Two']]}
```

--------------------------------

### Define choice pairs

Source: https://newforms.readthedocs.io/en/latest/fields.html

Example of defining a list of choice pairs for a Select widget.

```javascript
var STATE_CHOICES = [
  ['S', 'Scoped']
, ['D', 'Defined']
, ['P', 'In-Progress']
, ['C', 'Completed']
, ['A', 'Accepted']
]
print(reactHTML(forms.Select().render('state', null, {choices: STATE_CHOICES})))
```

--------------------------------

### Define grouped choice lists

Source: https://newforms.readthedocs.io/en/latest/fields.html

Example of using optgroups to categorize choices within a Select widget.

```javascript
var DRINK_CHOICES = [
  ['Cheap', [
      [1, 'White Lightning']
    , [2, 'Buckfast']
    , [3, 'Tesco Gin']
    ]
  ]
, ['Expensive', [
      [4, 'Vieille Bon Secours Ale']
    , [5, 'Château d’Yquem']
    , [6, 'Armand de Brignac Midas']
    ]
  ]
, [7, 'Beer']
]
print(reactHTML(forms.Select().render('drink', null, {choices: DRINK_CHOICES})))
```

--------------------------------

### Extend MultiWidget to Create DateSelectorWidget

Source: https://newforms.readthedocs.io/en/latest/widgets.html

This example demonstrates how to extend MultiWidget to create a custom widget for selecting dates. It includes implementations for the constructor, decompress, formatOutput, and valueFromData methods.

```javascript
var DateSelectorWidget = forms.MultiWidget.extend({
  constructor: function(kwargs) {
    kwargs = extend({attrs: {}}, kwargs)
    widgets = [
      forms.Select({choices: range(1, 32), attrs: kwargs.attrs}),
      forms.Select({choices: range(1, 13), attrs: kwargs.attrs}),
      forms.Select({choices: range(2012, 2017), attrs: kwargs.attrs})
    ]
    forms.MultiWidget.call(this, widgets, kwargs)
  },

  decompress: function(value) {
    if (value instanceof Date) {
      return [value.getDate(),
              value.getMonth() + 1, // Make month 1-based for display
              value.getFullYear()]
    }
    return [null, null, null]
  },

  formatOutput: function(renderedWidgets) {
    return React.createElement('div', null, renderedWidgets)
  },

  valueFromData: function(data, files, name) {
    var parts = this.widgets.map(function(widget, i) {
      return widget.valueFromData(data, files, name + '_' + i)
    })
    parts.reverse() // [d, m, y] => [y, m, d]
    return parts.join('-')
  }
})

```

--------------------------------

### EmailField Validation Example

Source: https://newforms.readthedocs.io/en/latest/fields.html

Demonstrates how to use the clean() method of an EmailField for validation. Shows successful validation and how to catch validation errors.

```javascript
var f = forms.EmailField()
print(f.clean('foo@example.com'))
// => foo@example.com
try {
  f.clean('invalid email address')
}
catch (e) {
  print(e.messages())
}
// => ["Enter a valid email address."]
```

--------------------------------

### Optional CharField Example

Source: https://newforms.readthedocs.io/en/latest/fields.html

Shows how to create a CharField that is not required by passing `required: false` to the constructor. An empty value will return a normalized empty string instead of raising a ValidationError.

```javascript
var f = forms.CharField({required: false})
```

--------------------------------

### Customize RenderForm containers

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Example of using component, className, and rowComponent props to customize the HTML structure of a rendered form.

```jsx
<RenderForm form={ParentForm}
   component="ul"
   className="parent"
   rowComponent="li"
   autoId={false}
/>
```

--------------------------------

### Declarative Fields Meta Setup

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

Use `DeclarativeFieldsMeta()` as a mixin to set up form fields during Form constructor creation. It handles field inheritance and precedence from prototype properties, mixins, and base classes.

```javascript
DeclarativeFieldsMeta(_prototypeProps_)
```

--------------------------------

### Define a Form and Render with Prefixes

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Define a form class and use the prefix prop to manage multiple instances of the same form.

```javascript
var ParentForm = forms.Form.extend({
  name: forms.CharField(),
  dob: forms.DateField({label: 'Date of birth'})
})
```

```javascript
<fieldset>
  <legend>Parent 1</legend>
  <RenderForm form={ParentForm} prefix="parent1"/>
</fieldset>
<fieldset>
  <legend>Parent 2</legend>
  <RenderForm form={ParentForm} prefix="parent2"/>
</fieldset>
```

--------------------------------

### Get BoundFields as a List

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `form.boundFields()` to get a list of all BoundField instances for a form, ordered as defined in the form. This is useful for iterating through fields in their declared order.

```python
form.boundFields()
```

--------------------------------

### Get Validation Errors for a Field

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `bf.errors()` to get an object containing validation error messages for a BoundField. It includes a default rendering to a `<ul class="errorlist">`.

```python
bf.errors()
```

--------------------------------

### Get Field Validation Status

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `bf.status()` to get the current validation status of a field as a string. Possible values are 'pending', 'error', 'valid', or 'default'. This method is available from version 0.10.

```python
bf.status()
```

--------------------------------

### Form Constructor

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

Initializes a new Form instance with specific configuration options for data binding, validation, and rendering behavior.

```APIDOC
## Form Constructor

### Description
Initializes a collection of Fields that knows how to validate and display itself.

### Parameters
- **kwargs.data** (Object) - Optional - Input form data for binding.
- **kwargs.files** (Object) - Optional - Input file data.
- **kwargs.errors** (ErrorObject) - Optional - Initial errors to be displayed.
- **kwargs.validation** (String/Object) - Optional - Configures form-wide interactive validation.
- **kwargs.controlled** (Boolean) - Optional - Configures whether the form renders controlled components.
- **kwargs.onChange** (Function) - Optional - Callback function triggered on input data or validation state changes.
- **kwargs.autoId** (String) - Optional - Template for generating field id attributes.
- **kwargs.prefix** (String) - Optional - Prefix applied to the name of each field.
- **kwargs.initial** (Object) - Optional - Initial form data for rendering.
- **kwargs.errorConstructor** (Function) - Optional - Constructor for creating error details.
- **kwargs.labelSuffix** (String) - Optional - Suffix used when generating labels.
- **kwargs.emptyPermitted** (Boolean) - Optional - Whether the form is allowed to be empty.
```

--------------------------------

### Instantiate a Form with Data

Source: https://newforms.readthedocs.io/en/latest/forms.html

Initialize a form with a data object containing field values.

```javascript
var data = {
  subject: 'hello'
, message: 'Hi there'
, sender: 'foo@example.com'
, ccMyself: true
}
var f = new ContactForm({data: data})
```

--------------------------------

### Extend TextInput constructor

Source: https://newforms.readthedocs.io/en/latest/fields.html

Shows how to create a custom widget constructor by extending TextInput.

```javascript
var TelInput = TextInput.extend({
  inputType: 'tel'
})
```

--------------------------------

### Retrieve raw field value

Source: https://newforms.readthedocs.io/en/latest/forms.html

Use boundField.value() to get the raw value of a field as it would be rendered by a widget.

```javascript
var initial = {subject: 'welcome'}
var data = {subject: 'hi'}
var unboundForm = new ContactForm({initial: initial})
var boundForm = new ContactForm({data: data, initial: initial})
print(unboundForm.boundField('subject').value())
// => welcome
print(boundForm.boundField('subject').value())
// => hi
```

--------------------------------

### Instantiate a Form

Source: https://newforms.readthedocs.io/en/latest/forms.html

Create a new instance of a form without initial data.

```javascript
var f = new ContactForm()
```

--------------------------------

### Get field ID for label

Source: https://newforms.readthedocs.io/en/latest/forms.html

Use idForLabel() to retrieve the ID of a field, useful for manual JSX label construction.

```javascript
<label htmlFor={form.boundField('myField').idForLabel()}>...<label>
```

--------------------------------

### Custom Rendering with Props

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Demonstrates how to customize the rendering of Newforms components using props like `component`, `className`, and `rowComponent`.

```APIDOC
## Custom rendering with props

### Description
The bundled React components offer a degree of customization via their props. You can use the `component`, `className` and `rowComponent` props to customize the containers.

### Example 1: Customizing Containers
```jsx
<RenderForm form={ParentForm}
   component="ul"
   className="parent"
   rowComponent="li"
   autoId={false}
/>
```

Which renders as:
```html
<ul class="parent">
  <li>Name: <input type="text" name="name"></li>
  <li>Date of birth: <input type="text" name="dob"></li>
</ul>
```

### Example 2: Custom Form Row
You can also customize how form rows are generated by passing a custom React component to the `row` prop.
```jsx
<RenderForm form={ParentForm} row={MySpecialFormRow}/>
```

Note: Keep in mind when implementing a custom row component that it will receive props as per those described for FormRow.
```

--------------------------------

### Set arguments for widget initialization

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Pass configuration objects like attrs to the widget constructor to control the rendered HTML attributes.

```javascript
var CommentForm = forms.Form.extend({
  name: forms.CharField(),
   url: forms.URLField(),
   comment: forms.CharField({
    widget: forms.Textarea({attrs: {rows: 6, cols: 60}})
  })
})
```

--------------------------------

### Customize form rows

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Example of passing a custom React component to the row prop to override default row rendering.

```jsx
<RenderForm form={ParentForm} row={MySpecialFormRow}/>
```

--------------------------------

### FormSet Constructor

Source: https://newforms.readthedocs.io/en/latest/formsets_api.html

Initializes a new FormSet instance with configuration options for form management.

```APIDOC
## FormSet Constructor

### Description
Creates a collection of instances of the same Form.

### Parameters
#### Request Body
- **form** (Function) - Required - The constructor for the Form to be managed.
- **kwargs.extra** (Number) - Optional - Number of extra forms to display; defaults to 1.
- **kwargs.canOrder** (Boolean) - Optional - If true, forms can be ordered; defaults to false.
- **kwargs.canDelete** (Boolean) - Optional - If true, forms can be deleted; defaults to false.
- **kwargs.maxNum** (Number) - Optional - Maximum number of forms; defaults to DEFAULT_MAX_NUM.
- **kwargs.minNum** (Number) - Optional - Minimum number of forms; defaults to 0.
```

--------------------------------

### Format Fields

Source: https://newforms.readthedocs.io/en/latest/fields_api.html

Documentation for RegexField, EmailField, GenericIPAddressField, and SlugField.

```APIDOC
## Format Fields

### RegexField
- **regex** (RegExp or String) - Required - Regular expression to validate against.

### GenericIPAddressField
- **protocol** (String) - Optional - 'both', 'ipv4', or 'ipv6'. Defaults to 'both'.
- **unpackIPv4** (Boolean) - Optional - Whether to unpack mapped IPv4 addresses. Defaults to false.
```

--------------------------------

### File Upload Widgets

Source: https://newforms.readthedocs.io/en/latest/widgets_api.html

Documentation for widgets used for file input handling.

```APIDOC
## FileInput

### Description
An <input type="file"> widget.

## ClearableFileInput

### Description
A file widget which also has a checkbox to indicate that the field should be cleared.
```

--------------------------------

### Handle Form Submission and Validation

Source: https://newforms.readthedocs.io/en/latest/quickstart.html

On form submission, get the form instance using its `ref` and call `validate()`. If valid, access the `cleanedData` object.

```javascript
  propTypes: {
    onSignup: React.PropTypes.func.isRequired
  },

  _onSubmit: function(e) {
    e.preventDefault()

    var form = this.refs.signupForm.getForm()
    var isValid = form.validate()
    if (isValid) {
      this.props.onSignup(form.cleanedData)
    }
  }
})
```

--------------------------------

### Initialize formset with data

Source: https://newforms.readthedocs.io/en/latest/formsets.html

Pass an array of objects as initial data to populate form fields.

```javascript
var ArticleFormSet = forms.FormSet.extend({form: ArticleForm, extra: 2})
var formset = new ArticleFormSet({initial: [
  {title: "Django's docs are open source!", pubDate: new Date()}
]})
formset.forms().forEach(function(form) {
  print(reactHTML(<RenderForm form={form}/>))
})
/* =>
<div>
  <div><label for="id_form-0-title">Title:</label> <input type="text" name="form-0-title" id="id_form-0-title" value="Django's docs are open source!"></div>
  <div><label for="id_form-0-pubDate">Pub date:</label> <input type="text" name="form-0-pubDate" id="id_form-0-pubDate" value="2014-02-28"></div>
</div>
<div>
  <div><label for="id_form-1-title">Title:</label> <input type="text" name="form-1-title" id="id_form-1-title"></div>
  <div><label for="id_form-1-pubDate">Pub date:</label> <input type="text" name="form-1-pubDate" id="id_form-1-pubDate"></div>
</div>
<div>
  <div><label for="id_form-2-title">Title:</label> <input type="text" name="form-2-title" id="id_form-2-title"></div>
  <div><label for="id_form-2-pubDate">Pub date:</label> <input type="text" name="form-2-pubDate" id="id_form-2-pubDate"></div>
</div>
*/
```

--------------------------------

### Remove Prefix from Field Name

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

Use `removePrefix()` to remove the form's prefix from the start of a field name, if the field name begins with the prefix.

```javascript
Form#removePrefix(_fieldName_)
```

--------------------------------

### Get BoundFields as an Object

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `form.boundFieldsObj()` to retrieve an object where keys are field names and values are BoundField instances. This is useful for accessing specific fields by name.

```python
form.boundFieldsObj()
```

--------------------------------

### Async Username Availability Check

Source: https://newforms.readthedocs.io/en/latest/validation.html

Use this for validating if a username is already taken during signup. It performs an HTTP POST request and calls back with an error or validation result.

```javascript
cleanUsername: function(callback) {
  http.post('/checkuser', {username: this.cleanedData.username}, function(err, res) {
    // There was an error during the HTTP request
    if (err) {
      return callback(err)
    }

    // The username is already taken
    if (res.alreadyTaken) {
      return callback(null, forms.ValidationError('This username is already taken.'))
    }

    // The username is available
    callback()
  })
}
```

--------------------------------

### Input Widgets

Source: https://newforms.readthedocs.io/en/latest/widgets_api.html

Standard HTML input widget classes.

```APIDOC
## Input Widgets

### Classes
- **Input**: Base <input> widget.
- **TextInput**: <input type="text"> widget.
- **NumberInput**: <input type="number"> widget.
- **EmailInput**: <input type="email"> widget.
- **URLInput**: <input type="url"> widget.
- **PasswordInput**: <input type="password"> widget. Supports `renderValue` (Boolean) option.
- **HiddenInput**: <input type="hidden"> widget.
- **Textarea**: <textarea> widget.
```

--------------------------------

### Accessing Cleaned Data from a Valid Form

Source: https://newforms.readthedocs.io/en/latest/forms.html

Access the `cleanedData` property of a form instance after validation to get normalized data. This property contains only valid fields from the input data.

```javascript
var data = {
  subject: 'hello'
, message: 'Hi there'
, sender: 'foo@example.com'
, ccMyself: true
}
var f = new ContactForm({data: data})
print(f.isValid())
// => true
print(f.cleanedData)
// => {subject: 'hello', message: 'Hi there', sender: 'foo@example.com', ccMyself: true}
```

--------------------------------

### Define a base form

Source: https://newforms.readthedocs.io/en/latest/formsets.html

Create a standard form class using forms.Form.extend.

```javascript
var ArticleForm = forms.Form.extend({
  title: forms.CharField(),
  pubDate: forms.DateField()
})
```

--------------------------------

### Get Field Value for Display

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `bf.value()` to retrieve the value that will be displayed in the field's user input element. This is useful for pre-populating forms or displaying current data.

```python
bf.value()
```

--------------------------------

### Forms API Overview

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

This section provides an overview of the Forms API, its main components, and how to use them.

```APIDOC
## Forms API

This API provides a comprehensive set of tools for creating, validating, and rendering forms in your application.

### Core Components

*   **`Form`**: The base class for all forms.
*   **BoundField**: Represents a field that is bound to a form instance.
*   **Fields**: Various field types for different data inputs (e.g., CharField, IntegerField).
*   **Validation**: Mechanisms for validating form data.
*   **Widgets**: Controls for rendering form fields (e.g., TextInput, Checkbox).
*   **Formsets**: Tools for managing multiple instances of a form.

### Utilities

A collection of utility functions to assist with form handling.
```

--------------------------------

### Get the First Validation Error Message

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `bf.errorMessage()` to retrieve the first validation error message as a string. Returns `undefined` if there are no errors, making it convenient for conditional display.

```python
bf.errorMessage()
```

--------------------------------

### Get a Specific BoundField

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `form.boundField(fieldName)` to retrieve the BoundField instance for a specific field by its name. This allows direct access to a single field's rendering helpers.

```python
form.boundField(fieldName)
```

--------------------------------

### Render raw HTML in help text

Source: https://newforms.readthedocs.io/en/latest/boundfield_api.html

Use the React convention of an object with a __html property to render raw HTML within help text tags.

```javascript
{__html: 'But <strong>be careful</strong>!'}
```

--------------------------------

### Utilities

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

A collection of utility functions for form manipulation.

```APIDOC
## Utilities

### Description
This section covers various utility functions that can be used to enhance form handling.

*(Note: Specific utility functions are not detailed in the provided text. This section serves as a placeholder for such documentation.)*
```

--------------------------------

### Using Multiple Formsets with Prefixes

Source: https://newforms.readthedocs.io/en/latest/formsets.html

Utilize the 'prefix' option when initializing formsets to prevent naming collisions when multiple formsets are used within the same HTML form. This is crucial for both client-side and server-side data processing.

```javascript
var ArticleFormSet = forms.FormSet.extend({form: ArticleForm})
var BookFormSet = forms.FormSet.extend({form: Book})

var PublicationManager = React.createClass({
  getInitialState: function() {
    return {
      articleFormset: new ArticleFormSet({prefix: 'articles'})
    , bookFormset: new BookFormSet({prefix: 'books'})
    }
  },

  // ...rendering implemented as normal...

  onSubmit: function(e) {
    e.preventDefault()
    var articlesValid = this.state.articleFormset.validate()
    var booksValid = this.state.bookFormset.validate()
    if (articlesValid && booksValid) {
      // Do something with cleanedData() on the formsets
    }
  }
})

```

--------------------------------

### Define a Simple Form

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Defines a basic form with name, URL, and comment fields using default text input widgets.

```javascript
var CommentForm = forms.Form.extend({
  name: forms.CharField(),
  url: forms.URLField(),
  comment: forms.CharField()
})

```

--------------------------------

### Define a Form Class

Source: https://newforms.readthedocs.io/en/latest/overview.html

Create a form by extending forms.Form and declaring fields with their respective metadata.

```javascript
var ContactForm = forms.Form.extend({
  subject: forms.CharField({maxLength: 100}),
  message: forms.CharField(),
  sender: forms.EmailField(),
  ccMyself: forms.BooleanField({required: false})
})
```

--------------------------------

### Add French Locale to Newforms

Source: https://newforms.readthedocs.io/en/latest/locales.html

Use `forms.addLocale()` to register a new locale with its specific date and time format configurations. This example adds a French locale with custom input formats.

```javascript
forms.addLocale('fr', {
  b: 'janv._févr._mars_avr._mai_juin_juil._août_sept._oct._nov._déc.'.split('_')
, B: 'janvier_février_mars_avril_mai_juin_juillet_août_septembre_octobre_novembre_décembre'.split('_')
, DATE_INPUT_FORMATS: [
    '%d/%m/%Y', '%d/%m/%y'
  , '%d %b %Y', '%d %b %y'
  , '%d %B %Y', '%d %B %y'
  ]
, DATETIME_INPUT_FORMATS: [
    '%d/%m/%Y %H:%M:%S'
  , '%d/%m/%Y %H:%M'
  , '%d/%m/%Y'
  ]
})
```

--------------------------------

### Manage choices in Select-based widgets

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Demonstrates how choices are inherited from a ChoiceField and how they can be updated dynamically on the widget.

```javascript
var CHOICES = [['1', 'First'], ['2', 'Second']]
var field = forms.ChoiceField({choices: CHOICES, widget: forms.RadioSelect})
print(field.choices())
// => [['1', 'First'], ['2', 'Second']]
print(field.widget.choices
// => [['1', 'First'], ['2', 'Second']]
field.widget.choices = []
field.setChoices([['1', 'First and only']])
print(field.widget.choices)
// => [['1', 'First and only']]
```

--------------------------------

### Custom Async Progress Rendering with React Component

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Replace the default progress indicator during async validation by passing a React component to the 'progress' prop. This example shows how to use a React.createClass component for a spinner image.

```javascript
var InProgress = React.createClass({
  render() {
    return <span>
      <img src="/img/spinner.gif" alt=""/> Validating&hellip;
    </span>
  }
})
```

--------------------------------

### Custom Formset Validation Logic

Source: https://newforms.readthedocs.io/en/latest/formsets.html

Implement custom validation for formsets by overriding the clean() method. This example checks for distinct titles across articles. Ensure individual forms are valid before proceeding with formset-level validation.

```javascript
var ArticleFormSet = forms.FormSet.extend({
  form: ArticleForm,
  /** Checks that no two articles have the same title. */
  clean: function() {
    if (this.totalErrorCount() !== 0) {
      // Don't bother validating the formset unless each form is valid on its own
      return
    }
    var titles = {}
    this.forms().forEach(function(form) {
      var title = form.cleanedData.title
      if (title in titles) {
        throw forms.ValidationError('Articles in a set must have distinct titles.')
      }
      titles[title] = true
    })
  }
})

var data = {
  'form-TOTAL_FORMS': '2'
, 'form-INITIAL_FORMS': '0'
, 'form-MAX_NUM_FORMS': ''
, 'form-0-title': 'Test'
, 'form-0-pubDate': '1904-06-16'
, 'form-1-title': 'Test'
, 'form-1-pubDate': '1912-06-23'
}
var formset = new ArticleFormSet({data: data})
print(formset.isValid())
// => false
print(formset.errors().map(function(e) { return e.toJSON() }))
// => [{}, {}])
print(formset.nonFormErrors().messages())
// => ['Articles in a set must have distinct titles.']

```

--------------------------------

### Select Widget

Source: https://newforms.readthedocs.io/en/latest/widgets_api.html

Represents an HTML select element.

```APIDOC
## Select

### Description
An HTML `<select>` widget.

### Arguments
- **kwargs** (Object) - Widget options.
  - **kwargs.choices** (Array) - Choices to be used when rendering the widget, with each choice specified as a pair in `[value, text]` format. Defaults to `[]`.
```

--------------------------------

### Widget Customization via attrs

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Learn how to customize the appearance and behavior of form widgets by passing an attrs object during instantiation.

```APIDOC
## Widget Customization

### Description
Customize widget instances by specifying additional HTML attributes using the `attrs` argument when instantiating a widget within a form field.

### Parameters
#### Request Body
- **attrs** (object) - Optional - An object containing HTML attributes (e.g., className, size, title) to be applied to the rendered widget element.

### Request Example
```javascript
name: forms.CharField({
  widget: forms.TextInput({attrs: {className: 'special', size: '20'}})
})
```
```

--------------------------------

### Composite Widgets

Source: https://newforms.readthedocs.io/en/latest/widgets_api.html

Documentation for widgets that handle multiple values or split inputs.

```APIDOC
## MultipleHiddenInput

### Description
A widget that handles <input type="hidden"> for fields that have a list of values.

## SplitDateTimeWidget

### Description
Splits Date input into two <input type="text"> elements.

### Parameters
#### kwargs (Object)
- **dateFormat** (String) - Optional - A time.strftime() format string for a date.
- **timeFormat** (String) - Optional - A time.strftime() format string for a time.

## SplitHiddenDateTimeWidget

### Description
Splits Date input into two <input type="hidden"> elements.
```

--------------------------------

### Generate Help Text Tag

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

Use `bf.helpTextTag()` to generate an HTML element (by default, `<span className="helpText">`) containing the field's help text, if configured. This can be customized with arguments.

```python
bf.helpTextTag()
```

--------------------------------

### Form Instance Properties

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

Properties available on a form instance after it has been constructed.

```APIDOC
## Form Instance Properties

### `form.fields`

**Description:** Form fields for this instance of the form. Fields are deep-copied into `fields` every time a new instance is created. Instances should only modify `fields`.

**Note:** `fields` does not exist until the `Form` constructor has been called.

**Type:** Object with field names as property names and Field instances as properties.
```

```APIDOC
### `form.isInitialRender`

**Description:** Determines if this form has been given input data which can be validated. `true` if the form has `data` or `files` set.
```

```APIDOC
### `form.cleanedData`

**Description:** After a form has been validated, this property contains only the valid fields. If data does not validate, `cleanedData` will contain only the valid fields.

**Type:** Object with field names as property names and valid, cleaned values coerced to the appropriate JavaScript type as properties.
```

--------------------------------

### newforms API Overview

Source: https://newforms.readthedocs.io/en/latest/api.html

A summary of the core modules and classes available in the newforms library.

```APIDOC
## newforms API Reference

### Description
The newforms library provides a comprehensive set of tools for form handling, validation, and widget rendering. Note that properties and methods starting with an underscore are considered implementation details and should not be relied upon.

### Core Modules
- **Forms API**: Includes `Form` and various utilities.
- **BoundField API**: Includes `BoundField`.
- **Fields API**: Includes `Field` and specialized field types (Numeric, Date/Time, Format, File, Boolean, Choice, and Complex).
- **Validation API**: Includes `ValidationError`, error handling, and validators.
- **Widgets API**: Includes `Widget`, `MultiWidget`, and various input/selector/file/composite widgets.
- **Formsets API**: Includes `FormSet`.
```

--------------------------------

### Render Widget with Attributes

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Renders a TextInput widget instance with specified HTML attributes for size and title, showing the resulting HTML input tag.

```javascript
var name = forms.TextInput({attrs: {size:10, title: 'Your name'}})
print(reactHTML(name.render('name', 'A name')))
// => <input size="10" title="Your name" type="text" name="name" value="A name">

```

--------------------------------

### Base Widget Class

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Overview of the base Widget class and its core methods for rendering and data retrieval.

```APIDOC
## Widget Class

### Description
The base class for all widgets. It provides the `attrs` attribute and defines the interface for rendering and data extraction.

### Methods
- **render(name, value)**: Returns a ReactElement representation of the widget. Must be implemented by subclasses.
- **valueFromData(data, name)**: Extracts the value for this widget from an input data object. Returns null if not found.
```

--------------------------------

### Date/Time Fields

Source: https://newforms.readthedocs.io/en/latest/fields_api.html

Documentation for DateField, TimeField, and DateTimeField classes.

```APIDOC
## Date/Time Fields

### DateField, TimeField, DateTimeField
- **inputFormats** (Array<String>) - Optional - List of time.strptime() format strings.
```

--------------------------------

### BoundField#helpTextTag

Source: https://newforms.readthedocs.io/en/latest/boundfield_api.html

Renders an HTML tag containing the help text for the field, with customizable tag type, content, and attributes.

```APIDOC
## BoundField#helpTextTag

### Description
Renders a tag containing help text for the field.

### Method
N/A (Method of BoundField class)

### Parameters
#### Arguments
- **kwargs** (Object) - Help text tag options:
  - **tagName** (String) - Overrides the default tag type ('span').
  - **contents** (String|Object) - Help text content. Defaults to field's help text. Use `{"__html": "..."}` for raw HTML.
  - **attrs** (Object) - Additional attributes for the tag. Defaults to `{"className": "helpText"}`.
```

--------------------------------

### DateInput Widget

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Documentation for the DateInput widget, which renders a date input as a text box.

```APIDOC
## DateInput()

### Description
Date input as a simple text box: <input type='text' ...>

### Parameters
#### Request Body
- **format** (string) - Optional - The format in which this field’s initial value will be displayed. If not provided, defaults to the first format in the current locale’s DATE_INPUT_FORMATS.
```

--------------------------------

### Render Default Form

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Renders a form instance with default widgets, showing their basic HTML output without custom attributes.

```javascript
var f = new CommentForm({autoId: false})
print(reactHTML(<RenderForm form={f}/>))
/* =>
<div>
  <div>Name: <input type="text" name="name"></div>
  <div>Url: <input type="url" name="url"></div>
  <div>Comment: <input type="text" name="comment"></div>
</div>
*/

```

--------------------------------

### Date-formatting Input Widgets

Source: https://newforms.readthedocs.io/en/latest/widgets_api.html

Input widgets that format Date objects into strings.

```APIDOC
## Date-formatting Input Widgets

### Classes
- **DateInput**: Formats Date as a date string.
- **DateTimeInput**: Formats Date as a datetime string.
- **TimeInput**: Formats Date as a time string.

### Parameters
- **kwargs.format** (String) - Optional - A time.strftime() format string.
```

--------------------------------

### Render a Form with RenderForm

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Basic usage of the RenderForm component to display a form.

```javascript
<RenderForm form={MyForm} ref="myForm"/>
```

--------------------------------

### FormSet Methods

Source: https://newforms.readthedocs.io/en/latest/formsets_api.html

Details on the methods available within the FormSet class.

```APIDOC
## FormSet#addFields

### Description
A hook for adding extra fields on to a form instance.

### Method
FormSet.addFields

### Parameters
#### Arguments
- **form** (Form) – the form fields will be added to.
- **index** (Number) – the index of the given form in the formset.

## FormSet#addPrefix

### Description
Returns a formset prefix with the given form index appended.

### Method
FormSet.addPrefix

### Parameters
#### Arguments
- **index** (Number) – the index of a form in the formset.

## FormSet#isMultipart

### Description
Returns `true` if the formset needs to be multipart-encoded, i.e. it has a `FileInput()`. Otherwise, `false`.

### Method
FormSet.isMultipart

### Parameters
None
```

--------------------------------

### Configure extra forms

Source: https://newforms.readthedocs.io/en/latest/formsets.html

Use the extra parameter to specify the number of blank forms to display by default.

```javascript
var ArticleFormSet = forms.FormSet.extend({form: ArticleForm, extra: 2})
```

--------------------------------

### Creating Custom Fields

Source: https://newforms.readthedocs.io/en/latest/fields.html

Instructions for extending the base Field class to implement custom form field logic.

```APIDOC
## Creating custom fields

### Description
To create a custom field, extend the base Field class.

### Requirements
- Implement a clean() method.
- The constructor() must accept core arguments: required, label, initial, widget, and helpText in an argument object.
```

--------------------------------

### Namespace Forms with Prefixes

Source: https://newforms.readthedocs.io/en/latest/forms.html

Use the prefix argument to distinguish fields when multiple forms are rendered in the same container.

```javascript
var mother = new PersonForm({prefix: 'mother'})
var father = new PersonForm({prefix: 'father'})
print(reactHTML(<RenderForm form={mother}/>))
/* =>
<div>
  <div><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name"></div>
  <div><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name"></div>
</div>
*/
print(reactHTML(<RenderForm form={father}/>))
/* =>
<div>
  <div><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name"></div>
  <div><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name"></div>
</div>
*/
```

--------------------------------

### FormSet.extend

Source: https://newforms.readthedocs.io/en/latest/formsets_api.html

Creates a new constructor which inherits from FormSet.

```APIDOC
## FormSet.extend

### Description
Creates a new constructor which inherits from FormSet, allowing for pre-configuration of prototype properties.

### Parameters
#### Request Body
- **prototypeProps** (Object) - Required - Default FormSet options and other prototype properties.
- **constructorProps** (Object) - Optional - Properties to be set directly on the new constructor function.
```

--------------------------------

### Access Form Instance for Submission

Source: https://newforms.readthedocs.io/en/latest/react_components.html

Use the ref prop to access the form instance via getForm() for validation during submission.

```javascript
render: function() {
  return <form onSubmit={this._onSubmit}>
    <forms.RenderForm form={MyForm} ref="myForm"/>
    <button>Submit</button>
  </form>
},

_onSubmit: function(e) {
  e.preventDefault()
  var form = this.refs.form.getForm()
  var isValid = form.validate()
  if (isValid) {
    // ..
  }
}
```

--------------------------------

### Create a formset class

Source: https://newforms.readthedocs.io/en/latest/formsets.html

Extend FormSet to create a collection of forms based on a base form class.

```javascript
var ArticleFormSet = forms.FormSet.extend({form: ArticleForm})
```

--------------------------------

### BoundField#render

Source: https://newforms.readthedocs.io/en/latest/boundfield_api.html

Default rendering method for the field, optionally including a hidden initial version.

```APIDOC
## BoundField#render

### Description
Default rendering method - if the field has `showHiddenInitial` set, renders the default widget and a hidden version, otherwise just renders the default widget for the field.

### Method
N/A (Method of BoundField class)

### Parameters
#### Arguments
- **kwargs** (Object) - Widget options as per `BoundField#asWidget()`.
```

--------------------------------

### Render Widget with BoundField

Source: https://newforms.readthedocs.io/en/latest/custom_display.html

The default `render()` method for a non-hidden BoundField calls `asWidget()`, which renders the Widget configured for the field. This is the standard way to display a field's input element.

```python
asWidget()
```

--------------------------------

### PasswordInput Widget

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Documentation for the PasswordInput widget, which renders a password input field.

```APIDOC
## PasswordInput()

### Description
Password input: <input type='password' ...>

### Parameters
#### Request Body
- **renderValue** (boolean) - Optional - Determines whether the widget will have a value filled in when the form is re-displayed after a validation error (default is false).
```

--------------------------------

### Initialize Form with onChange Callback

Source: https://newforms.readthedocs.io/en/latest/react_client.html

Initialize a newforms Form instance with an `onChange` callback. This callback is crucial for updating the React component's state and re-rendering the form when user input changes or validation occurs.

```javascript
getInitialState: function() {
  return {
    form: new ContactForm({onChange: this.onFormChange})
  }
},

onFormChange: function() {
  this.forceUpdate()
}
```

--------------------------------

### util.makeChoices

Source: https://newforms.readthedocs.io/en/latest/util_api.html

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

```APIDOC
## util.makeChoices(list, submitValueProp, displayValueProp)

### Description
Generates a list of choice pairs (submitValue, displayValue) from an array of objects.

### Arguments
* **list** (Array) - A list of objects.
* **submitValueProp** (String) - The property name for the submit value.
* **displayValueProp** (String) - The property name for the display value.

### Returns
* Array - An array of [submitValue, displayValue] pairs.
```

--------------------------------

### Render RadioSelect as a list

Source: https://newforms.readthedocs.io/en/latest/widgets.html

Default markup structure for a RadioSelect widget.

```html
<ul>
  <li><input type='radio' ...></li>
  ...
</ul>
```

--------------------------------

### Widget Class API

Source: https://newforms.readthedocs.io/en/latest/widgets_api.html

Documentation for the base Widget class used for rendering HTML form elements.

```APIDOC
## Widget Class

### Description
The base class for all HTML form widgets. It handles the rendering of HTML and the extraction of data from objects.

### Constructor
`new Widget(kwargs)`
- **kwargs.attrs** (Object) - Optional - HTML attributes for the rendered widget.

### Instance Properties
- **attrs** (Object) - Base HTML attributes for the rendered widget.

### Prototype Properties
- **isHidden** (Boolean) - Determines whether this corresponds to an <input type="hidden">
- **needsMultipartForm** (Boolean) - Determines whether this widget needs a multipart-encoded form
- **needsInitialValue** (Boolean) - Determines whether this widget’s render logic always needs to use the initial value
- **isRequired** (Boolean) - Determines whether this widget is for a required field

### Prototype Functions
- **render(name, value, kwargs)**
  - **name** (String) - The name for the rendered widget.
  - **value** (Any) - The value to be displayed.
  - **kwargs.attrs** (Object) - Additional HTML attributes.
  - **kwargs.controlled** (Boolean) - True if the widget should render a controlled component.
  - **kwargs.initialValue** (Any) - Initial value if needsInitialValue is true.
- **subWidgets(name, value, kwargs)** - Yields all subwidgets of this widget.
- **buildAttrs(kwargAttrs, renderAttrs)** - Helper for building HTML attributes.
- **valueFromData(data, files, name)** - Retrieves a value for this widget from form data.
- **idForLabel(id)** - Determines the HTML id attribute for a label.
```

--------------------------------

### Form Prefix Methods

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

Methods for managing field name prefixes within a form.

```APIDOC
## Form#addPrefix

### Description
Adds a prefix to the given field name if the form has a prefix set.

### Parameters
- **fieldName** (string) - Required - The field name to prefix.

## Form#removePrefix

### Description
Removes the prefix from the start of a field name if it exists.

### Parameters
- **fieldName** (string) - Required - The field name to process.
```

--------------------------------

### Form.extend

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

Creates a new constructor that inherits from the Form class, allowing for custom field definitions and prototype properties.

```APIDOC
## Form.extend

### Description
Creates a new constructor which inherits from Form. This is the entry point for defining custom forms.

### Parameters
- **prototypeProps** (Object) - Required - Form fields and other prototype properties such as custom constructors and validation methods.
- **constructorProps** (Object) - Optional - Properties to be set directly on the new constructor function.
```

--------------------------------

### Numeric Fields

Source: https://newforms.readthedocs.io/en/latest/fields_api.html

Documentation for IntegerField, FloatField, and DecimalField classes.

```APIDOC
## Numeric Fields

### IntegerField
- **maxValue** (Number) - Optional - Maximum valid value.
- **minValue** (Number) - Optional - Minimum valid value.

### FloatField
- **maxValue** (Number) - Optional - Maximum valid value.
- **minValue** (Number) - Optional - Minimum valid value.

### DecimalField
- **maxValue** (Number) - Optional - Maximum valid value.
- **minValue** (Number) - Optional - Minimum valid value.
- **maxDigits** (Number) - Optional - Maximum number of digits.
- **decimalPlaces** (Number) - Optional - Maximum number of decimal places.
```

--------------------------------

### Form Class API

Source: https://newforms.readthedocs.io/en/latest/forms_api.html

Details on the `Form` class, its methods, and attributes.

```APIDOC
## `Form` Class

### Description
The `Form` class is the foundation for creating forms. It handles data binding, validation, and rendering.

### Methods

*   **`__init__(self, data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=ErrorList, label_suffix=':', empty_permitted=False, instance=None)`**: Initializes a form instance.
*   **`is_valid(self)`**: Returns `True` if all validation checks pass.
*   **`clean(self)`**: Cleans and validates all fields. Returns the cleaned data.
*   **`save(self)`**: Saves the form data (implementation depends on the form type).

### Attributes

*   **`fields`**: A dictionary of all fields in the form.
*   **`cleaned_data`**: A dictionary containing the cleaned data after validation.
*   **`errors`**: A dictionary containing validation errors.
```
Tokens:
Raw