Field

import { Field } from "@prestojs/viewmodel";

Base Field

API

Constructor

new Field(values)

Parameter	Type	Description
values.asyncChoices	AsyncChoicesInterface	Asynchronous choices for this field. Only one of `asyncChoices` and `choices` should be passed.
values.blank	boolean	Is this field allowed to be assigned a blank (null, undefined, "") value? Defaults to false
values.blankAsNull	boolean	Frontend values are often stored as strings even if they are not stored like that in a backend (eg. database). Depending on your backend implementation it may expect empty values to be represented as `null` rather than an empty string. Setting `blankAsNull` to `true` indicates that empty strings should be converted to `null` when being sent to the backend.
values.choices	Map\|[SingleValueT, string][]	Choices for this field. Should be a mapping of value to the label for the choice.
values.defaultValue	ValueT\|null\| Function	Default value for this field. This can either be a function that returns a value or the value directly.
values.helpText	string	Optional help text for this field that might be shown on a form
values.label	string	Label for this field. If not specified will be generated from the name.
values.readOnly	boolean	True if field should be considered read only (eg. excluded from forms)
values.writeOnly	boolean	True if field should be considered write only (eg. excluded from detail views)

Methods

clone()

Source

Returns a clone of the field that should be functionally equivalent

Returns

Field

contributeToClass(viewModel)

Source

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.

	Parameter	Type	Description
*	viewModel	ViewModel Class

Returns

void

format(value)

Source

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

	Parameter	Type	Description
*	value	ValueT

Returns

any

isEqual(value1,value2)

Source

Should two values be considered equal?

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

	Parameter	Type	Description
*	value1	ValueT
*	value2	ValueT

Returns

boolean

normalize(value)

Source

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

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

	Parameter	Type	Description
*	value	ParsableValueT

Returns

One of the following:

ValueT

null

parse(value)

Source

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

	Parameter	Type	Description
*	value	ParsableValueT\|null

Returns

One of the following:

ValueT

null

toJS(value)

Source

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

	Parameter	Type	Description
*	value	ValueT

Returns

One of the following:

string

number

null

__type

toString()

Source

Returns

string

Properties

asyncChoices: AsyncChoicesInterface

Async choices for this field.

blank: boolean

Is this field required when saving a record?

blankAsNull: boolean

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

boundRecord: ViewModelInterface

When accessed on a bound field 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.

choices: Map

defaultValue: Promise<ValueT|null|undefined>|ValueT|null|undefined

Get the default value for this field.

helpText: string

Help text that can be displayed with the form widget

isBound: boolean

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.

label: string

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

If not specified will be generated from name.

model: ViewModel Class

The ViewModel class this field is attached to.

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

name: string

The name of this field.

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

readOnly: boolean

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)

value: ValueT

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

writeOnly: boolean

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)

Static Properties

fieldClassName: string|null

Field class name

This exists so things like 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.