Class: OptionsForm

qui.forms.commonforms.OptionsForm(page, …args)

A form ready to be used with qui.pages.PageMixin#makeOptionsBarContent.

Constructor

new OptionsForm(page, …args)

Parameters:
Name Type Attributes Description
page qui.pages.PageMixin

the page associated to this options form
args * <repeatable>

parent class parameters
Source:

Extends

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
Overrides:
Source:

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
Overrides:
Source:

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
Overrides:
Source:
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
Overrides:
Source:
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.

Overrides:
Source:

clearApplied()

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

Overrides:
Source:

close()

Close the form.

Overrides:
Source:

defaultAction()

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

Overrides:
Source:

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

Return the form button with the given id.

Parameters:
Name Type Description
id String

the button id
Overrides:
Source:
Returns:
Type
qui.forms.FormButton

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

Return all form buttons.

Overrides:
Source:
Returns:
Type
Array.<qui.forms.FormButton>

getChangedFieldNames() → {Array.<String>}

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

Overrides:
Source:
Returns:
Type
Array.<String>

getData() → {Promise}

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

Overrides:
Source:
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
Overrides:
Source:
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
Overrides:
Source:
Returns:
Type
Number

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

Return the list of all fields.

Overrides:
Source:
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.

Overrides:
Source:
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.<*>

getPage() → {qui.pages.PageMixin}

Return the associated page

Source:
Returns:
Type
qui.pages.PageMixin

getUnvalidatedData() → {Object}

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

Overrides:
Source:
Returns:

a dictionary with field values

Type
Object

getUnvalidatedFieldValue() → (nullable) {*}

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

Overrides:
Source:
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).

Overrides:
Source:
Returns:
Type
Boolean

isCompact() → {Boolean}

Tell if the form uses the compact layout.

Overrides:
Source:
Returns:
Type
Boolean

onButtonPress(button)

Called when one of the form buttons is pressed.

Parameters:
Name Type Description
button qui.forms.FormButton
Overrides:
Source:

onCancel()

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

Overrides:
Source:

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
Overrides:
Source:

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
Overrides:
Source:

onInvalid()

Called when the form data becomes invalid.

Overrides:
Source:

onOptionsBarOpenClose(opened)

Called when the options bar is opened or closed with this form.

Parameters:
Name Type Description
opened Boolean

true if opened, false otherwise
Source:

onValid(data)

Called when the form data becomes valid.

Parameters:
Name Type Description
data Object

the form data
Overrides:
Source:

proceed() → {Promise}

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

Overrides:
Source:
Returns:
Type
Promise

removeButton(id)

Remove a button from the form.

Parameters:
Name Type Description
id String

the button id
Overrides:
Source:

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
Overrides:
Source:

setApplied()

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

Overrides:
Source:

setData(data)

Update the form data.

Parameters:
Name Type Description
data Object

the new form data
Overrides:
Source:

updateButtonsState()

Update internal form state related to buttons.

Overrides:
Source:

updateFieldsState()

Update internal form state related to fields.

Overrides:
Source:

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.
Overrides:
Source:
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.

Overrides:
Source:

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
Overrides:
Source:
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
Overrides:
Source:
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>