Configuring Layouts

View as Markdown

Summary

  • layoutOptions on 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

Topics on this Page

TopicSummary
Layout Options catalogueWhere each layoutOptions property is documented
Layout View OptionsSettings Panel inline layout preview
Deleted special columnsRemove Calculated / FreeText columns from all Layouts
Suppressing Auto-SaveOptional manual Layout persistence
Discarding unsaved changesRoll 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.

PropertyPurposeHandbook
autoCreateLayoutFirst-run Layout from ColDefsDefault Layouts
layoutCreationDefaultPropertiesDefaults when users create a LayoutDefault Layouts
enableLayoutExtensionsUIUI to add/remove extended objectsExtending Layouts
isRowSelectionCheckboxVisiblePer-row selection checkbox visibilityTable Layouts — Row Selection
pivotPreviewColumnsExtra columns in pivot cell expand tablePivot Layouts
layoutViewOptions.maxColumnsToDisplayColumn names shown in Settings Panel layout previewLayout View Options (this page)
autoRemoveDeletedColumnsFromLayoutsDrop deleted special columns from LayoutsDeleted 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: 10
Number
How many column names to show in the inline Layout preview in Settings Panel

Deleted 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: true
Boolean
Remove deleted Calculated and FreeText columns from all Layouts

Suppressing 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:

  1. First Layout has columns A, B, C
  2. The user reorders them to C, B, A
  3. The user clones it as Second Layout (which keeps C, B, A)
  4. Switching back to First Layout shows A, B, C again

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.

Manually Saving Layouts
Fork
  • 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 State
    • Persist CURRENT Layout Changes — manually saves only the Current Layout
    • Undo Layout Changes — replaces any locally saved changes to Layouts with the last saved version in AdapTable State
    • Reset 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 Stars Column) are automatically persisted
Loading demo…