DurationField

Widget

The listener set for this object.

An object whose property names are the names of events to handle, or options which modifiy how the handlers are called.

See addListener for details about the options.

Listeners can be specified in target class config and they will be merged with any listeners specified in the instantiation config. Class listeners will be fired first:

class MyStore extends Store({
    static configurable = {
        listeners : {
            myCustomEvent() {
            },
            load : {
                prio : 10000,
                fn() { // this load listener handles things first }
            }
        }
    };
});

let store = new MyStore({
  listeners: {
    load: () => { // This load listener runs after the class's },
    ...
  }
});

Handlers as function name

Object event handlers may be specified as a function name. If a string is specified, it is the name of the function in the thisObj object.

If the string begins with up., this object's ownership hierarchy (if present) is scanned for an object which implements that function name:

new Popup({
    tbar : {
        items : {
            myCombo : {
                type      : 'combo',
                editable  : false,
                label     : 'Type',
                listeners : {
                    // Look in owner chain for this function name
                    change : 'up.onFilterChange'
                },
                items     : [
                    'Event',
                    'Task',
                    'Appointment'
                ]
            }
        }
    },
    items : {
        ...
    },
    onFilterChange({ value }) {
        // Handle event type selection here
    }
});

Step size for spin button clicks. The step property may be set in object form specifying two properties, magnitude, a Number, and unit, a String.

If a Number is passed, the step's current unit is used (or day if no current step set) and just the magnitude is changed.

If a String is passed, it is parsed by parseDuration, for example '1d', '1 d', '1 day', or '1 day'.

The duration unit to use with the current magnitude value.

Note that setting a value that includes a unit will override the configured unit.

Has a corresponding runtime unit property.

The value may be set either in object form specifying two properties, a numerical magnitude and a string unit:

new DurationField({
   value : {
     magnitude : 1,
     unit      : 'day'
   }
});

Or as a string, that is parsed in accordance with current locale rules. The string is taken to be the numeric magnitude, followed by whitespace, then an abbreviation, or name of the unit:

new DurationField({
   value : '1 day'
});

If a Number is passed, the field's current unit is used and just the magnitude is changed.

When the passed value includes a unit, that unit will override the unit configured on the field.

Upon read, the value is always a Duration object containing magnitude and unit.

Has a corresponding runtime value property.

A localizable string (May contain 'L{}' tokens which resolve in the locale file) to inject into an element which will be linked using the aria-describedby attribute.

The purpose of the aria-describedby attribute is to provide additional descriptive information for assistive technologies to provide more detailed information about the widget's purpose and state.

This extra description is announced by screen readers after the ariaLabel, providing users with a more comprehensive understanding of the widget's functionality and context. It can be used to convey additional instructions, state information, or any other relevant details that may assist users in effectively interacting with the widget.

This widget is passed as the templateData so that functions in the locale file can interrogate the widget's state.

A localizable string (May contain 'L{}' tokens which resolve in the locale file) to inject as the aria-label attribute.

The purpose of the aria-label attribute is to provide an accessible name for assistive technologies. This is analogous to a <label> element for form fields and is especially important for interactive widgets such as buttons, form fields, etc. that may not have visible text content that can be used as a label - for example an icon-only button.

By providing an aria-label, this ensures that assistive technologies can identify the widget and operate it by this identifier. Voice activation uses this label to allow users to interact with the widget using voice commands. Screen readers also use this label to announce the widget to users with visual impairments, providing them with the necessary information to understand the purpose of the widget and how to interact with it.

This widget is passed as the templateData so that functions in the locale file can interrogate the widget's state.

An object whose keys are the key name and optional modifier prefixes: 'Ctrl+', 'Alt+', 'Meta+', and 'Shift+' (case-insensitive). The values are the name of the instance method to call when the keystroke is received.

For example:

 keyMap : {
     'Ctrl+A': 'onSelectAll',
     'Ctrl+Z': 'onUndo',
     't'     : 'gotoNow',
     [/\d/]  : 'onDigit'
 }

If a key is a visible character (as above), and not modified by any modifier keys, and emanates from an editable element (such as an <input> or <textarea>), the keystroke is ignored. This is to allow the browser to handle typing in editable elements.

Target element filtering

By default, the keyMap will process keystrokes from any element within the widget.

This can be filtered by providing a targetSelector property in the keyMap. If provided, only keystrokes originating from elements matching the targetSelector (or their descendants) will be processed by the keyMap.

For example:

// Only accept keys from elements with class 'my-class' or their descendants.
keyMap : {
   targetSelector : '.my-class',
  'Enter'         : 'actionToPerformOnEnter'
}

This can be done on a more granular level for each keyMap entry by providing a targetSelector property in the action config object:

keyMap : {
    'Enter' : {
        handler        : 'actionToPerformOnEnter',
        targetSelector : '.my-class'
    }
}

Delegation

In addition to key names, the special key 'delegate' can be included to specify additional objects that have their own keyMap. If a keystroke is not handled by this keyMap, the delegates are processed until one has a matching entry in its keyMap. The value of the delegate key can be a single string, an array of strings or an object whose truthy keys are dot paths identifying the delegate(s) related to this instance.

For example:

 keyMap : {
     delegate : ['widgetMap.foo', 'widgetMap.bar', 'tbar']
 }

An widget with the above keyMap will delegate to the child widgets named foo and bar via the widget's widgetMap. In addition, the tbar property of the widget will also be considered as a delegate.

The following is equivalent to the above delegate but using an object. This form can be used to allow removal of entries by derived classes or an overriding instance config.

 keyMap : {
     delegate : {
         'widgetMap.foo' : true,
         'widgetMap.bar' : true,
         tbar            : true
     }
 }

Has a corresponding runtime keyMap property.

The ARIA role to apply to this widget's element. By default, this is set to 'presentation' to avoid accidentally applying a role which may interfere with screen readers.

Bryntum widgets usually set their own appropriate default role, so it is not usually necessary to set this config directly.

However, when creating custom widgets, or when a widget does not set an appropriate default role, this config should be set to the appropriate ARIA role for the widget.

Custom CSS classes to add to element. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:

 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }

Has a corresponding runtime cls property.

Applies the specified color to the widget, by setting the --b-primary CSS variable in the widgets style block.

If the supplied color starts with b-, a named color from the current theme will be used (red -> b-color-red etc.). Applied as <tag>, for example:

<tag>

When the supplied color does not start with b-, it is assumed to be a valid CSS color specification and is used as is. Applied as <tag>, for example:

<tag>

Custom CSS classes to add to the contentElement. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:

 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }

Custom CSS class name suffixes to apply to the elements rendered by this widget. This may be specified as a space separated string, an array of strings, or as an object in which property names with truthy values are used as the class names.

For example, consider a Panel with a ui config like so:

 new Panel({
     text : 'OK',
     ui   : 'light'
 });

This will apply the CSS class 'b-panel-ui-light' to the main element of the panel as well as its many child elements. This allows simpler CSS selectors to match the child elements of this particular panel UI:

 .b-panel-content.b-panel-ui-light {
     background-color : #eee;
 }

Using the cls config would make matching the content element more complex, and in the presence of docked items and nested panels, impossible to target accurately.

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.

Element (or element id) to adopt as this Widget's encapsulating element. The widget's content will be placed inside this element.

If this widget has not been configured with an id, it will adopt the id of the element in order to preserve CSS rules which may apply to the id.

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed.

Set this to true to catch exceptions thrown by this object's event handlers and continue processing the event. The exception will be rethrown on a zero millisecond timeout, so it will not destroy the stack.

Has a corresponding runtime catchEventHandlerExceptions property.

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.

Only valid if this Widget is floating.

How to align this element with its target when showBy is called passing a simple element as an align target.

Either a full alignment config object, or for simple cases, the edge alignment string to use.

When using a simple string, the format is '[trblc]n-[trblc]n' and it specifies our edge and the target edge plus optional offsets from 0 to 100 along the edges to align to. Also supports direction independent edges horizontally, s for start and e for end (maps to l and r for LTR, r and l for RTL).

See the showBy function for more details about using the object form.

Once set, this is stored internally in object form.

Only valid if this Widget is floating. Set to true to be able to drag a widget freely on the page. Or set to an object with a ´handleSelector´ property which controls when a drag should start.

draggable : {
    handleSelector : ':not(button)'
}

Only valid if this Widget is floating.

An object which defined which CSS style property should be animated upon hide, and how it should be animated eg:

{
   opacity: {
       to : 0,
       duration: '10s',
       delay: '0s'
   }
}

Set to 'false' to disable animation.

Only valid if this Widget is floating.

When configured as true, this widget uses isMobile to maximize itself on mobile devices.

Has a corresponding runtime maximizeOnMobile property.

Set to true when a widget is rendered into another widget's contentElement, but must not participate in the standard layout of that widget, and must be positioned relatively to that widget's contentElement.

Editors are positioned widgets.

Only valid if this Widget is floating.

An object which defined which CSS style property should be animated upon show, and how it should be animated eg:

{
   opacity: {
       to : 1,
       duration: '10s',
       delay: '0s'
   }
}

Set to 'false' to disable animation.

The x position for the widget.

Only valid if this Widget is floating and not aligned or anchored to an element.

Has a corresponding runtime x property.

The y position for the widget.

Only valid if this Widget is floating and not aligned or anchored to an element.

Has a corresponding runtime y property.

A DataField which describes a field of a Model that we are editing.

This is used to find formulaProviders which the field may support.

items : {
    formulaField : {
        type      : 'textfield',
        dataField : myStore.modelClass.getFieldDefinition('name')
    }
}

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.

Label position, either 'before' the field or 'above' the field

Leaving it out, or specifying null, lets the theme decide on label placement.

Controls the placement of this widget when it is added to a panel's strips collection. Typical values for this config are 'top', 'bottom', 'left', or 'right', which cause the widget to be placed on that side of the panel's body. Such widgets are called "edge strips".

Also accepts direction neutral horizontal values 'start' and 'end'.

If this config is set to 'header', the widget is placed in the panel's header, following the title. If this config is set to 'pre-header', the widget is placed before the title. Such widgets are called "header strips".

Text alignment: 'left', 'center' or 'right'. Also accepts direction neutral 'start' and 'end'.

Applied by adding a b-text-align-xx class to the widgets element. Blank by default, which does not add any alignment class.

To be compliant with RTL, 'left' yields same result as 'start' and 'right' as 'end'.

An object where property names with a truthy value indicate which events should bubble up the ownership hierarchy when triggered.

const container = new Container({
    items : [
       { type : 'text', bubbleEvents : { change : true }}
    ],

    listeners : {
        change() {
            // Will catch change event from the text field
        }
    }
});

Set to true to call onXXX method names (e.g. onShow, onClick), as an easy way to listen for events.

const container = new Container({
    callOnFunctions : true

    onHide() {
         // Do something when the 'hide' event is fired
    }
});

Has a corresponding runtime callOnFunctions property.

Disable or enable the widget. It is similar to readOnly except a disabled widget cannot be focused, uses a different rendition (usually greyish) and does not allow selecting its value.

Set to 'inert' to also set the inert DOM attribute.

Has a corresponding runtime disabled property.

An object specifying attributes to assign to the root element of this widget. Set null value to attribute to remove it.

new Label({
    elementAttributes : {
       'data-role': 'primary', // Add data-role attribute with `"primary"` value
       inert : '',             // Add inert with no value
       title : null            // This will remove the title attribute from the element
    }
});

Determines if the widgets read-only state should be controlled by its parent.

When set to true, setting a parent container to read-only will not affect the widget. When set to false, it will affect the widget.

A class translations of which are used for translating this entity. This is often used when translations of an item are defined on its container class. For example:

// Toolbar class that has some predefined items
class MyToolbar extends Toolbar {

    static $name = 'MyToolbar';

    static configurable = {
        // this specifies default configs for the items
        defaults : {
            // will tell items to use the toolbar locale
            localeClass : this
        },

        items : {
            // The toolbar has 2 buttons and translation for their texts will be searched in
            // the toolbar locales
            agree :{ text : 'Agree' },
            disagree :{ text : 'Disagree' }
        }
    };

   ...
}

So if one makes a locale for the MyToolbar class that will include Agree and Disagree string translations:

    ...
    MyToolbar : {
        Agree    : 'Yes, I agree',
        Disagree : 'No, I do not agree'
    }

They will be used for the toolbar buttons and the button captions will say Yes, I agree and No, I do not agree.

List of properties which values should be translated automatically upon a locale applying. In case there is a need to localize not typical value (not a String value or a field with re-defined setter/getter), you could use 'localeKey' meta configuration. Example:

 static configurable = {
      localizableProperties : ['width'],

      width : {
          value   : '54em', // default value here
          $config : {
              localeKey : 'L{editorWidth}' // name of the property that will be used in localization file
          }
      }
  };

When this is configured as true a ResizeObserver is used to monitor this element for size changes caused by either style manipulation, or by CSS layout.

By default, notifications are queued up for delivery in the next microtask.

To receive notifications immediately, set the immediate option to true.

Size changes are announced using the resize event.

The owning Widget of this Widget. If this Widget is directly contained (that is, it is one of the items of a Container), this config will be ignored. In this case the owner is always the encapsulating Container.

If this Widget is floating, this config should be specified by the developer.

Registering with an owner creates a lifecycle relationship with that owning Widget. When the owner is destroyed this widget will also be destroyed.

This also allows focus to be tracked in the ownership tree. If a widget owns another widget, then even if that other widget is in a different element, focusing that owned widget will not cause a focusOut event, and the containsFocus property remains set.

A widget can unregister from its owner and break this relationship at any time by setting the property to null. It is then the developer's responsibility to ensure that this Widget is destroyed.

Has a corresponding runtime owner property.

An identifier by which this widget will be registered in the widgetMap of all ancestor containers.

If omitted, this widget will be registered using its id. In most cases ref is preferable over id since id is required to be globally unique while ref is not.

The ref value is also added to the elements dataset, to allow targeting it using CSS etc.

Has a corresponding runtime ref property.

Configure as true to have the component display a translucent ripple when its focusElement, or element is tapped if the current theme supports ripples. Out of the box, only the Material theme supports ripples.

This may also be a config object containing the properties listed below.

E.g.

   columns  : [{}...],
   ripple   : {
       color : 'red',
       clip  : '.b-grid-row'
   },
   ...

A configuration for the tab created for this widget when it is placed in a TabPanel. For example, this config can be used to control the icon of the tab for this widget:

 items : {
     panel : {
         type : 'panel',
         // other configs...

         tab : {
             icon : 'fa fa-wrench'
         }
     },
     ...
 }

Another use for this config is to set the tab's rotate value differently than the default managed by the TabPanel:

 items : {
     panel : {
         type : 'panel',
         // other configs...

         tab : {
             rotate : false   // don't rotate even if tabBar is docked left or right
         }
     },
     ...
 }

Set this to false to prevent the creation of a tab for this widget. In this case, this widget must be shown explicitly. The activeTab for the tab panel will be -1 in this situation.

 items : {
     panel : {
         type : 'panel',
         tab  : false,    // no tab for this item

         // other configs...
     },
     ...
 ]

Has a corresponding runtime tab property.

Tooltip for the widget, either as a string or as a Tooltip config object.

By default, the Widget will use a single, shared instance to display its tooltip as configured, reconfiguring it to the specification before showing it. Therefore, it may not be permanently mutated by doing things such as adding fixed event listeners.

To have this Widget own its own Tooltip instance, add the property newInstance : true to the configuration. In this case, the tooltip's owner will be this Widget.

Note that in the absence of a configured ariaDescription, the tooltip's value will be used to populate an aria-describedBy element within this Widget.

This may be configured as true to make the widget's element use the direction:rtl style.

All descendant widgets, including any floating widgets will inherit this setting.

Has a corresponding runtime rtl property.

Predefined style to use for the field. Possible values are:

• 'outlined' (default)
• 'filled'

The supplied value will be part of the field's class list, as b-text-field-{rendition}.

Has a corresponding runtime rendition property.

Check for CSS compatibility and inclusion related issues and try to auto fix them. Performs the following checks:

• Detects usage of .b-fa class for icons. Since v7, FontAwesome is no longer built-in, the standard .fa class should be used instead.
• Detects missing FontAwesome font. With FontAwesome no longer built-in, this must be included separately by the app. If it is not included, it tries to autoload it from CDN.
• Checks for presence of a Bryntum CSS. Theme and structural CSS was separated in v7, both structural CSS and a theme must be included. If they are not, it tries to autoload them from CDN.

Defaults to true in Grid, Scheduler, Scheduler Pro, Gantt, Calendar and TaskBoard.