# Plugin API reference

The SDK's [types.d.ts](https://github.com/thymerapp/thymer-plugin-sdk/blob/main/types.d.ts) is the full reference, with every signature and comment. This page lists the main objects and methods. The API is still changing during the beta; check the declarations that match your app version.

## Plugin classes

`AppPlugin` for the workspace, `CollectionPlugin` for one collection, `DynCollectionPlugin` for a dynamic collection. `onLoad()` is where you register things; `onUnload()` is where you clean up. All of them have `ui`, `data`, `events`, `ws` and `window`; collection plugins also have `collection`, `properties` and `views`.

## Data

| Method | Returns |
| --- | --- |
| `this.data.getRecord(guid)` | A record, or `null` |
| `this.data.getAllRecords()` | Every record in the workspace |
| `await this.data.getAllCollections()` | The collections |
| `this.data.getActiveUsers()` | The workspace's users |
| `await this.data.searchByQuery(query, max)` | Matching records and lines |
| `this.data.getPluginByGuid(guid)` | A plugin or collection object |

```js
const results = await this.data.searchByQuery("@task @overdue", 50);
for (const record of results.records) console.log(record.getName());
```

In a collection plugin, `await this.collection.getAllRecords()` loads its records and `this.collection.createRecord(title)` makes a new one, returning its guid.

## Records

A record is a page. `guid`, `getName()`, `getCreatedAt()`, `getUpdatedAt()`, `getAsMarkdown()`, `getSubPageOf()` and `setSubPageOf(guid)`, and `await record.getLineItems()` for its lines.

| Reader | Returns |
| --- | --- |
| `record.number(name)`, `record.text(name)` | A number or text, or `null` |
| `record.choice(name)` | The choice id, or `null` |
| `record.numbers(name)`, `record.texts(name)` | All values of a multi-value property |
| `record.users(name)` | User objects |
| `record.linkedRecord(name)`, `record.linkedRecords(name)` | One linked record, or all of them |

Choices have an id and a label: `PluginProperty.choiceLabel()` gives the label, `setChoice()` takes the label. Setters are asynchronous and return whether they succeeded.

## Lines

A `PluginLineItem` knows its parent and children, its text segments and its task status. `setSegments()` replaces the content, `setTaskStatus()` changes the checkbox. A line's text is made of segments, including references; replace only the segments you mean to change.

## Properties and views

`this.properties.formula(name, fn)`, `render()`, `customSort()` and the choice hooks are described in [Collection plugins](collection-plugins.md), together with `this.views.register(name, fn)` and the view hooks `onLoad`, `onRefresh` and `onDestroy`. `await this.views.getAllRecordsInView(name)` returns a view's records with its filter and sort applied.

## Interface

`this.ui.addCommandPaletteCommand()`, `addStatusBarItem()`, `addToaster()`, `addSidebarWidget()`, `registerCustomPanelType()`, plus buttons, icons and tooltips that follow the theme. `this.ui.getActivePanel()` returns the active panel, or `null`, and a panel may have no record. Use the text APIs for anything a user typed; only pass HTML you built yourself to the HTML APIs.

Desktop window APIs only exist in the desktop app; check before calling them.