JSDoc: Class: Form

Constructor

new Form(widthopt, noBackgroundopt, compactopt, valuesWidthopt, continuousValidationopt, closeOnApplyopt, autoDisableDefaultButtonopt, fieldsopt, buttonsopt, initialDataopt, …args)

Parameters:

Name	Type	Attributes	Description
`width`	Number \| String	<optional>	a specific form width to be used instead of the default
`noBackground`	Boolean	<optional>	indicates that the form should have transparent background (defaults to `false`)
`compact`	Boolean	<optional>	indicates that the form should be compact to better fit in smaller containers; compact forms have field labels and values on separate lines, to reduce the overall form width (defaults to `false`)
`valuesWidth`	Number	<optional>	sets the width of the values column, as percent, relative to the form body; when set to `0` the width of each field's value will be computed automatically; this attribute is ignored for forms that have `compact` set to `true` (defaults to `60`)
`continuousValidation`	Boolean	<optional>	if set to `true`, each field will be validated upon change, instead of when the form data is applied (using `qui.forms.Form#applyData`). Defaults to `false`
`closeOnApply`	Boolean	<optional>	if set to `false`, the form will not automatically close when data is applied (using `qui.forms.Form#applyData`). Defaults to `true`
`autoDisableDefaultButton`	Boolean	<optional>	controls if the default button is automatically enabled and disabled based on currently changed fields, their validity and applied state. Defaults to `true`
`fields`	Array.<qui.forms.FormField>	<optional>	fields to be added to the form
`buttons`	Array.<qui.forms.FormButton>	<optional>	buttons to be added to the form
`initialData`	Object	<optional>	a dictionary with initial values for the fields
`args`	*	<repeatable>	parent class parameters

Mixes In:

Source:

forms/form.js, line 28

Methods

addButton(index, button)

Add a button to the form.

Parameters:

Name	Type	Description
`index`	Number	the index where the button should be added; `-1` will add the button at the end
`button`	qui.forms.FormButton	the button

Source:

forms/form.js, line 216

addField(index, field)

Add a field to the form.

Parameters:

Name	Type	Description
`index`	Number	the index where the field should be added; `-1` will add the field at the end
`field`	qui.forms.FormField	the field

Source:

forms/form.js, line 313

applyData(data) → (nullable) {Promise.<*, Error>}

A function that applies the form data.

If null or undefined is returned, the form data is considered applied right away. If a promise is returned, data is considered applied when the promise is resolved and qui.forms.Form#setApplied is called to mark the form as applied.

A rejected promise will set a form error using qui.views.ViewMixin#setError. To set field errors, reject the returned promise with a qui.forms.ErrorMapping. A null error will simply cancel the application, without setting any error.

Form will be put in progress using qui.views.ViewMixin#setProgress while promise is active.

Parameters:

Name	Type	Description
`data`	Object	form data to be applied

Source:

forms/form.js, line 879

Throws:

Error errors while applying the data can also be thrown

Returns:

Type: Promise.<*, Error>

applyField(value, fieldName) → (nullable) {Promise.<*, Error>}

Implement this method to define how a field value is applied when it changes. This method can be used to implement continuous form saving, eliminating the need of a general form save button.

For continuous form saving to work, the form attribute continuousValidation must be set to true.

If a promise is returned, value is considered applied when the promise is resolved and qui.forms.Form#setApplied is called to mark the form as applied. A rejected promise will set a field error using qui.views.ViewMixin#setError.

The field will be put in progress using qui.views.ViewMixin#setProgress while promise is active.

Returning null or undefined indicates that values cannot be applied continuously for the given field (this is the default behaviour).

Parameters:

Name	Type	Description
`value`	*	the validated field value
`fieldName`	String	the name of the field that was changed

Source:

forms/form.js, line 908

Throws:

Error errors in applying the value can also be thrown

Returns:

Type: Promise.<*, Error>

cancelAction()

Execute the cancel form action. By default this is qui.forms.Form#close.

Source:

forms/form.js, line 1088

clearApplied()

Put the form in the normal state, but only if the current state is qui.forms.STATE_APPLIED.

Source:

forms/form.js, line 1014

close()

Close the form.

Source:

forms/form.js, line 1172

defaultAction()

Execute the default form action. By default this is qui.forms.Form#proceed.

Source:

forms/form.js, line 1081

getButton(id) → (nullable) {qui.forms.FormButton}

Return the form button with the given id.

Parameters:

Name	Type	Description
`id`	String	the button id

Source:

forms/form.js, line 257

Returns:

Type: qui.forms.FormButton

getButtons() → {Array.<qui.forms.FormButton>}

Return all form buttons.

Source:

forms/form.js, line 268

Returns:

Type: Array.<qui.forms.FormButton>

getChangedFieldNames() → {Array.<String>}

Return the names of the fields whose values have been changed.

Source:

forms/form.js, line 825

Returns:

Type: Array.<String>

getData() → {Promise}

Return the current form data in a promise, after making sure it is valid.

Source:

forms/form.js, line 781

Returns:

a promise that is resolved with a dictionary of field values, if the form is valid, and is rejected with a dictionary of errors associated to invalid fields, if the form is invalid

Type: Promise

getField(name) → (nullable) {qui.forms.FormField}

Return the field with a given name. If no such field is found, null is returned.

Parameters:

Name	Type	Description
`name`	String	the name of the field

Source:

forms/form.js, line 382

Returns:

Type: qui.forms.FormField

getFieldIndex(field) → {Number}

Return the index of the given field. If the field does not belong to this form, -1 is returned.

Parameters:

Name	Type	Description
`field`	qui.forms.FormField \| String	the field or a field name

Source:

forms/form.js, line 394

Returns:

Type: Number

getFields() → {Array.<qui.forms.FormField>}

Return the list of all fields.

Source:

forms/form.js, line 410

Returns:

Type: Array.<qui.forms.FormField>

getFieldValue() → {Promise.<*>}

Return the current value of a field, in a promise, after making sure the entire form is valid.

Source:

forms/form.js, line 757

Returns:

a promise that is resolved with the field value, if the form is valid, and is rejected, if the form is invalid

Type: Promise.<*>

getUnvalidatedData() → {Object}

Return the current form data without validating fields or the form.

Source:

forms/form.js, line 789

Returns:

a dictionary with field values

Type: Object

getUnvalidatedFieldValue() → (nullable) {*}

Return the current value of a field without performing any validation.

Source:

forms/form.js, line 767

Returns:

the current field value or null if no such field is found

Type: *

isApplied() → {Boolean}

Tell if the form data has been applied (and thus there are no pending changes).

Source:

forms/form.js, line 1024

Returns:

Type: Boolean

isCompact() → {Boolean}

Tell if the form uses the compact layout.

Source:

forms/form.js, line 95

Returns:

Type: Boolean

onButtonPress(button)

Called when one of the form buttons is pressed.

Parameters:

Name	Type	Description
`button`	qui.forms.FormButton

Source:

forms/form.js, line 276

onCancel()

Called when the user closes the form without applying the data.

Source:

forms/form.js, line 885

onChange(data, fieldName)

Called whenever a field value changes.

Parameters:

Name	Type	Description
`data`	Object	the unvalidated form data
`fieldName`	String	the name of the field that was changed

Source:

forms/form.js, line 834

onChangeValid(data, fieldName)

Called whenever a field value changes and the form is entirely valid. This method is only called for forms with continuousValidation set to true.

Parameters:

Name	Type	Description
`data`	Object	the validated form data
`fieldName`	String	the name of the field that was changed

Source:

forms/form.js, line 843

onInvalid()

Called when the form data becomes invalid.

Source:

forms/form.js, line 856

onValid(data)

Called when the form data becomes valid.

Parameters:

Name	Type	Description
`data`	Object	the form data

Source:

forms/form.js, line 850

proceed() → {Promise}

Run the form by gathering, validating and applying form data.

Source:

forms/form.js, line 1096

Returns:

Type: Promise

removeButton(id)

Remove a button from the form.

Parameters:

Name	Type	Description
`id`	String	the button id

Source:

forms/form.js, line 237

removeField(nameOrField)

Remove a field from the form.

Parameters:

Name	Type	Description
`nameOrField`	String \| qui.forms.FormField	the name of the field or a field object

Source:

forms/form.js, line 345

setApplied()

Put the form in the applied state. The view state is set to qui.forms.STATE_APPLIED.

Source:

forms/form.js, line 1007

setData(data)

Update the form data.

Parameters:

Name	Type	Description
`data`	Object	the new form data

Source:

forms/form.js, line 799

updateButtonsState()

Update internal form state related to buttons.

Source:

forms/form.js, line 282

updateFieldsState()

Update internal form state related to fields.

Source:

forms/form.js, line 417

updateValidationState(extraErrorsopt) → {Promise.<Object>}

Used for continuous validation. Runs a "background" validation to:

show possible field/form errors
update internal validity state
enable/disable default form button

Parameters:

Name	Type	Attributes	Default	Description
`extraErrors`	Object.<String, Error>	<optional>	null	a dictionary containing any extra field errors that should be considered in addition to those returned by the validation mechanism.

Source:

forms/form.js, line 676

Returns:

a promise that is resolved with form data, if the form is valid (the promise is never rejected)

Type: Promise.<Object>

updateValidationStateASAP()

Calls qui.forms.Form#updateValidationState asap, preventing multiple unnecessary successive calls.

Source:

forms/form.js, line 739

validate(data) → (nullable) {Promise.<*, qui.forms.ValidationError>}

Tell if given form data is valid as a whole or not. This method is called only with valid field data. Override this method to implement custom form validation.

Parameters:

Name	Type	Description
`data`	Object	the form data to validate

Source:

forms/form.js, line 648

Throws:

qui.forms.ValidationError the validation error can also be thrown instead of being returned in a rejected promise

Returns:

null or a resolved promise, if the data is valid; a promise rejected with a validation error otherwise;

Type: Promise.<*, qui.forms.ValidationError>

validateField(name, value, data) → (nullable) {Promise.<*, qui.forms.ValidationError>}

Override this method to implement custom field validation in the context of this form.

Parameters:

Name	Type	Description
`name`	String	the field name
`value`	*	the field value to validate
`data`	Object	the form unvalidated data

Source:

forms/form.js, line 662

Throws:

qui.forms.ValidationError the validation error can also be thrown instead of being returned in a rejected response

Returns:

null or a resolved promise, if the value is valid; a promise rejected with a validation error otherwise;

Type: Promise.<*, qui.forms.ValidationError>