Configuring Layouts
Summary
layoutOptionson Adaptable Options configure Layout behaviour that is not stored in Layout State- Includes auto-creation, default properties on new layouts, row-selection checkboxes, pivot cell previews, extensions UI, and Settings Panel layout list preview
- Advanced manual Layout persistence uses State Options together with Layout API — see Suppressing Auto-Save below
Find Out More
Layouts · Topics in this Section. Layout State and API — Layout Technical Reference.
Topics on this Page
| Topic | Summary |
|---|---|
| Layout Options catalogue | Where each layoutOptions property is documented |
| Layout View Options | Settings Panel inline layout preview |
| Deleted special columns | Remove Calculated / FreeText columns from all Layouts |
| Suppressing Auto-Save | Optional manual Layout persistence |
| Discarding unsaved changes | Roll back a Layout when the user switches away |
Layout Options Catalogue
Most layoutOptions properties have dedicated handbook pages so this section does not repeat their full behaviour.
| Property | Purpose | Handbook |
|---|---|---|
autoCreateLayout | First-run Layout from ColDefs | Default Layouts |
layoutCreationDefaultProperties | Defaults when users create a Layout | Default Layouts |
enableLayoutExtensionsUI | UI to add/remove extended objects | Extending Layouts |
isRowSelectionCheckboxVisible | Per-row selection checkbox visibility | Table Layouts — Row Selection |
pivotPreviewColumns | Extra columns in pivot cell expand table | Pivot Layouts |
layoutViewOptions.maxColumnsToDisplay | Column names shown in Settings Panel layout preview | Layout View Options (this page) |
autoRemoveDeletedColumnsFromLayouts | Drop deleted special columns from Layouts | Deleted special columns (this page) |
Note
Do not set layoutTagOptions — extend objects with LayoutExtensions on Layout State. See Extending Layouts.
Layout View Options
layoutViewOptions controls how Layouts appear in the Settings Panel list (not column behaviour inside the grid).
layoutViewOptions.maxColumnsToDisplay
Default: 10NumberDeleted Special Columns
When a Calculated Column or FreeText Column is deleted, AdapTable can remove that column from every Layout (column lists, sorts, grouping, and other Layout properties).
autoRemoveDeletedColumnsFromLayouts
Default: trueBooleanSuppressing Auto-Save
Layouts, like all AdapTable objects, save automatically as soon as they are changed.
Whenever a Column is grouped, resized, pinned etc, the change is immediately persisted to AdapTable State.
Sometimes this is not desired behaviour, and developers prefer to manually control when a Layout is saved.
In other words, run-time users can only make temporary changes to Layouts, and the actual state persistence is imperatively driven.
The persistState function in State Options is used to write a snapshot of last-saved Layouts instead of the running Layout State.
Other AdapTable objects (e.g. Format Columns) continue to persist automatically.
Developers can then persist Layouts on demand:
- Persist ALL Layout Changes — save every Layout in the running State
- Persist CURRENT Layout Changes — merge only the Current Layout into the snapshot
Discarding Unsaved Changes
A common requirement is that unsaved edits are lost when the user leaves a Layout.
For example:
First Layouthas columnsA,B,C- The user reorders them to
C,B,A - The user clones it as
Second Layout(which keepsC,B,A) - Switching back to
First LayoutshowsA,B,Cagain
This is implemented by listening to the Layout Changed Event and, on a LAYOUT_SELECT, restoring the abandoned Layout from the last persisted snapshot via createOrUpdateLayout in Layout API.
If the abandoned Layout is not in the snapshot (e.g. a freshly cloned Layout), it is left as-is.
Note
This demo is a cut down version from examples in the Guide to Controlling AdapTable State Persistence. See the demos there for full explanations of this advanced topic.
Caution
This pattern only works with a custom persistState hook.
In a default setup there is no "last saved" Layout to roll back to.
- In this demo we prevent the auto-saving of Layouts
- Changes to Layouts stay local until they are explicitly persisted; we keep a snapshot of last-saved Layouts and provide 4 Dashboard Buttons:
Persist ALL Layout Changes— manually saves every Layout to AdapTable StatePersist CURRENT Layout Changes— manually saves only the Current LayoutUndo Layout Changes— replaces any locally saved changes to Layouts with the last saved version in AdapTable StateReset Layout Changes— replaces any locally saved changes to Layouts with the initial version in AdapTable State
- Switching away from a Layout discards its unsaved changes (the Layout is restored from the last persisted snapshot). A freshly cloned Layout is left as-is because it is not yet in that snapshot
- Note: only Layouts are not auto-saved — changes to other objects (e.g. changing the back colour of the Format Column on the
Github StarsColumn) are automatically persisted