Container

A config object containing default settings to apply to all child widgets.

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

An array of child item config 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.

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

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

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

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

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

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

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

Update assigned record automatically on field changes

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.

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

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.

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

Returns the first widget in this Container.

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.

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

Returns true if all contained fields are valid, otherwise false

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

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.

Returns the last widget in this Container.

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

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

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.

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

The number of visible child items shown in this Container.

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

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.

Returns the widget at the specified index in this Container.

Returns a directly contained widget by id

Inserts the passed widget into this Container at the specified position.

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.

Removes the passed child/children from this Container.

Removes all children from this Container.

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.

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.