TabBar

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

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.

A query selector function which can identify the descendant widget to which focus should be directed by default.

Or a CSS selector string which identifies a descendant element to focus.

By default, the first focusable descendant widget is chosen. This may direct focus to a different widget:

    new Popup({
        title        : 'Details',
        width        : '25em',
        centered     : true,
        modal        : true,

        // Focus goes straight to OK button in the bottom toolbar on show
        defaultFocus : w => w.ref === 'okButton',
        items        : {
            nameField : {
                type  : 'textfield',
                label : 'Name'
            },
            ageField  : {
                type  : 'numberfield',
                label : 'Name'
            }
        },
        bbar     : {
            items : {
                okButton : {
                    text    : 'OK',
                    handler : okFunction
                },
                cancelButton : {
                    text    : 'Cancel',
                    handler : cancelFunction
                }
            }
        }
    }).show();

Convenience setting to align input fields of child widgets. By default, the Field input element is placed immediately following the label. If you prefer to have all input fields aligned to the right, set this config to 'end'.

Has a corresponding runtime inputFieldAlign property.

Either a default rendition to apply to all child widgets, or a map of renditions keyed by child widget type.

// Mixed types, use object form:
new Container({
  rendition : {
    text   : 'outlined',
    button : 'raised'
  },
  items : [
    { type : 'text', label : 'Name' },
    { type : 'button', text : 'Save' }
  ]
});

// Single type, can use string form:
new Container({
  rendition : 'outlined',
  items : [
    { type : 'button', text : 'Save' },
    { type : 'button', text : 'Cancel' }
  ]
});

Has a corresponding runtime rendition property.

An object containing typed child widget config objects or Widgets. Can also be specified as an array.

If configured as an Object, the property names are used as the child component's ref name, and the value is the child component's config object.

 new Toolbar({
     appendTo : document.body
     items    : {
         button : {
             type : 'button',
             onClick() { ... }
         }
     }
 })

Some special items can also be added:

• -> Pushes following items to the other side
• | Adds a vertical separator

 new Toolbar({
     appendTo : document.body
     items    : {
         button : {
             type : 'button',
             text : 'Click me',
             onClick() { ... }
         },
         separator : '|',
         name : {
             type : 'textfield',
             label : 'Enter name'
         },
         // Align following items to the end of the toolbar
         spacer : '->',
         saveButton : {
             type : 'button',
             text : 'Save',
             onClick() { ... }
         }
     }
 })

Has a corresponding runtime items property.

Sets labelWidth´ for all children of this Container, that does not define their own labelWidth`.

new Container({
   labelWidth : 100,
   items : {
     name : { type : 'textfield', label : 'Name' },
     score : { type : 'numberfield', label : 'Score' }
   }
});

Replaces the old approach of specifying this in the defaults config, with the added advantage of being able to set the default value to have this affect all containers:

// Use labelWidth 100 for all containers in the app
Container.applyDefaults({ labelWidth : 100 });

Has a corresponding runtime labelWidth property.

An array of child itemconfig objects which is to be converted into instances only when this Container is rendered, rather than eagerly at construct time.

This is mutually exclusive with the items config.

An object containing default config objects which may be referenced by name in the items config. For example, a specialized Menu subclass may have a namedItems default value defined like this:

 namedItems : {
     removeRow : {
         text : 'Remove row',
         onItem() {
             this.ownerGrid.remove(this.ownerGrid.selectedRecord);
         }
     }
 }

Then whenever that subclass is instantiated and configured with an items object, the items may use the above defaults like this:

 items : {
     removeRow : true,   // The referenced namedItem will be applied to this
     otherItemRef : {
         text : 'Option 2',
         onItem() { }
     }
}

If a menu instance (or its class) does not include removeRow in its items, no menu item will be created. See also defaults.

Specify true for a container used to show text markup. It will apply the CSS class b-text-content which specifies a default max-width that makes long text more readable.

This CSS class is automatically removed if the container adds/defines child Widgets.

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.

The HTML to display initially or a function returning the markup (called at widget construction time).

This may be specified as the name of a function which can be resolved in the component ownership hierarchy, such as 'up.getHTML' which will be found on an ancestor Widget.

Has a corresponding runtime html property.

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.

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.

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".

Specify true to make this container hide when it has no visible children (Either empty or all children hidden).

Container will show itself when there are visible children, ie: hidden children are shown, or new visible children are added.

The short name of a helper class which manages rendering and styling of child items.

Or a config object which includes a type property which specifies which type of layout to use, and how to configure that layout.

By default, the only special processing that is applied is that the Container class's itemCls is added to child items.

Containers use CSS flexbox in its default configuration to arrange child items. You may either use the layoutStyle configuration to tune how child items are layed out, or use one of the built in helper classes which include:

• fit A single child item is displayed fitting exactly into the contentElement.
• card Child items are displayed one at a time, size to fit the contentElement and are slid in from the side when activated.
• box Child items are layed out using flexbox.

For example:

{
    id     : 'myContainer',
    // Our child items flow downwards and are stretched to fill our width
    layout : {
        type       : 'box',
        direction  : 'column'
        align      : 'stretch'
    }
}

Has a corresponding runtime layout property.

The CSS style properties to apply to the contentElement.

By default, a Container's contentElement uses flexbox layout, so this config may contain the following properties:

• flexDirection default 'row'
• flexWrap
• flexFlow
• justifyContent
• alignItems
• alignContent
• placeContent

Has a corresponding runtime layoutStyle property.

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 toolbars 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.

Whether this widget is read-only. This is only valid if the widget is an input field, or contains input fields at any depth.

All descendant input fields follow the widget's setting. If a descendant widget has a readOnly config, that is set.

Has a corresponding runtime readOnly 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.

Record whose values will be used to populate fields in the container.

Any descendant widgets of this Container with a name property (or a ref if no name is configured) will have its value set to the value of that named property of the record.

If no record is passed, the widget has its value set to null.

To strictly match by the name property, configure strictRecordMapping as true.

When fields loaded from this record are changed by user input, the hasChanges property will be set.

Has a corresponding runtime record property.

Specifies whether (and optionally in which axes) a Widget may scroll. true means this widget may scroll in both axes. May be an object containing boolean overflowX and overflowY properties which are applied to CSS style properties overflowX and overflowY. If they are boolean, they are translated to CSS overflow properties thus:

• true -> 'auto'
• false -> 'hidden'

After initialization, this property yields a Scroller which may be used to both set and read scroll information.

A Widget uses its overflowElement property to select which element is to be scrollable. By default, in the base Widget class, this is the Widget's encapsulating element. Subclasses may implement get overflowElement to scroll inner elements.

Has a corresponding runtime scrollable property.

How this Toolbar should deal with items that overflow its main axis.

Values may be:

• 'menu' A button with a menu is shown and the menu contains the overflowing items.
• 'scroll' The items overflow and mey be scrolled into view using the mouse or scroll buttons.
• null Disable overflow handling

When mode is 'menu', clones of overflowing toolbar item are created and added to a Menu. Any config changes to the original toolbar item are propagated to the menu's clone, so disabling a toolbar item will make the clone in the menu disabled.

The clone of an input field will propagate its value changes back to the original. The overflow button, its menu, and the clones should not be accessed or manipulated by application code.

Note that cloned items will be allocated a unique, generated ID because all IDs must be unique, so CSS targeting an element ID will not apply to a clone in the overflow menu.

Values may also be specified in object form containing the following properties:

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.

When this container is used as a tab in a TabPanel, these items are added to the TabBar when this container is the active tab.

new TabPanel({
    appendTo : targetElement,
    height   : '25em',
    items: {
        firstTab : {
            title: 'First',
            items: {
                name : { type: 'textfield', label: 'Name' }
            },
            tabBarItems : [{
                type    : 'button',
                text    : 'Add tab',
                onClick : 'up.onAddTabClick'
            }]
        }
    },

    onAddTabClick({ value }) {
        this.add({
            type  : 'container',
            title : 'New tab',
            items : {
                button : {
                    type : 'button',
                    text : 'Click me',
                    onClick() {
                        Toast.show('Awesome!');
                    }
                }
            }
        });
    }
});