Field

Abstract

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.

Has a corresponding runtime editable property.

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.

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.

Has a corresponding runtime readOnly property.

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() {
              ...
          }
      },
      ...
  }
})

Has a corresponding runtime triggers property.

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.

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'
             }
         }
     }
 });

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.

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.

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.