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.
By default Layouts will save automatially when their contents change - and there must always be one active Layout in AdapTable.
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 Definitions include a number of important properties including:
Sorting Information (including for multiple columns)
Aggregation Information (e.g. which columns will display an aggregation number in a grouped row)
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.
In AdapTable you are able to manipulate Layouts in multiple ways including:
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
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).
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.
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
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
AdapTable must always have at least one Layout - which will automatically get updated as the grid changes.
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.
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
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.
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
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.
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)
The Layout Api section of AdapTable API has a number of methods to enable you to create, edit, clone, delete and retrieve layouts programmatically.
The Layout Options of AdapTable Options contains a range of useful properties to enable Layout usage to be configured to particular requirements.
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.
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.