Field

The configuration for additional items associated to this field. This is typically used to add contextual fields related to a checkbox or radio button. See these classes for examples of nested fields.

This config can be provided as an array of widget config objects, an object with named widgets (see namedItems, or a config object for the whole field container.

To determine if the object is a namedItems object or a field container config, the object is checked for either a type or an items property. If it has either of these properties, it is a field container config object. Configuring the container is useful for applying classes or styles to the container as a whole.

For example, to add named items:

 new Checkbox({
     text : 'Separate shipping address',
     container : {
         address1 : {
             type : 'textfield'
         },
         address2 : {
             type : 'textfield'
         }
     }
 });

To style the container as well, move the items to the items property and add cls:

 new Checkbox({
     text : 'Separate shipping address',
     container : {
         cls   : 'address-form',
         items : {
             address1 : {
                 type : 'textfield'
             },
             address2 : {
                 type : 'textfield'
             }
         }
     }
 });

The config controls how the value of nested items are handled when a parent container gets or sets its values.

The valid values for this config are:

• null (the default) will include the values of this field's items if this field stores its own value.
• true to always include the values of this field's items.
• false to never include the values of this field's items.
• 'nested' to include the values of this field's items as a nested object under the field's name. This field's value is stored as the 'value' property of that object.
• Any other string is treated as the name of a property on this field. When truthy, the values of this field's items will be included.
• A function can be supplied that must return a value given this field as its sole argument. If that value is truthy, this field's items will be included.

Set this config to true to always display items horizontally along with this field. This assigns an hbox as the layout to the container.

Alternatively, set this config to false to wrap this field's items below. This assigns a VBox as the layout to the container.

This config defaults to true if there is exactly one item, and false otherwise.

Sets the native autocomplete property of the underlying input element. For more information, please refer to MDN

Text alignment for the input field.

Sets custom attributes of the underlying input element. For more information, please refer to MDN

If you need to use something else than a default input element, as the input element, provide the tag name here. Please note that this is used for advanced usage only, for example when using WebComponents (custom elements), and that the configured element must fulfil the same contract as a regular input element.

Sets the type attribute of the underlying input element (password, hidden, date, color, etc.).

The width to apply to the .b-field-inner element, which encompasses the input element and any triggers. If a number is specified, px will be used.

Sets the native spellcheck property of the underlying input element. For more information, please refer to MDN

The tab index of the input field or fields, or null for natural tab order (recommended). Setting to 0 is equivalent to natural tab order, but is unnecessary for fields since they are naturally tabbable (i.e., accessible via the TAB key). Setting to -1 disables tabbability but allows for focus to be set to the element programmatically.

From MDN documentation:

Warning: You are recommended to only use 0 and -1 as tabindex values. Avoid using tabindex values greater than 0 and CSS properties that can change the order of focusable HTML elements (Ordering flex items). Doing so makes it difficult for people who rely on using keyboard for navigation or assistive technology to navigate and operate page content. Instead, write the document with the elements in a logical sequence.

Set to false to not highlight a field as invalid while typing, to instead show it on ENTER key press or similar.

An optional string to display inside the input field as an overlay. This can be useful for displaying a field's units.

This config is ignored if hintHtml is set.

For example:

 {
     type  : 'numberfield',
     label : 'Temperature',
     hint  : '°C'
 }

This config can be set to a function to dynamically generate the hint text:

 {
     type  : 'numberfield',
     label : 'Duration',
     hint  : ({ value }) => (value === 1) ? 'Day' : 'Days'
 }

The function is passed an object with the following properties:

• source A reference to the field instance.
• value The current value of the field.

A hint function will be called when the field changes value.

This config is similar to hint except that this config is used to display HTML content. Since this can allow malicious content to be executed, be sure not to include user-entered data or to encode such data (see encodeHtml).

If this config is set, hint is ignored.

For example:

 {
     type     : 'numberfield',
     label    : 'Temperature',
     hintHtml : '<i>°C</i>'
 }

This config can be set to a function to dynamically generate the hintHtml text:

 {
     type     : 'numberfield',
     label    : 'Duration',
     hintHtml : ({ value }) => (value === 1) ? '<i>Day</i>' : '<i>Days</i>'
 }

The function is passed an object with the following properties:

• source A reference to the field instance.
• value The current value of the field.

A hintHtml function will be called when the field changes value.

The labels to add either before or after the input field. Each label may have the following properties:

• html The label text.
• align 'start' or 'end' which end of the field the label should go.

Specify true to auto select field contents on focus

Show a trigger to clear field, if this field is not readOnly. The trigger is available in the triggers object under the name clear. May also be an object which configures the clear trigger.

Set to false to prevent user from editing the field. For TextFields it is basically the same as setting readOnly, but for PickerFields there is a distinction where it allows you to pick a value but not to type one in the field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

On mobile devices, PickerFields are set to editable : false by default so that the user must select a value from the dropdown picker rather than having to type a value which will cause a display of the virtual keyboard.

If typing is essential to the functioning of the field, configuring the field with editable : true will override this behaviour.

Specify true to highlight field after external value changes

The delay in milliseconds to wait after the last keystroke before triggering a change event. Set to 0 to not trigger change events from keystrokes (listen for input event instead to have immediate feedback, change will still be triggered on blur).

If the field is clearable, the change event fires immediately on receiving the clear gesture.

Name of the field which is used as a key to get/set values from/to the field. Used prior to ref and id in Container.values.

The config is useful when the field is used in EventEditor or TaskEditor to load/save values automatically.

Text to display in empty field.

Makes the field unmodifiable by user action. The input area is not editable, and triggers are unresponsive.

This is a wider-acting setting than editable which only sets the readOnly attribute of the <input> field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

Configure as true to indicate that a null field value is to be marked as invalid. This will optionally append a * to the field label if showRequiredIndicator is set.

If this field is not readOnly, then setting this option means that pressing the ESCAPE key after editing the field will revert the field to the value it had when the user focused the field. If the field is not changed from when focused, the clearable behaviour will be activated.

true to automatically display a * after the label for this field when it is required.

Set to true, completely bypasses validation logic (could be userful if your field is not editable to the user).

The triggers to add either before or after the input field. Each property name is the reference by which an instantiated Trigger Widget may be retrieved from the live triggers property.

Each trigger may have the following properties:

• cls The CSS class to apply.
• handler A method in the field to call upon click
• align (Optional) 'start' or 'end' which end of the field the trigger should go.
• weight (Optional) Higher weighted triggers gravitate towards the input field.
• key (Optional) The key name of the key to use as the activation key of this trigger.

const textField = new TextField({
  triggers : {
      check : {
          cls : 'fa fa-check',
          handler() {
              ...
          }
      },
      ...
  }
})

Default value

Set to false to prevent user from editing the field. For TextFields it is basically the same as setting readOnly, but for PickerFields there is a distinction where it allows you to pick a value but not to type one in the field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

On mobile devices, PickerFields are set to editable : false by default so that the user must select a value from the dropdown picker rather than having to type a value which will cause a display of the virtual keyboard.

If typing is essential to the functioning of the field, configuring the field with editable : true will override this behaviour.

The input element at the heart if this field

Returns true if this field is empty. That is, if it would violate the required setting.

This may have different definitions in subclasses from simple text fields.

Returns true if the field's input is empty

Returns true if the field value is valid

Text to display in empty field.

Makes the field unmodifiable by user action. The input area is not editable, and triggers are unresponsive.

This is a wider-acting setting than editable which only sets the readOnly attribute of the <input> field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

Configure as true to indicate that a null field value is to be marked as invalid. This will optionally append a * to the field label if showRequiredIndicator is set.

true to automatically display a * after the label for this field when it is required.

The triggers to add either before or after the input field. Each property name is the reference by which an instantiated Trigger Widget may be retrieved from the live triggers property.

Each trigger may have the following properties:

• cls The CSS class to apply.
• handler A method in the field to call upon click
• align (Optional) 'start' or 'end' which end of the field the trigger should go.
• weight (Optional) Higher weighted triggers gravitate towards the input field.
• key (Optional) The key name of the key to use as the activation key of this trigger.

const textField = new TextField({
  triggers : {
      check : {
          cls : 'fa fa-check',
          handler() {
              ...
          }
      },
      ...
  }
})

Gets or sets the value. The returned type will depend upon the Field subclass.

TextField returns a String.

NumberField returns a Number.

DateField and TimeField return a Date object, and null if the field is empty.

Combo will return a String if configured with items as a simple string array. Otherwise it will return the valueField value from the selected record, or null if no selection has been made.

Clears the value of this Field, and triggers the clear event.

Selects the field contents. Optionally may be passed a start and end.

Called by the base Field class's set value to sync the state of the UI with the field's value.

Relies upon the class implementation of get inputValue to return a string representation of the value for user consumption and editing.

This method can be overridden.