Column

This config enables automatic height for all cells in this column. It is achieved by measuring the height a cell after rendering it to DOM, and then sizing the row using that height (if it is greater than other heights used for the row).

Heads up if you render your Grid on page load, if measurement happens before the font you are using is loaded you might get slightly incorrect heights. For browsers that support it we detect that and remeasure when fonts are available.

NOTE: Enabling this config comes with a pretty big performance hit. To maintain good performance, we recommend not using it. You can still set the height of individual rows manually, either through data or via renderers.

Also note that this setting only works fully as intended with non-flex columns.

Rows will always be at least rowHeight pixels tall even if an autoHeight cell contains no data.

Manually setting a height from a renderer in this column will take precedence over this config.

Has a corresponding runtime autoHeight property.

This config sizes a column to fits its content. It is used instead of width or flex.

This config requires the ColumnAutoWidth feature which responds to changes in the grid's store and synchronizes the widths' of all autoWidth columns.

If this config is not a Boolean value, it is passed as the only argument to the resizeToFitContent method to constrain the column's width.

Has a corresponding runtime autoWidth property.

The name of the data model field to read a cells value from.

Also accepts dot notation to read nested or related data, for example 'address.city'.

Has a corresponding runtime field property.

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

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.

The collapse behavior when collapsing a parent column. Specify "toggleAll" or "showFirst".

• "showFirst" toggles visibility of all but the first columns.

• "toggleAll" toggles all children, useful if you have a special initially hidden column which gets shown in collapsed state. To specify which columns are initially hidden, configure them with toggleAllHidden.

In the snippet below, the first two child columns are initially shown, while the third is initially hidden. When collapsing the parent column, the visibility of all three children will be toggled, so the third column will be shown and the first two hidden.

new Grid({
   columns : [{
         text        : 'Parent',
         collapsible : true,
         collapseMode : 'toggleAll',
         children    : [
             { text : 'Shown initially', field : 'field1', flex : 1 },
             { text : 'Shown initially', field : 'field2', flex : 1 },
             { text : 'Hidden initially', field : 'field3', flex : 1, toggleAllHidden : true }
         ]
   }]
});

{@note}Note that when using toggleAll mode, at least one child column must be configured with toggleAllHidden: true and at least one must not.{@/note}

Has a corresponding runtime collapseMode property.

A config object used to create the input field which will be used for editing cells in the column. Used when CellEdit feature is enabled. The Editor refers to field for a data source.

Configure this as false or null to prevent cell editing in this column.

All subclasses of Field can be used as editors. The most popular are:

• TextField
• NumberField
• DateField
• TimeField
• Combo

If record has method set + capitalized field, method will be called, e.g. if record has method named setFoobar and the field is foobar, then instead of record.foobar = value, record.setFoobar(value) will be called.

Function may be used for React application parameter for using JSX components as editors.

 columns : [
        {
            type   : 'name',
            field  : 'name',
            width  : 250,
            editor : ref => <TextEditor ref={ref}/>
        },
        ...
]

where passing ref to the React editor is essential for the editor to work.

NOTE: React editor component must implement setValue method which usually internally calls setState. React setState is asynchronous so we need to return Promise which will be resolved when setState finishes. A typical example of setValue method implemented in a React editor is:

setValue(value) {
    return new Promise(resolve => this.setState({ value }, () => resolve(value)));
}

Please consult the React Integration Guide for details on usage of React cell editors.

Note that for Column subclasses which have a default editor, the editor config is merged with the Column class's default editor config. This allows an application to reconfigure the default editor to conform to requirements for a specific column:

new Grid({
    columns : [{
        type  : 'date',
        field : 'date',
        // Override defaults for the date editor
        editor : {
            step : null // disable back/forward stepping
        }
    }]
});

Has a corresponding runtime editor property.

Allow filtering data in the column (if Filter or FilterBar feature is enabled).

Also allows passing a custom filtering function that will be called for each record with a single argument of format { value, record, [operator] }. Returning true from the function includes the record in the filtered set.

Configuration object may be used for FilterBar feature to specify filterField. See an example in the code snippet below or check FilterBar page for more details.

const grid = new Grid({
    columns : [
         {
             field : 'name',
             // Disable filtering for this column
             filterable : false
         },
         {
             field : 'age',
             // Custom filtering for this column
             filterable: ({ value, record }) => Math.abs(record.age - value) < 10
         },
         {
             field : 'start',
             // Changing default field type
             filterable: {
                 filterField : {
                     type : 'datetime'
                 }
             }
         },
         {
             field : 'city',
             // Filtering for a value out of a list of values
             filterable: {
                 filterField : {
                     type  : 'combo',
                     value : '',
                     items : [
                         'Paris',
                         'Dubai',
                         'Montreal',
                         'London',
                         'New York'
                     ]
                 }
             }
         },
         {
             field : 'score',
             filterable : {
                 // This filter fn doesn't return 0 values as matching filter 'less than'
                 filterFn : ({ record, value, operator, property }) => {
                     switch (operator) {
                         case '<':
                             return record[property] === 0 ? false : record[property] < value;
                         case '=':
                             return record[property] == value;
                         case '>':
                             return record[property] > value;
                     }
                 }
             }
         }
    ]
});

When providing a custom filtering function, if the filter feature is configured with prioritizeColumns : true that function will also be used for programmatic filtering of the store:

const grid = new Grid({
    features : {
        filter : {
            prioritizeColumns : true
        }
    },

    columns : [
         {
             field : 'age',
             // Custom filtering for this column
             filterable: ({ value, record }) => Math.abs(record.age - value) < 10
         }
    ]
});

// Will use filterable() from the column definition above
grid.store.filter({
    property : 'age',
    value    : 50
});

To use custom FilterField combo store it should contain one of these data or readUrl configs. Otherwise combo will get data from owner Grid store.

const grid = new Grid({
    columns : [
         {
             field : 'name',
             filterable: {
                 filterField {
                     type  : 'combo',
                     store : new Store({
                         data : ['Adam', 'Bob', 'Charlie']
                     })
                 }
             }
         }
    ]
});

or

const grid = new Grid({
    columns : [
         {
             field : 'name',
             filterable: {
                 filterField : {
                    type  : 'combo',
                    store : new AjaxStore({
                        readUrl  : 'data/names.json',
                        autoLoad : true
                    })
                 }
             }
         }
    ]
});

Has a corresponding runtime filterable property.

A function which is called when a cell edit is requested to finish.

This may be an async function which performs complex validation. The return value should be:

• false - To indicate a generic validation error
• true - To indicate a successful validation, which will complete the editing
• a string - To indicate an error message of the failed validation. This error message will be cleared upon any subsequent user input.

The action for the failed validation is defined with the invalidAction config.

For example for synchronous validation:

const grid = new Grid({
   columns : [
      {
         type : 'text',
         text : 'The column',
         field : 'someField',
         flex : 1,
         finalizeCellEdit : ({ value }) => {
             return value.length < 4 ? 'Value length should be at least 4 characters' : true;
         }
      }
   ]
});

Here we've defined a validation finalizeCellEdit function, which marks all edits with new value less than 4 characters length as invalid.

For asynchronous validation you can make the validation function async:

finalizeCellEdit : async ({ value }) => {
    return await performRemoteValidation(value);
}

Has a corresponding runtime finalizeCellEdit property.

By default, cell editing is finalized when the editor is blurred or if the user taps outside the editor. For complex custom editors, focus or tapping might be expected outside the Bryntum owned editor. In such cases, supply false for this config to take manual control over when cell editing in the column should be finalized.

To accept changes, call finishEditing. To reject, call cancelEditing.

// Setup
const grid = new Grid({
  columns : [
    {
      text               : 'Skills',
      field              : 'skills',
      managedCellEditing : false
    }
  ]
});

// From your custom editor, when you are ready to accept changes
grid.finishEditing();

Has a corresponding runtime managedCellEditing property.

Allow sorting of data in the column. You can pass true/false to enable/disable sorting, or provide a custom sorting function, or a config object for a CollectionSorter

const grid = new Grid({
    columns : [
         {
             // Disable sorting for this column
             sortable : false
         },
         {
             field : 'name',
             // Custom sorting for this column
             sortable(user1, user2) {
                 return user1.name < user2.name ? -1 : 1;
             }
         },
         {
             // A config object for a Core.util.CollectionSorter
             sortable : {
                 property         : 'someField',
                 direction        : 'DESC',
                 useLocaleCompare : 'sv-SE'
             }
         }
    ]
});

When providing a custom sorting function, if the sort feature is configured with prioritizeColumns : true that function will also be used for programmatic sorting of the store:

const grid = new Grid({
    features : {
      sort : {
          prioritizeColumns : true
      }
    },

    columns : [
         {
             field : 'name',
             // Custom sorting for this column
             sortable(user1, user2) {
                 return user1.name < user2.name ? -1 : 1;
             }
         }
    ]
});

// Will use sortable() from the column definition above
grid.store.sort('name');

Also, any custom sorter function is called with an additional parameter indicating the sort direction. Please note that is an informative parameter, the result of the sort function is already reversed if needed depending on direction.

const grid = new Grid({
    columns : [
         {
             field : 'name',
             // direction will be ASC or DESC
             sortable(user1, user2, direction) {
                 return user1.name < user2.name ? -1 : 1;
             }
         }
    ]
});

Has a corresponding runtime sortable property.

Only applies for leaf columns in a collapsible group configured with collapseMode : 'toggleAll'. Specify true to show the column when the group is collapsed, false to hide it.

See collapseMode for more details and an example.

Has a corresponding runtime toggleAllHidden property.

Region (part of the grid, it can be configured with multiple) where to display the column. Defaults to defaultRegion.

A column under a grouped header automatically belongs to the same region as the grouped header.

Has a corresponding runtime region property.

Extra items to show in the cell context menu for this column, null or false to not show any menu items for this column.

cellMenuItems : {
    customItem : { text : 'Custom item' }
}

Has a corresponding runtime cellMenuItems property.

Extra items to show in the header context menu for this column.

// A rank column, which displays its header text vertically and offers a menu item to toggle that
{
    text              : 'Rank',
    field             : 'rank',
    width             : 30,
    type              : 'number',
    headerWritingMode : 'sideways-lr',
    align             : 'center',
    headerMenuItems   : {
        toggleVerticalText : {
            text    : 'Vertical header text',
            checked : true,
            weight  : 10,
            onItem  : ({ column }) => {
                column.headerWritingMode = column.headerWritingMode ? null : 'sideways-lr';
            }
        }
    }
},

Has a corresponding runtime headerMenuItems property.

Specify true to merge cells within the column whose value match between rows, making the first occurrence of the value span multiple rows.

Only applies when using the MergeCells feature.

This setting can also be toggled using the column header menu.

Has a corresponding runtime mergeCells property.

Set to false to prevent merging cells in this column using the column header menu.

Only applies when using the MergeCells feature.

Has a corresponding runtime mergeable property.

An empty function by default, but provided so that you can override it. This function is called each time a merged cell is rendered. It allows you to manipulate the DOM config object used before it is synced to DOM, thus giving you control over styling and contents.

NOTE: The function is intended for formatting, you should not update records in it since updating records triggers another round of rendering.

const grid = new Grid({
  columns : [
    {
      field      : 'project',
      text       : 'Project',
      mergeCells : 'true,
      mergedRenderer({ domConfig, value, fromIndex, toIndex }) {
        domConfig.className.highlight = value === 'Important project';
      }
   }
 ]
});

Has a corresponding runtime mergedRenderer property.

Set to false to not always clear cell content if the renderer returns undefined or has no return statement. This is useful when you mutate the cellElement, and want to prevent cell content from being reset during rendering.

Set to true to always clear cell content regardless of renderer return value.

Has a corresponding runtime alwaysClearCell property.

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.

An array of the widgets to append to the column header. These widgets have this Column instance as their owner which can be used to reference the column, and the owning Grid via this.owner.grid.

columns : [
{
    text          : 'Name',
    field         : 'name',
    flex          : 1,
    headerWidgets : [
        {
            type      : 'button',
            text      : 'Add row',
            rendition : 'filled',
            async onAction() {
                const
                     grid = this.owner.grid,
                     [newRecord] = grid.store.add({
                         name : 'New user'
                     });

                await grid.scrollRowIntoView(newRecord);

                await grid.features.cellEdit.startEditing({
                    record : newRecord,
                    field  : 'name'
                });
            }
        }
    ]
}]

Has a corresponding runtime headerWidgets property.

Applies a CSS class that controls the CSS writing-mode property for the column header text element.

{
    text              : 'Rank',
    field             : 'rank',
    width             : 30,
    type              : 'number',
    headerWritingMode : 'sideways-lr'
}

Has a corresponding runtime headerWritingMode property.

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

A callback function called after every cell has been rendered, which lets you mutate the cell/row or contents. This is useful when you want to mutate contents of a pre-configured column (e.g. CheckColumn, WidgetColumn etc.) without overwriting the built-in renderer.

In the method, you can modify the cell / row elements, e.g. to add custom CSS classes:

new Grid({
    columns : [
        {
            text     : 'Name',
            afterRenderCell : ({ record, row, cellElement }) => {
                cellElement.classList.toggle('myClass', true);
                // Add special CSS class to new rows that have not yet been saved
                row.cls.newRow = record.isPhantom;
            }
        }
    ]
});

Has a corresponding runtime afterRenderCell property.

Renderer function for group headers (when using Group feature).

const grid = new Grid({
    columns : [
        {
            text : 'ABC',
            groupRenderer(renderData) {
                return {
                     class : {
                         big   : true,
                         small : false
                     },
                     children : [
                         { tag : 'img', src : 'img.png' },
                         renderData.groupRowFor
                     ]
                };
            }
        }
    ]
});

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding runtime groupRenderer property.

Renderer function for the column header.

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding runtime headerRenderer property.

Renderer function, used to format and style the content displayed in the cell. Return the cell text you want to display. Can also affect other aspects of the cell, such as styling.

new Grid({
    columns : [
        { text : 'Status', renderer : ({ record }) => record.status }
    ]
});

You can also return a DomConfig object describing the markup:

new Grid({
    columns : [
        {
             text : 'Status',
             renderer : ({ record }) => {
                 return {
                     class : 'myClass',
                     children : [
                         {
                             tag : 'i',
                             class : 'fa fa-pen'
                         },
                         {
                             tag : 'span',
                             text : record.name
                         }
                     ]
                 };
             }
        }
    ]
});

You can modify the row element too from inside a renderer to add custom CSS classes:

new Grid({
    columns : [
        {
            text     : 'Name',
            renderer : ({ record, row }) => {
               // Add special CSS class to new rows that have not yet been saved
              row.cls.newRow = record.isPhantom;

              return record.name;
        }
    ]
});

If you are adding a renderer to a column that has a built in renderer (like DateColumn or NumberColumn), you may call the built-in renderer from your custom renderer if you want to use the default content and modify it. For example, to highlight modified dates in a DateColumn:

new Grid({
    columns : [
        {
            type     : 'date',
            field    : 'startDate',
            text     : 'Start Date',
            renderer : ({ record, column }) => {
                let result = this.defaultRenderer(...arguments);

                // Highlight modified start dates
                if (record.isFieldModified('startDate')) {
                    result = `<span class="modified">${result}</span>`;
                }
                return result;
            }
        }
    ]
});

Using JSX (React)

When using the Bryntum React wrapper, renderers can return JSX elements:

renderer({ record, value }) {
    return <MyComponent value={value} record={record} />;
}

{@note}When renderer includes static HTML output, htmlEncode will be automatically set to false if not explicitly configured. You are responsible for HTML encoding user-provided data to mitigate XSS issues. See StringHelper.encodeHtml.{@/note}

Has a corresponding runtime renderer property.

Controls stickiness when the StickyCells feature is enabled.

• true (default) - all cell content is pinned while the row scrolls off the top
• false - this column is excluded from stickiness
• A CSS selector string - only the matching child element is pinned

// Only pin the date header inside each cell
{ stickyContent : '.my-date-header' }

Has a corresponding runtime stickyContent property.

Renderer function for the cell tooltip (used with CellTooltip feature). Specify false to disable tooltip for this column.

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding runtime tooltipRenderer property.

Summary type (when using Summary feature). Valid types are:

• 'sum' - Sum of all values in the column
• 'add' - Alias for sum
• 'count' - Number of rows
• 'countNotEmpty' - Number of rows containing a value
• 'average' - Average of all values in the column
• callbackFn - A custom function, used with store.reduce. Its return value becomes the value of the accumulator parameter on the next invocation of callbackFn

Has a corresponding runtime sum property.

Renderer function for summary (when using Summary feature). The renderer is called with an object having the calculated summary sum parameter. Function returns a string value to be rendered.

Example:

columns : [{
    type            : 'number',
    text            : 'Score',
    field           : 'score',
    sum             : 'sum',
    summaryRenderer : ({ sum }) => `Total amount: ${sum}`
}]

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding runtime summaryRenderer property.