Layout Module

The Layout Module facilities creating Layouts - essentially a way of managing columns.

It is designed to enable users easily to switch between different column setups in their grid

Layouts typically contain column visibility and order information but can also include column sorting, grouping, pivoting, size and aggregation information.

note

Filters and Query manage which Rows are displayed; Layouts decide which Columns are displayed

important

By default Layouts will save automatically when their contents change - and there must always be one active Layout in AdapTable

Layout Contents

Layout Definitions include a number of important properties including:

caution

Layouts are primarily sets of column visibility and order; they do not include styling functions (e.g. Conditional Styles) nor do they include searching or filtering functions

tip

It is possible to create a 'View' (i.e. a Layout plus other items of Config) but it requires some custom code using the AdaptableStateKey property of Adaptable Options. See an example here.

Layout Options

The Layout Options section of Adaptable Options contains much Layout-related behaviour and is defined as follows:

PropertyDescriptionDefault
autoSaveLayoutsLayouts save whenever Grid's column / sort info changes; if false, a Save button will displaytrue
autoSizeColumnsInLayoutColumns auto-size when Layout loads for first timefalse
autoSizeColumnsInPivotLayoutColumns auto-size when Pivot-based Layout loads first timefalse
createDefaultLayoutWhether a "Default Layout" will be created in addition to Layouts provided in Configfalse
includeExpandedRowGroupsLayouts will include details of expanded grouped rows; if true these will be re-applied at start-upfalse

Managing Layouts

AdapTable allows you to manage and manipulate Layouts in multiple ways.

Creating Layouts

Layouts are created in 2 ways:

  • visually in the Layout Editor which allows for the selection (and order) of visible columns, sorting, grouping, aggregrating and pivoting.

  • defined in Layout Predefined Config - with the ability to provide full sorting, grouping and pivoting details

note

Creating a Layout in Predefined Config also allows you to set Pinning and Column Widths information - which cannot be done in the Layout Editor (as it is actioned in the Grid itself)

Saving Layouts

By default layouts save automatically when any relevant changes are made in the grid.

To avoid this behaviour set the autoSaveLayouts property to false in Layout Options. When this happens, a Save button will be visible in the Layout toolbar.

tip

You can override the value of the 'autoSaveLayouts' property in Layout Options by setting the AutoSave property in the Layout Definition (which takes precedence)

warning

Any changes made in the Layout Editor will always be saved when the user clicks 'Finish' irrespective of the value of the autoSaveLayouts property

Auto-Sizing Layout Columns

AdapTable enables Layout columns to be auto-sized by default - popular with users where horizontal space is at a premium.

There are 2 properties available in Layout Options (both of which default to false):

  • autoSizeColumnsInLayout - all Layouts will automatically auto-size columns when first opened

    caution

    This will only be used if no Column Width information was provided in the Layout definition.

  • autoSizeColumnsInPivotLayout - pivot Layouts will automatically auto-size columns when first opened

important

If you have the the GridOptions suppressColumnVirtualisation property set to true (in AG Grid), then only the visible columns will be auto sized

Default Layout

AdapTable must always have at least one Layout - which will automatically get updated as the grid changes.

warning

AdapTable will not allow the last remaining Layout in the State to be deleted

If no Layouts are provided in Layout Predefined Config, then AdapTable provides a Default Layout at start-up based on the inital column definitions provided to the grid.

tip

Use the createDefaultLayout property in Layout Options to tell AdapTable to create a Default Layout even if you have defined also Layouts in Predefined Config

Persisting Expanded Groups

By default a Layout will not store information about which Grouped Rows are currently open so this information is lost when the application next loads.

To change this behaviour set the includeExpandedRowGroups property to true in Layout Options

UI Elements

Layout includes the following UI Elements:

  • Popup - Shows a list of existing Layouts with Edit and Delete buttons, and a 'Current' Radio Button to select the current Layout. Also includes an Add button to open the Layout Editor.

  • Editor - A single screen which enables the creation and editing of Layouts.

  • Toolbar - Provides a list of the available Layouts in a dropdown, together with buttons for adding, editing, restoring, deleting and cloning.

  • Tool Panel - Same as Toolbar above.

UI Entitlements

UI Entitlements behaviour is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is is that existing Layouts can be selected, but Users cannot manage or suspend them.

caution

Even with a ReadOnly Entitlement, the Layout can still be modified at run-time by the user resizing or moving Columns in the UI or in the Columns ToolPanel.

tip

The only way to prevent ANY changes to the Layout is, not through Entitlements, but through initial Column definitions that prevent modifications

important

Even when Layouts are hidden AdapTable will still create a Default Layout, update (and persist) it as the grid changes, and load it when the grid re-starts; however all that will be invisible to the User.

Layout Predefined Config

The Layout State contains a collection of Layouts and the Current Layout:

PropertyDescriptionDefault
CurrentLayoutLayout which will be loaded when AdapTable starts - must match Name property in Layout''
LayoutsCollection of Layout objects - listed in Layout toolbar and Tool Panelnull

Layout Object

The full contents of the Layout object is as follows:

PropertyDescription
AggregationColumnsColumns showing aggregated values in grouped rows; first value in record is Column name and second is either the agg func (e.g. sum, avg etc.) or 'true' (to use default aggfunc)
AutoSaveWhether Layout should automatically save or not - overrides autoSaveLayouts property in LayoutOptions
ColumnHeadersMapSet of custom header names for some (or all columns)
ColumnsWhich columns should be visible in the Layout and in which order
ColumnSortsSorting to apply in the Layout
ColumnWidthMapSet of widths for some (or all columns)
EnablePivotWhether pivoting should be enabled in the Grid when this Layout loads
ExpandedRowGroupValuesValues of opened row groups - only used if includeExpandedRowGroups in LayoutOptions is true
NameName of Layout as will appear in Layout toolbar and tool panel
PinnedColumnsMapSet of pinned Columns
PivotColumnsList of Columns which should be pivoted when grid is in pivot mode
RowGroupedColumnsColumns which are row-grouped when the Layout is applied
SuppressAggFuncInHeaderWhether to include the aggFunc name in the column header: e.g. 'sum(Bank Balance)' will just be 'Bank Balance'

As can be seen, there are a number of useful properties and collections including:

Columns

Which columns should be visible in the Layout and in which order.

caution

The names in this list should match those provided when the Columns were defined in the vendor grid (e.g. field in AG Grid).

important

When the Layout is first applied, only the Columns in this array will be visible - and in the order that they are listed here.

Column Widths

ColumnWidthMap is a set of widths for some (or all columns)

The object is defined as follow:

ColumnWidthMap?: {
[columnId: string]: number;
};

To use its, simply pass the names of the Columns (without quotes) together with the widths required:

ColumnWidthMap: {
OrderId: 200,
Comments: 300,
},

Column Sorts

ColumnSorts is a collection of ColumnSort objects which define the sorting which will be applied in the Layout.

The object has 2 properties:

  • Column name
  • Sort Order (e.g. 'Asc' or 'Desc')
ColumnSorts: [
{
ColumnId: 'ShipName',
SortOrder: 'Asc',
},
{
ColumnId: 'ShipVia',
SortOrder: 'Desc'
},
],

Row Grouped Columns

List of columns which should be row-grouped when the Layout is applied.

tip

Make sure that the column names supplied are groupable according to the vendor grid you are using (e.g. enableRowGroup in AG Grid)

Expanded Row Group Values

ExpandedRowGroupValues is a collection of values detailing which Row Groups are opened.

caution

This is only used if includeExpandedRowGroups in LayoutOptions is set to true

note

This is typically set by AdapTable at run-time, rather than provided in Predefined Config

Aggregations

Lists which columns will show aggregated values in Grouped Rows.

caution

This only applies when row grouping is enabled in the grid.

The definition is a Record which contains 2 values:

AggregationColumns?: Record<string, string | true>;
  1. The Column name

  2. Either the agg func required (e.g. sum, avg, min etc.) or *true(to use the default aggfunc)

note

The true value can only be used if an aggFunc was previously defined for the Column

AggregationColumns: {
InvoicedCost: 'sum',
ItemCount: 'avg',
OrderCost: true
},

Pivot Columns

PivotColumns is a collection of names of Columns which should be pivoted when Grid is in Pivot Mode.

caution

This will only be applied if the enablePivot property is set to true

Layout: {
CurrentLayout: 'Pivot View',
Layouts: [
{
Columns: [],
RowGroupedColumns: ['Employee'],
PivotColumns: ['ShipVia', 'ShipCountry'],
AggregationColumns: { InvoicedCost: 'sum', ItemCount: 'max' },
EnablePivot: true,
Name: 'Pivot View',
},
],
},

Pinned Columns

The PinnedColumnsMap property defines a set of pinned columns for the layout.

The definition of the property is:

PinnedColumnsMap?: { [columnId: string]: 'left' | 'right' };

To use the property, simply provide the name of the Column (without quotes) together with the direction (of 'left' or 'right')

PinnedColumnsMap: {
OrderId: 'left',
Comments: 'right',
},

Column Headers

Each Layout can include different Column header names (i.e. captions) than those provided in Grid Options.

This is achieved through the ColumnHeadersMap property which is defined as follows:

ColumnHeadersMap?: { [columnId: string]: string };

To use the property provide the Id of the Column (without quotes) together with the new caption to be used:

ColumnHeadersMap: {
RequiredDate: 'Reqd. Dt',
ChangeLastOrder: 'Change',
},
note

This property should be used in preference to the deprecated HeaderName property in Format Column

Layout Example

export default {
Layout: {
CurrentLayout: 'Pivoted Layout',
Layouts: [
{
Name: 'Simple Layout',
Columns: ['country', 'currency', 'tradeId', 'notional', 'counterparty'],
},
{
Name: 'Sorting Layout',
ColumnWidthMap: {
currency: 200,
counterparty: 300,
},
ColumnSorts: [
{
Column: 'counterparty',
SortOrder: 'Desc',
},
{
Column: 'currency',
SortOrder: 'Desc',
},
],
Columns: ['country', 'currency', 'tradeId', 'notional', 'counterparty'],
},
{
Name: 'Grouping Layout',
Columns: ['country', 'notional', 'counterparty', 'InvoicedCost', 'ItemCount'],
AggregationColumns: { InvoicedCost: 'sum', ItemCount: 'avg' },
GroupedColumns: ['currency', 'country'],
},
{
Name: 'Pivoted Layout',
Columns: ['bid', 'ask', 'price', 'counterparty', 'status', 'stars'],
RowGroupedColumns: ['currency'],
EnablePivot: true,
PivotColumns: ['status', 'stars'],
AggregationColumns: {'bid':'avg', 'ask':'avg'},
},
],
}
} as PredefinedConfig;

In this example we have created 4 Layouts:

  • Simple Layout - sets column visibility and order
  • Sorting Layout - includes 2 sort orders (and 2 columns with widths set)
  • Grouping Layout - includes 2 grouped columns and 2 columns with aggregation set,
  • Pivoted Layout - provides Pivot details (so that the grid will be pivoted when the Layout is selected)

Layout Changed Event

An Adaptable Event that fires whenever the Layout State changes.

LayoutChangedInfo

The LayoutChangedInfo object provides the reason why the Layout changed and the Layout State before and after the change:

PropertyDescription
actionNameWhat caused Layout State to change
newLayoutStateCurrent Layout State
oldLayoutStatePrevious Layout State

Action Names

The value for the actionName property can be one of 5 values:

  • LAYOUT_ADD
  • LAYOUT_EDIT
  • LAYOUT_SAVE
  • LAYOUT_DELETE
  • LAYOUT_SELECT

Event Subscription

Subscribing to the Event is done the same as with all Adaptable Events:

api.eventApi.on('LayoutChanged', (eventInfo: LayoutChangedInfo) => {
// do something with the info
});

Layout API

This section of AdapTable API has a number of methods to enable you to create, edit, clone, delete and retrieve layouts programmatically.

MethodDescription
areLayoutsEqual(layout1, layout2)Compares 2 Layouts for equality
cloneAndSetLayout(layoutToClone, layoutName)Creates new Layout based on given Layout but with name provided and then loads it into Grid
cloneLayout(layoutToClone, layoutName)Creates new Layout based on given Layout but with name provided
createAndSetLayout(layoutToCreate)Creates new Layout in the state and then loads it into Grid
createDefaultLayoutIfNeeded()Creates a Default Layout (when none provided in Config)
createLayout(layoutToCreate)Creates new Layout in the state
doesLayoutExist(layout)Checks whether this Layout exists in the Adaptable State (by comparing Uuid property)
fireLayoutChangedEvent(trigger, oldSate, newState)Fires the LayoutChanged event
getAllLayout()Retrieves all Layouts in Adaptable State
getCurrentLayout()Retrieves Current Layout from Layout State
getCurrentLayoutName()Retrieves name of current Layout
getCurrentVisibleColumnIds()Retrieves array of visible ColumnIds in current Layout
getCurrentVisibleColumnIdsMap()Retrieves map with visible columns in current Layout
getLayoutById(id)Retrieves Layout by id
getLayoutByName(layoutName)Retrieves Layout with the given name
getLayoutDescription(layout)Get a string description of a Layout
getLayoutState()Retrieves Layout section from Adaptable State
saveCurrentLayout()Saves current Layout - using column order, visibility, sorting etc. currently in use in the grid
saveLayout(layoutToSave)Saves given Layout into Adaptable State
setLayout(layoutName)Sets (i.e. selects) the Layout
shouldAutoSaveLayout(layout)Whether this Layout should be auto saved (based on Layout State and Layout Options)
showLayoutPopup()Opens Layout popup screen

FAQ

Is there a limit on the number of Layouts allowed?

No, you can create as many Layouts as you wish but you must always have at least one Layout.

AdapTable will prevent you from deleting the last Layout in your state.

Can my colleague use the same Layout as me?

Yes, if Team Sharing is enabled, then you can upload your Layout so that your colleague can also access it.

Does a Layout include which column(s) is currently sorted?

Yes, this is included in the layout since version 1.6

Does a Layout include pivoting?

Yes if the underlying vendor grid supports pivoting.

Can a Layout included multiple sorts?

Yes. If the underlying grid supports multiple sorts, then the layout will as well.

Does a Layout include information about column widths or pinning?

Yes - this can be provided in the Config and it will be saved automatically as the Layout changes.

What is the "Default Layout"?

This is a Layout that AdapTable will create on start-up based on the column definitions you provide - if you have not defined any Layouts in your Predefined Config.

Is every Layout editable and deletable?

Yes, assuming that your Entitlements Access Level property for Layouts is Full.

note

The only time a Layout cannot be deleted is if it's the last remaining in the State

More Information