# Making Notes

Canonical page: https://www.adaptabletools.com/docs/handbook-notes

- Notes are annotations that are attached to AG Grid Cells
- They are designed for per-user use and are stored in AdapTable State

Notes are **personal annotations** that run-time users attach to individual **Cells** in AG Grid.

Each Cell can have only one Note attached (but it can be edited).

Notes are stored in [Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state/index.md), rather than with the Grid’s underlying data source.

- Notes differ from [Comments](https://www.adaptabletools.com/docs/handbook-comments/index.md) — Notes are personal; Comments are for colleague communication
- Notes differ from [Free Text Columns](https://www.adaptabletools.com/docs/handbook-freetext-column/index.md) — Notes annotate **single cells**; Free Text is a full **user-owned column**

Notes can be created in 2 ways:
- by run-time users using the [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md) (or `Shift + F2`) and adding Text
- by design-time developers through [Notes Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-notes/index.md)

- Notes are **not** available if you are using an [auto-generated Primary Key](https://www.adaptabletools.com/docs/getting-started-primary-key/index.md#auto-generated-key)
- Notes use AG Grid’s Notes feature — register AG Grid’s `NotesModule` (see [AG Grid Modules](https://www.adaptabletools.com/docs/getting-started-aggrid-modules/index.md))

### How Notes Work in AdapTable

AdapTable Notes are a wrapper around [AG Grid Cell Notes](https://www.ag-grid.com/javascript-data-grid/notes/).

AG Grid owns the in-cell indicator, the Note editor, hover / click to open, `Shift + F2`, and the Add / Edit / Remove / View Note [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md) items.

AdapTable keeps the Note as an object in [Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state/index.md), so Notes can still be:

- predefined in [Initial State](https://www.adaptabletools.com/docs/technical-reference-notes/index.md)
- persisted and [Team Shared](https://www.adaptabletools.com/docs/handbook-team-sharing/index.md)
- listed and edited in the Notes [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md)
- given a [Note Type](https://www.adaptabletools.com/docs/handbook-notes-configuring/index.md) (`Info`, `Warning`, `Error`, `Success`) that colours the cell indicator
- created, edited and deleted via [Note API](https://www.adaptabletools.com/docs/technical-reference-notes/index.md)

**Example: Notes in AdapTable**

Adding Notes to cells

- Four Notes in Initial State: two on `name`, two on `license` (see `adaptableOptions.ts`)
- Each Note has a [Note Type](https://www.adaptabletools.com/docs/handbook-notes-configuring/index.md), which colours the triangle in the cell

- Hover a noted Cell to read the Note (the default)
- Right-click a Cell and select *Add Note* — or press `Shift + F2` — to create a new Note
- Right-click a noted Cell and use *Set Note Type* to change the indicator colour
- Click the Note Dashboard button to see all the Notes that have been provided for this Grid

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,
  CustomContextMenuContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';
import {
  AdaptableContextMenuItemName,
  AdaptableSystemContextMenuItem,
} from '@adaptabletools/adaptable';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Notes',
  userName: 'Demo User',
  contextMenuOptions: {
    customContextMenu: (customMenuContext: CustomContextMenuContext) => {
      const agGridNote = customMenuContext.defaultAgGridMenuStructure.find(
        item => 'name' in item && item.name === 'note'
      );
      const adaptableNoteItems =
        customMenuContext.defaultAdaptableMenuStructure.filter(
          (
            item
          ): item is AdaptableSystemContextMenuItem<AdaptableContextMenuItemName> =>
            item !== '-' && item.category === 'Note'
        );
      return [...(agGridNote ? [agGridNote] : []), ...adaptableNoteItems];
    },
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['Note'],
    },
    Theme: {CurrentTheme: 'dark'},

    Note: {
      Notes: [
        {
          PrimaryKeyValue: 10270250,
          Text: 'We are using this Framework',
          ColumnId: 'name',
          Author: 'Demo User',
          NoteType: 'Info',
          CreatedAt: new Date().setDate(new Date().getDate() - 1),
        },
        {
          PrimaryKeyValue: 11730342,
          Text: 'Popular with the Accounts team',
          ColumnId: 'name',
          Author: 'Demo User',
          NoteType: 'Success',
          CreatedAt: new Date().setDate(new Date().getDate() - 2),
        },
        {
          PrimaryKeyValue: 82095231,
          Text: 'Need to find out Stencil license',
          ColumnId: 'license',
          Author: 'Demo User',
          NoteType: 'Warning',
          CreatedAt: new Date().setDate(new Date().getDate() - 3),
        },
        {
          PrimaryKeyValue: 5532320,
          Text: 'Need to find out Polymer license',
          ColumnId: 'license',
          Author: 'Demo User',
          NoteType: 'Error',
          CreatedAt: new Date().setDate(new Date().getDate() - 4),
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'github_stars',
            'license',
            'github_watchers',
            'language',
            'open_issues_count',
            'closed_issues_count',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'description',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Defining Notes

Notes can be defined by developers at design-time using [Notes Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-notes/index.md).

### Defining a Note

Each `Note` object requires the Text, the Column and the [Primary Key](https://www.adaptabletools.com/docs/getting-started-primary-key/index.md). A created-at timestamp is optional:

This is the [Primary Key](https://www.adaptabletools.com/docs/getting-started-primary-key/index.md) value for the row containing the Note

The actual contents of the Note

The Id of the Column that contains the cell

When the Note was first written (milliseconds). AdapTable stamps this automatically if omitted.

```ts [[1, 5, "PrimaryKeyValue"], [1, 11, "PrimaryKeyValue"], [2, 6, "Text"], [2, 12, "Text"], [3, 7, "ColumnId"], [3, 13, "ColumnId"], [4, 8, "CreatedAt"]]
initialState: {
  Note: {
    Notes: [
      {
        PrimaryKeyValue: 10270250,
        Text: 'We are using this Framework',
        ColumnId: 'name',
        CreatedAt: Date.now(),
      },
      {
        PrimaryKeyValue: 82095231,
        Text: 'Need to find out Stencil license',
        ColumnId: 'license',
      },
    ],
  },
},
```

- Other optional properties include `Author` (defaults to `adaptableOptions.userName`), `UpdatedAt`, & `IsReadOnly`
- There is also a `NoteType` property (`Info` by default) which users can edit at run-time

## Using Notes

Notes can be added by run-time users of AdapTable.

### Creating Notes in AdapTable

Creating / Editing a Note is straightforward:

Notes are attached to Cells so first select the desired Cell.

Right-click to open the [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md) and choose *Add Note*, or press `Shift + F2`.

Type the text in the Note editor that appears. Closing the editor (click away or press Escape) saves the Note.

Hover a noted Cell to read its Note (or right-click and choose *View Note* / *Edit Note*).

The Notes page in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md), the Notes Dashboard button, and the Notes [Status Bar](https://www.adaptabletools.com/docs/ui-status-bar/index.md) list every Note in State.

There you can edit the Text inline, change the Type, and see Created / Last Updated timestamps.

## Exporting Notes

Notes are exported as cell comments in `Excel` and `VisualExcel` [Reports](https://www.adaptabletools.com/docs/handbook-exporting-reports-format-type-excel/index.md#notes).

## UI Entitlements

The UI Entitlements behaviour for Notes is as expected for `Full` and `Hidden` [`Access Levels`](https://www.adaptabletools.com/docs/reference/accesslevel.md).

The `ReadOnly` Entitlement behaviour is that Notes provided in Initial State will be visible but they cannot be edited nor deleted, and new Notes cannot be added.

### FAQ

**Can I share my Notes with colleagues through Team Sharing?**
Technically you can, but for that use case we recommend [Comments](https://www.adaptabletools.com/docs/handbook-comments/index.md), which are designed for collaboration.
