Container
Widget

A Widget that can contain other widgets. Uses a CSS Grid layout by default, either use CSS or see the layout config to apply another layout.

// Create a container with two widgets
const container = new Container({
    items : {
        name  : { type : 'textfield', label : 'Name' },
        score : { type : 'numberfield', label : 'Score' }
    }
});

Label position & input field alignment

Fields support placing labels either before or above them. This can be set for all fields in a container at once by specifying the labelPosition config. It supports 3 settings:

'above' - Labels are placed above the field. For text fields in the Material3 theme, this means ~ on the fields top border.
'before' - Labels are placed before the field.
'align-before' - Labels are placed before the field and the fields are arranged in a two column layout (used in the live demo above).

align-before setting cannot be used in conjunction with specifying a Container layout.

When using 'align-before', the container uses display: grid to lay out the fields. You can override this by specifying a different grid-template-columns value in your CSS. To get two equal width columns, use:

.b-container.b-columns {
    grid-template-columns: 1fr 1fr;
}

If you want input elements aligned to the right / end side of your container, enable inputFieldAlign as seen in the demo below.

Adding and removing child widgets

Containers can have child widgets added, or removed during their lifecycle to accommodate business needs. For example:

 // Insert a child widget before another field
 myContainer.insert(textField, someField)

 // Remove a child widget
 myContainer.remove(checkboxField);

If you are looking for a more powerful container that can have toolbars, a title bar, and more see Panel.

No results

Configs

Configs are options you supply in a configuration object when creating an instance of this class

autoUpdateFields : Boolean

internal

Update fields if the record changes

defaultFocus : Function/String

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

Parameters

widget : Widget

Widget passed to method

Returns

Boolean

truthy value if widget is the default one

focusDescendant : Boolean

internal

Can be set to true to make a focus of a focusable encapsulating element relay focus down into a focusable child. This is normally false to allow mousedown to begin text selection in Popups.
gridColumns : Number

internal

Number of columns to use in a grid layout. Applied as grid-template-columns: repeat(n, auto). Also applies the b-columns CSS class to the container.

Has a corresponding runtime gridColumns property.
inputFieldAlign : 'start'/'end'

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.
isolateFields : Booleanfalse

internal

Specify true to isolate record changes to this container and its ancestors. Prevents record updates from propagating up from here and also prevents record updates from parent from propagating down to us.
labelPosition : 'before'/'above'/'align-before'/'auto'/null

Convenience setting to use same label placement on all child widgets.

Set it to 'auto' to let the theme decide on label placement.

Specifying 'align-before' will position labels before the field and also apply a two column layout (in combination with display: contents on the fields) to align all labels in the first column and the fields in the second.

Has a corresponding runtime labelPosition property.

rendition : String/Object<String, String>/null

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.

border : Boolean

Set true to add a border to this container's element.
itemCls : String

An optional CSS class to add to child items of this container.
defaults : WidgetConfig

A config object containing default settings to apply to all child widgets.
items : Object<String, WidgetConfig | MenuItemEntry>/(WidgetConfig|MenuItemEntry|Widget)[]
An object containing typed child widget config objects or Widgets. May 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.
```
 class MyContainer extends Container {
     static configurable = {
         items : {
             details : {
                 type : 'panel',
                 ....
             },
             button : {
                 type : 'button',
                 text : 'Save'
             }
         }
     }
 }

 new MyContainer({
     title    : 'Test Container',
     floating : true,
     centered : true,
     width    : 600,
     height   : 400,
     layout   : 'fit',
     items    : {
         button : {
             disabled : true
         },
         details : {
             title : 'More coolness',
             html  : 'Details content'
         }
     }
 }).show();
```
The order of the child widgets is determined by the order they are defined in items, but can also be affected by configuring a weight on one or more widgets.

To remove existing items, set corresponding keys to null.

If you want to customize child items of an existing class, you can do this using the child widget 'ref' identifier (useful for reconfiguring Event Editor in Scheduler / Gantt):
```
 new MyCustomTabPanel({
     items    : {
         // Reconfigure tabs
         firstTab : {
             title : 'My custom title'
         },
         secretTab : null // hide this tab
     }
 }).show();
```
Note that conversion between array and object notation is not supported, if you want to override items in a container that uses object notation, you must use the same notation. This applies for example to when customizing items in the event editor in Scheduler and the task editor in Scheduler Pro and Gantt.

Has a corresponding runtime items property.
labelWidth : Number/null
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 });
```
If your goal is simply to have labels be same width to have fields to align nicely in a form like layout, consider using the labelPosition config with the value 'align-before' instead, which will use CSS Grid to align all labels in one column and all fields in another, without the need to specify a fixed width.

Has a corresponding runtime labelWidth property.
lazyItems : Object<String, WidgetConfig>/WidgetConfig[]/Widget[]

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.
namedItems : Object<String, WidgetConfig>
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.
textContent : Booleantrue

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.
hideWhenEmpty : Boolean

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.
layout : String/LayoutConfig
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.
layoutStyle : Object
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.
overflowable : Boolean/Stringfalse

internal

When set to true, this widget is considered as a whole when processing Toolbar overflow. When false, this widget's child items are considered instead.

When set to the string 'none', this widget is ignored by overflow processing. This option should be used with caution as it prevents the overflow algorithm from moving such widgets into the overflow popup which may result in not clearing enough space to avoid overflowing the toolbar.
autoUpdateRecord : Boolean

Update assigned record automatically on field changes
record : Model

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.
strictRecordMapping : Booleanfalse

Specify true to match fields by their name property only when assigning a record, without falling back to ref.

Has a corresponding runtime strictRecordMapping property.

tabBarItems : ToolbarItems[]/Widget[]

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

Properties

Properties are getters/setters or publicly accessible variables on this class

isContainer : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of Container class, or subclass thereof.

firstItem : Widget

READONLY

Returns the first widget in this Container.
gridColumns : Number

internal

Number of columns to use in a grid layout. Applied as grid-template-columns: repeat(n, auto). Also applies the b-columns CSS class to the container.

Has a corresponding gridColumns config.
hasChanges : Boolean

READONLY

Returns true if any of the fields in this container have been changed since the container was loaded with a record.

Note that this value does not update during typing. The field's change event which is triggered when the field is blurred causes this to be updated.

For example when processing a "close" button click, this value will be in its correct state.
initialItems : Boolean

internal

READONLY

This property is true until the container's initial items config has been processed. This property is set to false by the updateItems method.
inputFieldAlign : 'start'/'end'

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 inputFieldAlign config.
isSettingValues : Boolean

READONLY

Returns true if currently setting values. Allow fields to change highlighting to distinguishing between initially setting values and later on changing values.
isValid : Boolean

READONLY

Returns true if all contained fields are valid, otherwise false
items : (WidgetConfig|MenuItemConfig|Widget)/Object<String, WidgetConfig | MenuItemConfig>
A property, which, when read, returns an array of the child items of this container in rendered order.

This property may also be set to change the child items of the container. Just as in the initial items configuration, the new value may either be an array of Widgets/Widget configs or an object.

If specified as an Object, the property names are used as the child Widget's ref name, and the value is the child Widget/Widget config.

When setting this, any items which are only in the outgoing child items which were created by this container from raw config objects are destroyed.

Usage patterns:
```
myContainer.items = {
    name : {
        type  : 'textfield',
        label : 'User name'
    },
    age : {
        type  : 'numberfield',
        label : 'User age'
    }
};
```
or
```
myContainer.items = [{
    ref   : 'name',
    type  : 'textfield',
    label : 'User name'
},
    ref   : 'age',
    type  : 'numberfield',
    label : 'User age'
}];
```
Has a corresponding items config.
labelPosition : 'before'/'above'/'align-before'/'auto'/null

Convenience setting to use same label placement on all child widgets.

Set it to 'auto' to let the theme decide on label placement.

Specifying 'align-before' will position labels before the field and also apply a two column layout (in combination with display: contents on the fields) to align all labels in the first column and the fields in the second.

Has a corresponding labelPosition config.
lastItem : Widget

READONLY

Returns the last widget in this Container.

rendition : String/Object<String, String>/null

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 rendition config.

values : Object<String, Object>

Retrieves or sets all values from/to contained widgets.

The property set or read from a contained widget is its defaultBindProperty.

This defaults to the value for fields.

You may add child widgets which may accept and yield a value to/from another property, such as a Button having its href set.

Accepts and returns a map, using name, ref or id (in that order) as keys.

const container = new Container({
    appendTo : document.body,
    items    : {
        firstName : {
            type : 'textfield
        },
        surName : {
            type : 'textfield
        }
        saveButton : {
            type                : 'button',
            text                : 'Save',
            defaultBindProperty : 'href'
            href                : '#'
        }
    }
});

container.values = {
    firstName  : 'Clark',
    surname    : 'Kent',
    saveButton : '#save-route'
};

isContainer : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of Container class, or subclass thereof.
labelWidth : Number/null
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 });
```
If your goal is simply to have labels be same width to have fields to align nicely in a form like layout, consider using the labelPosition config with the value 'align-before' instead, which will use CSS Grid to align all labels in one column and all fields in another, without the need to specify a fixed width.

Has a corresponding labelWidth config.
layout : Layout

The layout as an instance of Layout. This is a helper class which adds and removes child widgets to this Container's DOM and applies CSS classes based upon its requirements.

The card layout provides for showing one child widget at a time, and provides a switching API to change which child widget is currently active.

Has a corresponding layout config.
layoutStyle : Object
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 layoutStyle config.
record : Model

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 record config.
strictRecordMapping : Booleanfalse

Specify true to match fields by their name property only when assigning a record, without falling back to ref.

Has a corresponding strictRecordMapping config.
visibleChildCount : Number

READONLY

The number of visible child items shown in this Container.
widgetMap : Object<String, Widget>

READONLY

An object which contains a map of descendant widgets keyed by their ref. All descendant widgets will be available in the widgetMap.

Functions

Functions are methods available for calling on the class

add( ...toAdd )
: Widget/Widget[]

Appends the passed widget / widgets or config(s) describing widgets to this Container.

If the widgets specify a weight, they are inserted at the correct index compared to the existing items weights.
createWidget( widget )

internal

This function converts a Widget config object into a Widget.
getAt( index )
: Widget

Returns the widget at the specified index in this Container.
getPositionableLocation( position )
: HTMLElement[]

internal

Returns a 2-element array of [parentElement, insertBefore] that specifies where in the DOM to insert a child item based on its positionable config value.
getWidgetById( id )
: Widget

Returns a directly contained widget by id
includes( widgetOrId )
: Boolean

Determines if the passed widget is an immediate child of this Container.
insert( toAdd, index )
: Widget

Inserts the passed widget into this Container at the specified position.
onFieldChange( params )

internal

A function called by descendant widgets after they trigger their 'change' event, in reaction to field changes. By default, implements the functionality for the autoUpdateRecord config.
processWidgetConfig( widgetConfig, addingTo )
: void/Boolean

This function is called prior to creating widgets, override it in subclasses to allow containers to modify the configuration of each widget.

When adding a widget to a container hierarchy, each parent containers' processWidgetConfig will be called.

Returning false from the function prevents the widget from being added at all.
remove( ...toRemove )
: Widget/Widget[]

Removes the passed child/children from this Container.
removeAll( )
: Widget[]

Removes all children from this Container.
resetValues( values )
Resets field values and dirty tracking.
- Calling with no arguments restores the values captured at the last clean setValues call (i.e. the baseline established when setValues(...) ran, typically via setting a record).
- Calling with an object applies those values and establishes a new clean baseline.
setValues( values, options )

Sets values into descendant fields/widgets.

Accepts either a data Model instance or a plain object whose keys map to field names/refs/ids. The second parameter is passed through to child widgets so they can customize how they resolve and assign their value (mirrors previous internal usage).

Change tracking (dirty state) is now managed here.

When called, existing dirty state is cleared and a new baseline of initialValues is captured.
setupWidgetConfig( widgetConfig, type )
: WidgetConfig

internal

This method combines container defaults

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

beforeSetRecord

Fired before this container will load record values into its child fields. This is useful if you want to modify the UI before data is loaded (e.g. set some input field to be readonly)
dirtyStateChange

Fires when a field is mutated and the state of the hasChanges property changes

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onBeforeSetRecord

Called before this container will load record values into its child fields. This is useful if you want to modify the UI before data is loaded (e.g. set some input field to be readonly)
onDirtyStateChange

Called when a field is mutated and the state of the hasChanges property changes

CSS variables

CSS variables that can be set to adjust appearance

Name	Description
--b-container-align-content	Containers align-content setting
--b-container-border-color	Border color for bordered containers
--b-container-border-width	Border width for bordered containers
--b-container-color	Containers color setting
--b-container-gap	Gap between container items
--b-container-padding	Container padding
--b-divider-font-size	Divider font size
--b-divider-font-weight	Divider font weight
--b-divider-line-color	Divider line color
--b-divider-margin-block	Divider block margin
--b-divider-text-color	Divider text color

Container
Widget

Label position & input field alignment

Adding and removing child widgets

Configs

Parameters

Returns

Properties

Functions

Events

Event handlers

CSS variables

Source path

Inheritance tree3

Mixins5

Contents

Container Widget

Label position & input field alignment

Adding and removing child widgets

Configs

Parameters

Returns

Properties

Functions

Events

Event handlers

CSS variables

Source path

Inheritance tree3

Mixins5

Contents

Container
Widget