Providing Default Layout Properties

Summary

AdapTable provides default Layout properties which will be used in all Layouts created at run-time
Additional props can be applied to all Layouts (new & existing) to enhance / extend functionality seamlessly
The State Options functions can be leveraged to define these props at design-time for greater flexibility

AdapTable enables developers to configure default properties for both Table and Pivot Layouts.

These are then applied automatically to Layouts created at runtime.

Additionally, developers can extend all Layouts (new and existing) with custom properties to enhance functionality or patch existing configurations seamlessly.

Caution

This is different to the Default Layout that versions of AdapTable (prior to v.20) offered but which was removed
That was a full-blown Layout which AdapTable created if none was supplied

Default Creation Properties

Default creation properties are applied automatically to all new Table and Pivot Layouts created at runtime.

These properties ensure consistency across newly created Layouts without requiring manual configuration.

Note

Layouts created through Layout API will contain these properties (unless the property is explicitly overridden)
Layouts created via the UI wil show these properties in the Layout Wizard (allowing the user to change them)

This is done using the layoutCreationDefaultProperties property in Layout Options.

layoutCreationDefaultProperties

DefaultLayoutProperties

Sets default properties for new Layouts (Table or Pivot)

DefaultLayoutProperties

Provides a set of Default Properties for new Layouts (Table or Pivot).

The definition of the property is as follows:

layoutCreationDefaultProperties?:
    | LayoutCreationDefaultProperties
    | ((
        context: LayoutCreationDefaultPropertiesContext
      ) => TableLayoutCreationDefaultProperties | PivotLayoutCreationDefaultProperties);

As can be seen, the default properties can be provided as an object or via a function.

Providing an Object

It is possible to return a LayoutCreationDefaultProperties which contains default properties for Table and Pivot Layouts:

Property	Description
pivotLayout	Default properties to apply when creating a new Pivot Layout
tableLayout	Default properties to apply when creating a new Table Layout

// Provide default properties to be used im Table 
layoutOptions: {
  layoutCreationDefaultProperties: {
    tableLayout: {
      ColumnSorts: [
        {
          ColumnId: 'name',
          SortOrder: 'Asc',
        },
      ],
    },
    pivotLayout: {
      PivotAggregationColumns: [
        {
          ColumnId: 'github_stars',
          AggFunc: 'sum',
        },
        {
          ColumnId: 'github_watchers',
          AggFunc: 'sum',
        },
      ],
    },
  },
},

Using a Function

Alternatively you can provide a function which will return the object on a per-case basis.

The function receives LayoutCreationDefaultPropertiesContext which is defined as follows:

Property	Description
layoutType	Type of Layout ('table' \| 'pivot')
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

When using the function you return one of 2 objects:

DefaultTableLayoutProperties - set of Table Layout properties
DefaultPivotLayoutProperties - set of Pivot Layout properties

Caution

Neither of these objects allow you to provide a default Name property (since that has to be unique to the Layout)


  layoutOptions: {
    layoutCreationDefaultProperties: (context: LayoutCreationDefaultPropertiesContext) => {
      if (context.layoutType == 'table') {
        return {
          ColumnSorts: [
            {
              ColumnId: 'name',
              SortOrder: 'Asc',
            },
          ],
        };
      } else {
        return {
          PivotAggregationColumns: [
            {
              ColumnId: 'github_stars',
              AggFunc: 'sum',
            },
            {
              ColumnId: 'github_watchers',
              AggFunc: 'sum',
            },
          ],
        };
      }
    },
  },

Default Creation Props

Fork Fork

In this example we have provided default creation properties for both Table and Pivot Layouts:
- For Table Layouts - we default a on Name Column, and a Column Filter on Language Column
- For Pivot Layouts - we default Aggregations on Github Stars and Github Watchers Columns (suppressing the Agg Func), a GrandTotalRow at bottom and a PivotGrandTotal Column before

Try It Out

In the Layout Toolbar click to add a new Table Layout and note that the new Layout already contains the Column Sort and Column Filter defined in default props
Then click to add a new Pivot Layout and note that the new Layout already contains the Aggregations, GrandTotalRow and PivotGrand Total Column

import {
  AdaptableOptions,
  LayoutCreationDefaultPropertiesContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Default Layout Props',
  layoutOptions: {
    layoutCreationDefaultProperties: (
      context: LayoutCreationDefaultPropertiesContext
    ) => {
      if (context.layoutType == 'table') {
        return {
          ColumnSorts: [
            {
              ColumnId: 'name',
              SortOrder: 'Asc',
            },
          ],
          ColumnFilters: [
            {
              ColumnId: 'language',
              Predicates: [
                {
                  PredicateId: 'Is',
                  Inputs: ['TypeScript'],
                },
              ],
            },
          ],
          AutoSizeColumns: true,
        };
      } else {
        return {
          PivotAggregationColumns: [
            {
              ColumnId: 'github_stars',
              AggFunc: 'sum',
            },
            {
              ColumnId: 'github_watchers',
              AggFunc: 'sum',
            },
          ],
          SuppressAggFuncInHeader: true,
          GrandTotalRow: 'bottom',
          PivotGrandTotal: 'before',
        };
      }
    },
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['Layout', 'SettingsPanel'],
      PinnedToolbars: ['Layout'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Table Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'license',
            'language',
            'github_stars',
            'open_pr_count',
            'closed_issues_count',
            'created_at',
            'updated_at',
            'pushed_at',
            'created_at',
            'has_wiki',
            'github_watchers',
            'description',
            'open_issues_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            'week_issue_change',
          ],
          Name: 'Table Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Extending Initial State Layouts

AdapTable allows developers to enhance all Layouts (new and existing) by manipulating the Layout State.

This is most easily achieved by leveraging 2 State Options functions:

applyState - modifies the Layout state dynamically
saveState - controls how Layouts are persisted to avoid polluting the saved state with default configurations

Default Layout Props

Fork Fork

This example demonstrates how to create default layout properties in Initial State; we:
- Add a read-only All Columns Layout that includes all available columns with a default sort on name
- Prevent the default All Columns Layout from being persisted by filtering it out in the saveState function in State Options
- Apply a default descending sort on the github_stars column to all Layouts that do not contain a sort

import {AdaptablePersistentState, Layout} from '@adaptabletools/adaptable';
import {AdaptableOptions, TableLayout} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Default Layout Props',
  initialState: {
    Layout: {
      CurrentLayout: 'Custom Layout',
      Layouts: [
        {
          Name: 'Custom Layout',
          TableColumns: [
            'name',
            'license',
            'language',
            'description',
            'github_stars',
          ],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Dashboard: {
      ModuleButtons: ['Layout', 'SettingsPanel'],
      PinnedToolbars: ['Layout'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout'],
        },
      ],
    },
  },
  stateOptions: {
    applyState: (state, config) => {
      addAllColumnLayout(state);
      enhanceLayoutsWithDefaultSorting(state);
      return state;
    },
    saveState: (state, config) => {
      // remove the default layout before saving state
      // we don't want to pollute the persisted state with it
      state.Layout.Layouts = state.Layout?.Layouts?.filter(
        layout => layout.Metadata?.DEFAULT_PROP !== true
      ) as [Layout, ...Layout[]];
    },
  },
};

function addAllColumnLayout(state: Partial<AdaptablePersistentState>) {
  const ALL_COLS_LAYOUT: TableLayout = {
    Metadata: {
      DEFAULT_PROP: true,
    },
    IsReadOnly: true,
    Name: 'All Columns',
    TableColumns: [
      'name',
      'license',
      'language',
      'github_stars',
      'open_pr_count',
      'closed_issues_count',
      'created_at',
      'updated_at',
      'pushed_at',
      'created_at',
      'has_wiki',
      'github_watchers',
      'description',
      'open_issues_count',
      'closed_pr_count',
      'has_projects',
      'has_pages',
      'week_issue_change',
    ],
    ColumnSorts: [{ColumnId: 'name', SortOrder: 'Asc'}],
  };

  state.Layout?.Layouts?.push(ALL_COLS_LAYOUT);
}

function enhanceLayoutsWithDefaultSorting(
  state: Partial<AdaptablePersistentState>
) {
  state.Layout?.Layouts?.forEach(layout => {
    if (layout.ColumnSorts?.length) {
      return;
    }
    layout.ColumnSorts = [{ColumnId: 'github_stars', SortOrder: 'Desc'}];
  });
}

PreviousExtending Layouts NextSynchronising Layouts

Framework: