Form

Wrapper around react-final-form with some extensions

1) You can pass a record to `initialValues` and it will pass through the underlying data to the form

2) final-form expects a function as a child which you then render a `<form>` element with and pass through
   handleSubmit. Most the time this is the same thing so you optionally just pass through renderable
   children and the form will be created implicitly for you.


props

FormProps

ReactElement

FormValues

constructor

new Field

values

Field

__fieldValueType

ValueT

__parsableValueType

ParsableValueT

_defaultValue

null

__type

_model

ViewModelConstructor

_name

string

asyncChoices

AsyncChoicesInterface

SingleValueT

Is this field required when saving a record?

blank

boolean

If true an empty string value should be converted to a null value

blankAsNull

choices

Help text that can be displayed with the form widget

helpText

undefined

Label that can be displayed as the form label for a widget

If not specified will be generated from `name`.


label

Indicates this field should only be read, not written. Not enforced but can be used by components to adjust their
output accordingly (eg. exclude it from a form or show it on a form with a read only input)

readOnly

Indicates this field should only be written only and is not intended to be read directly. This is not enforced
but can be used by components to adjust their output accordingly (eg. exclude it from a detail view on a record)

writeOnly

This exists so things like [getWidgetForField](doc:getWidgetForField) can select a widget for
a field without needing to import all fields up front.

For custom fields this isn't required unless your implementation of `getWidgetForField` wants
to do avoid importing the field up front.


fieldClassName

When accessed on a [bound field](doc:viewModelFactory#var-_f) will return the current instance of the ViewModel
the field is bound to.

If called on an unbound field then this will always be undefined and a warning will be raised.


__get

boundRecord

defaultValue

Returns true if field is bound to a ViewModel instance. When a field is bound to a instance
the value for that field is accessible on the 'value' property.

isBound

The [ViewModel](doc:viewModelFactory) class this field is attached to.

This will throw an error if the field is not attached to a model.


model

__set

viewModel

void

name

When `isBound` is true this will return the current value of this field on the bound ViewModel.
Otherwise will always be undefined.

value

clone

Returns a clone of the field that should be functionally equivalent

contributeToClass

Called once after fields are attached to a ViewModel. This occurs the first time `.fields` is
accessed on the ViewModel.

By default this does nothing but can be used by fields to attach extra properties or validate
against the final view model (for example checking that another field does / does not exist).

NOTE: This is called for every distinct ViewModel class; so if class A is extended by class B
then it will be called on both A and B.


format

Format the value for displaying in a form widget. eg. This could convert a `Date` into
a localized date string

isEqual

This is used when determining if two records are equal (see ViewModel.isEqual)


value1

value2

normalize

Normalize a value passed into a ViewModel constructor. This could do things like extract the id of a nested
relation and only store that, eg.

TODO: Do we need to handle things like normalizing to multiple fields? eg. In the example below setting the
id to addressId and relation to address

```js
// This might become
{
    name: 'Sam',
    address: {
        id: 5,
        formatted: '3 Somewhere Road, Some Place',
    },
}
// ...this
{
    name: 'Same',
    address: 5,
}
```


parse

Parse a value received from a form widget `onChange` call. eg. This could convert a localized date string
into a `Date`.

toJS

Convert value to plain JS representation useful for things like passing to a form or posting to
a backend API

toString

RecordBoundField

NumberField

ListField

BaseRelatedViewModelField

NullableBooleanField

CharField

DateField

RangeField

DateTimeField

FileField

TimeField

TestField

Constructors

Properties

Accessors

Methods

__call

FieldProps

number

Promise

ViewModelInterface

Field.__constructor

new RecordBoundField

Field.__fieldValueType

Field.__parsableValueType

ParsableType

Field._defaultValue

Field.asyncChoices

Field.blank

Field.blankAsNull

Field.boundRecord

Field.choices

Field.helpText

Field.isBound

true

Field.label

Field.readOnly

Field.value

Field.writeOnly

Field.fieldClassName

Field.defaultValue

Field.model

Field.name

Field.clone

Field.contributeToClass

Field.format

Field.isEqual

Field.normalize

Field.parse

Field.toJS

Field.toString

new NumberField

maxValue

minValue

Other numeric fields (IntegerField, DecimalField, FloatField...) will extend this.


DecimalField

FloatField

IntegerField

NumberFieldProps

Variables

new ListField

__namedParameters

childField

Calls `childField.format` on each entry in the passed array

Calls `childField.parse` on each entry in the passed array

If `value` is falsy or an empty array and `blankAsNull` is true
it will return `null` or if `blankAsNull` is false then it
will return an empty array.


You must pass `childField` which is the underlying field for each value in the
list. `ListField` will call `format`, `parse`, and `normalize` on this field for
each value in the list.

By default `defaultValue` will be set to an empty array unless `blankAsNull` is
`true` in which case it will be set to `null`. `normalize` and `parse` also behave
in the same way (a falsy value passed to these will either return an empty array
when `blankAsNull` is false or null when it is true).

```js
const listOfInts = new ListField({ childField: new IntegerField() });
```


new BaseRelatedViewModelField

BaseRelatedViewModelValueType

TargetViewModelT

FieldValueT

RelatedViewModelParsableType

_isResolvingDeps

_loadTo

_resolvedTo

_resolvingTo

sourceField

sourceFieldName

many

Get the [ViewModel](doc:viewModelFactory) this related field is to.

If `to` was defined as a function returning a `Promise` then you must call `resolveViewModel`
and wait for the returned `Promise` to resolve before accessing this otherwise an error will be thrown


Compares to relations for equality - if the ViewModel has the same data this returns true

resolveViewModel

Resolves the ViewModel this field links to. This is necessary as the ViewModel might be a dynamic
import that hasn't yet loaded.

This needs to be called manually before `to` can be accessed.


We split into RelatedViewModelField (for single records) and ManyRelatedViewModelField (for multiple records)
mainly to making typing easier.

Use `ManyRelatedViewModelField` if `sourceFieldName` refers to a `ListField` otherwise `RelatedViewModelField`.


RelatedViewModelField

ManyRelatedViewModelField

RelatedViewModelFieldProps

BaseRelatedViewModelField.__constructor

new RelatedViewModelField

RelatedViewModelValueType

FieldDataMappingRaw

BaseRelatedViewModelField._isResolvingDeps

BaseRelatedViewModelField.sourceField

BaseRelatedViewModelField.sourceFieldName

BaseRelatedViewModelField.many

BaseRelatedViewModelField.to

BaseRelatedViewModelField.contributeToClass

BaseRelatedViewModelField.isEqual

Converts a value into the relations [ViewModel](doc:viewModelFactory) instance.

BaseRelatedViewModelField.resolveViewModel

Converts the linked record to a plain javascript object

Record

Define a field that references another ViewModel

This requires two things:

1) The ViewModel to reference
2) The field on the source ViewModel that contains the ID for the relation

In the following example `User` has a `Group` as a relation. The id for the
connected group is stored on the `groupId` field:

```js
class Group extends viewModelFactory({
  name: new CharField(),
}) {}
class User extends viewModelFactory({
  name: new CharField(),
  groupId: new IntegerField(),
  group: new RelatedViewModelField({
    to: Group,
    sourceFieldName: 'groupId',
  }),
}) {}
```

You can then fetch the data - including the relations - from the cache:

```js
Group.cache.add({ id: 1, name: 'Staff' });
User.cache.add({ id: 1, name: 'Bob', groupId: 1 });
User.cache.get(['name', 'group']);
// { id: 1, name: 'Bob', groupId: 1, group: { id: 1, name: 'Staff' }}
```

The `to` field can also be a function to support circular references:

```js
class Group extends viewModelFactory({
  name: new CharField(),
  ownerId: new IntegerField(),
  owner: new RelatedViewModelField({
    to: () => User,
    sourceFieldName: 'ownerId',
  }),
}) {}
class User extends viewModelFactory({
  name: new CharField(),
  groupId: new IntegerField(),
  group: new RelatedViewModelField({
    to: Group,
    sourceFieldName: 'groupId',
  }),
}) {}
```

You can query the circular relations as deep as you want:

```js
Group.cache.add({ id: 1, name: 'Staff', ownerId: 1 });
User.cache.add({ id: 1, name: 'Bob', groupId: 1 });
User.cache.get(['name', 'group', ['group', 'owner'], ['group', 'owner', 'group']);
// {
//   id: 1,
//   name: 'Bob',
//   groupId: 1,
//   group: {
//     id: 1,
//     name: 'Staff',
//     ownerId: 1,
//     owner: {
//       id: 1,
//       name: 'Bob',
//       groupId: 1,
//       group: {
//         id: 1,
//         name: 'Staff',
//         ownerId: 1,
//       }
//     },
//   },
// }
```

`to` can also be a a function that returns a Promise. This is useful to
lazy load modules:

```js
class Subscription extends viewModelFactory({
  userId: new IntegerField(),
  user: new RelatedViewModelField({
      sourceFieldName: 'userId',
      to: async () => {
        const User = await import('./User').default;
        return User;
      }
  })
}) {}
```

**NOTE:** When you return a promise you have to call `resolveViewModel` on
that field before it's usable:

```js
await Subscription.fields.user.resolveViewModel()
```

Failure to do this will result in an error being thrown the first time it's accessed.

If you have multiple values use [ManyRelatedViewModelField](doc:ManyRelatedViewModelField) instead.


new ManyRelatedViewModelField

Define a field that contains multiple records from another ViewModel

This behaves the same as [RelatedViewModelField](doc:RelatedViewModelField) but `sourceFieldName`
must refer to a [ListField](doc:ListField) and all values are an array instead of a single value.


new RecordPointer

currentCachedValue

record

RecordPointer

This is the value that was replaced by this pointer in the cache. When we actually clone
the record we compare against this value - if it's the same we return the original object
so that equality checks still hold. This is because we never return the RecordPointer - we
only resolve the underlying value as is required. In order to determine whether or not
an object is the same requires first cloning it and then comparing it. As such we do that
at the time we need the cloned value, not upfront (ie. we don't do it before we store the
RecordPointer as that would be lower than doing it lazily - especially if you are updating
lots of records)

currentCachedRecord

InstanceType

ViewModelClassType

fieldNames

PartialViewModel

Points to a record that is cached already. The purpose of this is to have a single object
in memory and only clone it as needed (eg. a single instance of the RecordPointer is stored
on multiple other cache keys). We could do it by storing the record directly but we'd then
have to check if the _assignedFields is what we expect and then clone - it's easier and faster
to just check if it's an instanceof RecordPointer

	Parameter	Type	Description
*	props		Any of the final-form FormProps and the options shown below
	props.formProps	Record	Any extra props to pass through to the underlying form component. The form component used is determined by the `formComponent` passed to UiProvider or `form` if none is passed. Note that this only applies if you pass `children` to `Form`. If you use `render` or `component` then it is ignored.
	props.initialValues	FormValues\|ViewModel	Initial values for the form. Either an object or a `ViewModel` record.