# OutlineApi

The Outline panel, headless: the bookmark tree, read whole and edited one bookmark at a time. A bookmark is addressed by its path — the indices that lead to it in the tree `get()` returns (`[0]` the first top-level bookmark, `[0, 2]` its third child). A viewer on the document follows each edit: its panel refreshes, it takes an undo step and fires [`documentChanged`](https://kernstra.com/docs/web-sdk/api/events#ev-documentchanged). The panel is described under [Document features](https://kernstra.com/docs/web-sdk/guides/document-features).

`get()` needs no feature, but without `extract` every title is `''`. `set`, `add`, `delete` and `setTitle` need the `edit-pages` feature and refuse with `FEATURE_NOT_LICENSED` without it. Each of the four refuses a certified document with `INVALID_STATE` unless `options.invalidateSignatures`: no certification level allows bookmark changes.

- Kind: namespace
- Access: `doc.outline`

## Usage

```ts
for (const chapter of await doc.outline.get()) {
  console.log(chapter.title, '→ page', chapter.pageIndex);
}
await doc.outline.add('Appendix', doc.pageCount - 1);
```

## Reading

### `get`

```ts
get(): Promise<OutlineNode[]>
```

The bookmark tree. Without the `extract` feature every title is `''`, so a tree read then and given back to `set` writes them blank: rename with `setTitle`. Needs no feature.

- Kind: method
- Since: 1.0.0

Returns `Promise<OutlineNode[]>`: Each `{ title, pageIndex, children }`; `pageIndex` is `null` when the bookmark has no page (it only groups children).

Throws:

- `DOCUMENT_CLOSED` — the document has been closed.

```ts
const chapters = await doc.outline.get();
```

Page: https://kernstra.com/docs/web-sdk/api/doc-outline/get

## Editing

### `set`

```ts
set(nodes: OutlineNode[], options?: SignedDocumentOptions): Promise<void>
```

Replace the whole tree. Keeps only titles, pages and nesting: each bookmark's zoom, color, style, other actions and open state are lost — use `add`, `delete` and `setTitle` for single edits, which change one bookmark and nothing else. Needs the `edit-pages` feature.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `nodes` | `OutlineNode[]` | The whole tree: `{ title, pageIndex, children }` each. |
| `options?` | `SignedDocumentOptions` | `{ invalidateSignatures? }`. |

Returns `Promise<void>`

Throws:

- `FEATURE_NOT_LICENSED` — the license lacks `edit-pages`.
- `PAGE_ERROR` — the change could not be written.
- `DOCUMENT_CLOSED` — the document has been closed.
- `INVALID_STATE` — a certified document, unless `options.invalidateSignatures` (no certification level allows bookmark changes); or a progressive document still downloading.

```ts
await doc.outline.set([
  { title: 'Cover', pageIndex: 0, children: [] },
  { title: 'Terms', pageIndex: 4, children: [{ title: 'Payment', pageIndex: 5, children: [] }] },
]);
```

Page: https://kernstra.com/docs/web-sdk/api/doc-outline/set

### `add`

```ts
add(title: string, pageIndex: number, options?: AddBookmarkOptions): Promise<number[]>
```

Add one bookmark, as the last child of the bookmark at `options.parentPath` (omitted: top level), going to `pageIndex`. Needs the `edit-pages` feature.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `title` | `string` | The bookmark's title. |
| `pageIndex` | `number` | The zero-based page it goes to. |
| `options?` | `AddBookmarkOptions` | `parentPath` (a path into `get()`'s tree; omitted, top level) and `invalidateSignatures`. |

Returns `Promise<number[]>`: The new bookmark's path, for `delete()` / `setTitle()`.

Throws:

- `INVALID_ARGUMENT` — a page index out of range, or a `parentPath` that names no bookmark.
- `FEATURE_NOT_LICENSED` — the license lacks `edit-pages`.
- `PAGE_ERROR` — the change could not be written.
- `DOCUMENT_CLOSED` — the document has been closed.
- `INVALID_STATE` — a certified document, unless `options.invalidateSignatures` (no certification level allows bookmark changes); or a progressive document still downloading.

```ts
const path = await doc.outline.add('Appendix', doc.pageCount - 1);
await doc.outline.add('Tables', doc.pageCount - 1, { parentPath: path });
```

Page: https://kernstra.com/docs/web-sdk/api/doc-outline/add

### `delete`

```ts
delete(path: number[], options?: SignedDocumentOptions): Promise<void>
```

Delete the bookmark at a path, its children with it. Needs the `edit-pages` feature.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | `number[]` | The bookmark's path into `get()`'s tree. |
| `options?` | `SignedDocumentOptions` | `{ invalidateSignatures? }`. |

Returns `Promise<void>`

Throws:

- `INVALID_ARGUMENT` — a `path` that names no bookmark.
- `FEATURE_NOT_LICENSED` — the license lacks `edit-pages`.
- `PAGE_ERROR` — the change could not be written.
- `DOCUMENT_CLOSED` — the document has been closed.
- `INVALID_STATE` — a certified document, unless `options.invalidateSignatures` (no certification level allows bookmark changes); or a progressive document still downloading.

```ts
await doc.outline.delete([0, 2]); // the first bookmark's third child
```

Page: https://kernstra.com/docs/web-sdk/api/doc-outline/delete

### `setTitle`

```ts
setTitle(path: number[], title: string, options?: SignedDocumentOptions): Promise<void>
```

Rename the bookmark at a path, in place. Needs the `edit-pages` feature.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | `number[]` | The bookmark's path into `get()`'s tree. |
| `title` | `string` | The new title. |
| `options?` | `SignedDocumentOptions` | `{ invalidateSignatures? }`. |

Returns `Promise<void>`

Throws:

- `INVALID_ARGUMENT` — a `path` that names no bookmark.
- `FEATURE_NOT_LICENSED` — the license lacks `edit-pages`.
- `PAGE_ERROR` — the change could not be written.
- `DOCUMENT_CLOSED` — the document has been closed.
- `INVALID_STATE` — a certified document, unless `options.invalidateSignatures` (no certification level allows bookmark changes); or a progressive document still downloading.

```ts
await doc.outline.setTitle([0], 'Introduction');
```

Page: https://kernstra.com/docs/web-sdk/api/doc-outline/settitle

Web page: https://kernstra.com/docs/web-sdk/api/doc-outline