# Dashboard Buttons

Canonical page: https://www.adaptabletools.com/docs/ui-dashboard-buttons

- Dashboard Buttons provide shortcuts to regularly used functionality in AdapTable
- There are 2 sets available:
  - Module Buttons - System buttons shipped by AdapTable which open the Module's Settings Panel section
  - Custom Buttons - provided by Developers which can perform any action when clicked

The AdapTable Dashboard can include buttons - shortcuts to particular actions.

- These are **not** the same Buttons which are rendered inside [Custom Toolbars](https://www.adaptabletools.com/docs/ui-dashboard-custom-toolbars/index.md)
- Instead, these are Buttons which are displayed in the top part of the Dashboard itself

Dashboard Buttons can be of 2 types:

- (System) Module Buttons - provided by AdapTable
- Custom Buttons - supplied by developers

## Module Buttons

These are System Buttons supplied by AdapTable.

There is one Button (of type [Adaptable Button](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md)) for each [AdapTable Module](https://www.adaptabletools.com/docs/technical-reference-adaptable-modules/index.md).

- The Dashboard always shows a **Home control** that opens the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md) — it is not a Module Button
- By default no Module Buttons are displayed; add them in Dashboard State if you want shortcuts to specific Modules

When a Module Button is clicked, AdapTable opens that Module’s page in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md).

**Example: Dashboard: Module Buttons**

Displaying Module Buttons in the Dashboard

- This example illustrates how to provide Module Buttons in the Dashboard
- It sets 4 Module Buttons - `FormatColumn`, `DataChangeHistory`, `CalculatedColumn` and `Shortcut`
### Expand to see how the Module Buttons are provided

The 4 Module Buttons are provided in Dashboard Initial State:
```tsx
initialState: {
  Dashboard: {
   ModuleButtons: ['FormatColumn', 'DataChangeHistory', 'CalculatedColumn', 'Shortcut' ],
  },
},
```

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Dashboard Module Buttons',
  initialState: {
    Dashboard: {
      ModuleButtons: [
        'FormatColumn',
        'DataChangeHistory',
        'CalculatedColumn',
        'Shortcut',
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Custom Buttons

Custom Dashboard Buttons are standard [Adaptable Buttons](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md) provided by Developers at design-time.

They are supplied in the `customDashboardButtons` property in [Dashboard Options](https://www.adaptabletools.com/docs/technical-reference-dashboard/index.md).

### `customDashboardButtons`

Custom Buttons to show in the Dashboard Header

  [`AdaptableButton<DashboardButtonContext>`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)

The `customDashboardButtons` property of [Dashboard Options](https://www.adaptabletools.com/docs/technical-reference-dashboard/index.md) enables developers to supply a group of custom [Adaptable Buttons](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md) which will appear in the Dashboard Header.

```ts
const adaptableOptions: AdaptableOptions = {
  dashboardOptions: {
    customDashboardButtons: [
      {
        label: 'First',
        buttonStyle: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          return context.dashboardState.ActiveTabIndex == 0
            ? {
                variant: 'raised',
                tone: 'info',
              }
            : {
                variant: 'outlined',
                tone: 'success',
              };
        },
        icon: {
          height: 30,
          src: 'https://img.icons8.com/ios-glyphs/30/000000/sort.png',
        },
        onClick: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          console.log('button onClick function', {button, context});
        },
        hidden: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          return context.dashboardState.IsCollapsed != true;
        },
      },
      {
        label: 'Second',
        buttonStyle: {
          variant: 'raised',
          tone: 'accent',
        },
        onClick: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          console.log('button onClick function', {button, context});
        },
      },
      {
        label: 'cb3',
        buttonStyle: {
          variant: 'raised',
          tone: 'accent',
        },
        icon: {
          height: 20,
          src: 'https://img.icons8.com/ios-glyphs/30/000000/sort.png',
        },
        onClick: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          console.log('button onClick function', {button, context});
        },
      },
    ],
  },
};
```

- Any Custom Button provided in Dashboard Options will be **automatically** displayed in the Dashboard
- There is no requirement (or ability) to reference it in Dashboard Initial State - it appears anyway
- Equally there is no ability for run-time users to hide a Custom Button (like they can with Module Buttons)

### Custom Dashboard Buttons

As with all Adaptable Buttons, the button can be styled to user requirements with many properties and functions available to configure visibility, styling, onClick and other features.

All the Button's functions receive as context a bespoke [`DashboardButtonContext`](https://www.adaptabletools.com/docs/reference/customtoolbarbuttoncontext.md) object which contains a single property:

| Property | Type | Description |
| --- | --- | --- |
| [dashboardState](https://www.adaptabletools.com/docs/reference/dashboardbuttoncontext.md#dashboardstate) | [`DashboardState`](https://www.adaptabletools.com/docs/reference/dashboardstate.md) | Current Dashboard State |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/dashboardbuttoncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

Custom Dashboard Buttons will perform bespoke actions when clicked.

- Remember to provide an implementation for the Button's `onClick` property
- Otherwise nothing will happen when the Button is clicked

**Example: Dashboard: Custom Buttons**

Displaying Custom Buttons in the Dashboard

- This example illustrates how to provide Custom Buttons in the Dashboard. There are 2 Custom Buttons:
  - to show the time
  - to change the theme (this button changes based on whether the Dark or Light Theme is currently applied)
### Expand to see how the Custom Buttons are provided

The 2 Custom Buttons are defined in Dashboard Options:
```tsx
dashboardOptions: {
  customDashboardButtons: [
    {
      label: (
        button: AdaptableButton<DashboardButtonContext>,
        context: DashboardButtonContext
      ) => {
        return context.adaptableApi.themeApi.getCurrentTheme() == 'light'
          ? 'Dark Theme'
          : 'Light Theme';
      },
      onClick: (
        button: AdaptableButton<DashboardButtonContext>,
        context: DashboardButtonContext
      ) => {
        context.adaptableApi.themeApi.getCurrentTheme() == 'light'
          ? context.adaptableApi.themeApi.loadDarkTheme()
          : context.adaptableApi.themeApi.loadLightTheme();
      },
      buttonStyle: {
        tone: 'accent',
        variant: 'raised',
      },
    },
    {
      label: 'Current Time',
      onClick: (
        button: AdaptableButton<DashboardButtonContext>,
        context: DashboardButtonContext
      ) => {
        context.adaptableApi.alertApi.showAlertInfo(
          'Current Time',
          new Date().toTimeString()
        );
      },
      buttonStyle: {
        tone: 'info',
        variant: 'text',
      },
    },
  ],
},
```

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {
  AdaptableButton,
  AdaptableOptions,
  DashboardButtonContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Dashboard Custom Buttons',
  dashboardOptions: {
    customDashboardButtons: [
      {
        label: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          return context.adaptableApi.themeApi.getCurrentTheme() == 'light'
            ? 'Dark Theme'
            : 'Light Theme';
        },

        onClick: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          context.adaptableApi.themeApi.getCurrentTheme() == 'light'
            ? context.adaptableApi.themeApi.loadDarkTheme()
            : context.adaptableApi.themeApi.loadLightTheme();
        },
        buttonStyle: {
          tone: 'accent',
          variant: 'raised',
        },
      },
      {
        label: 'Current Time',
        onClick: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          context.adaptableApi.alertApi.showAlertInfo(
            'Current Time',
            new Date().toTimeString()
          );
        },
        buttonStyle: {
          tone: 'info',
          variant: 'text',
        },
      },
    ],
  },
  initialState: {
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Setting Buttons Location

By default the Dashboard will display all Module and Custom buttons on the right hand side.

The `buttonsLocation` property of Dashboard Options can be used to display them on the left.

### `buttonsLocation`

Where in Dashboard to display Module and Custom Buttons

Set this property to 'left' if you would prefer to display the Dashboard Buttons in the left corner - before the Title.

```ts {4}
// Show Module and Custom Buttons on left side of Dashboard
const adaptableOptions: AdaptableOptions = {
  dashboardOptions: {
    buttonsLocation: 'left',
  },
};
```

### FAQ

**Is there a limit to the amount of Module buttons that I can show?**
No, you can choose to show as many as you want.

**Why can't I remove the Settings Panel control from the Dashboard?**
The Dashboard Home control always opens the Settings Panel (unless that Module is `Hidden`). It is not a Module Button and is not listed in `ModuleButtons`.

**Can I hide Custom Dashboard Buttons at run-time?**
No, you can only set the visibility (and order) of Module Buttons.
Custom Buttons have a `hidden` property which can be provided by developers to manage button visibility
