Layout

The Layout Function facilities creating Layouts (a.k.a. Views) - essentially a way of managing columns designed to enable users easily to switch between different 'views' of their grid

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

important

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

note

Version 7 of AdapTable made significant improvements to Layouts - see the Upgrade Guide for more information and the migration path it offers for Layouts from previous versions.

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.

Managing Layouts

In AdapTable you are able to manipulate Layouts in multiple ways including:

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

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 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 Layouts in Predefined Config.

Persisting Expanded Grouped Rows

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 / restoring / deleting.

  • Tool Panel - Same as Toolbar above.

Entitlements

Layout Entitlement Rules:

  • Full: All Layouts are available to the User

  • ReadOnly: User can select Layouts that have been provided in Predefined Config but cannot edit or delete them, nor add others.

  • Hidden: All Layouts are hidden from the User

    note

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

Layout Predefined Config

The Layout Predefined Config of Layout State facilitates the creation of Layouts at design-time.

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 API

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

Layout Options

The Layout Options of AdapTable Options contains a range of useful properties to enable Layout usage to be configured to particular requirements.

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

What happened to the old Column Chooser?

Layouts received a big makeover in Version 7 of AdapTable including a much improved Layout Editor which removed the need for a separate Column Chooser screen.

More Information