html_url,issue_url,id,node_id,user,created_at,updated_at,author_association,body,reactions,issue,performed_via_github_app
https://github.com/simonw/datasette/pull/2052#issuecomment-1510423051,https://api.github.com/repos/simonw/datasette/issues/2052,1510423051,IC_kwDOBm6k_c5aBzoL,9020979,2023-04-16T16:12:14Z,2023-04-20T05:14:39Z,CONTRIBUTOR,"# Javascript Plugin Docs (alpha)
## Motivation
The Datasette JS Plugin API allows developers to add interactive features to the UI, without having to modify the Python source code.
## Setup
No external/NPM dependencies are needed.
Plugin behavior is coordinated by the Datasette `manager`. Every page has 1 `manager`.
There are 2 ways to add your plugin to the `manager`.
1. Read `window.__DATASETTE__` if the manager was already loaded.
```js
const manager = window.__DATASETTE__;
```
2. Wait for the `datasette_init` event to fire if your code was loaded before the manager is ready.
```js
document.addEventListener(""datasette_init"", function (evt) {
const { detail: manager } = evt;
// register plugin here
});
```
3. Add plugin to the manager by calling `manager.registerPlugin` in a JS file. Each plugin will supply 1 or more hooks with
- unique name (`YOUR_PLUGIN_NAME`)
- a numeric version (starting at `0.1`),
- configuration value, the details vary by hook. (In this example, `getColumnActions` takes a function)
```js
manager.registerPlugin(""YOUR_PLUGIN_NAME"", {
version: 0.1,
makeColumnActions: (columnMeta) => {
return [
{
label: ""Copy name to clipboard"",
// evt = native click event
onClick: (evt) => copyToClipboard(columnMeta.column),
}
];
},
});
```
There are 2 plugin hooks available to `manager.registerPlugin`:
- `makeColumnActions` - Add items to the cog menu for headers on datasette table pages
- `makeAboveTablePanelConfigs` - Add items to ""tabbed"" panel above the `
` on pages that use the Datasette table template.
While there are additional properties on the `manager`, but it's not advised to depend on them directly as the shape is subject to change.
4. To make your JS file available as a Datasette plugin from the Python side, you can add a python file resembling [this](https://github.com/simonw/datasette/pull/2052/files#diff-c5ecf3d22075a60d04a4e95da2e15c612cf1bc84e38d777b67ba60dbd156e293) to your plugins directory. Note that you could host your JS file anywhere, it doesn't have to be served from the Datasette statics folder.
I welcome ideas for more hooks, or feedback on the current design!
## Examples
See the [example plugins file](https://github.com/simonw/datasette/blob/2d92b9328022d86505261bcdac419b6ed9cb2236/datasette/static/table-example-plugins.js) for additional examples.
## Hooks API Guide
### `makeAboveTablePanelConfigs`
Provide a function with a list of panel objects. Each panel object should contain
1. A unique string `id`
2. A string `label` for the tab
3. A `render` function. The first argument is reference to an HTML [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element).
Example:
```js
manager.registerPlugin(""panel-plugin-graphs"", {
version: 0.1,
makeAboveTablePanelConfigs: () => {
return [
{
id: 'first-panel',
label: ""My new panel"",
render: node => {
const description = document.createElement('p');
description.innerText = 'Hello world';
node.appendChild(description);
}
}
];
},
});
```
### `makeColumnActions`
Provide a function that returns a list of action objects. Each action object has
1. A string `label` for the menu dropdown label
2. An onClick `render` function.
Example:
```js
manager.registerPlugin(""column-name-plugin"", {
version: 0.1,
getColumnActions: (columnMeta) => {
// Info about selected column.
const { columnName, columnNotNull, columnType, isPk } = columnMeta;
return [
{
label: ""Copy name to clipboard"",
onClick: (evt) => copyToClipboard(column),
}
];
},
});
```
The getColumnActions callback has access to an object with metadata about the clicked column. These fields include:
- columnName: string (name of the column)
- columnNotNull: boolean
- columnType: sqlite datatype enum (text, number, etc)
- isPk: Whether this is the primary key: boolean
You can use this column metadata to customize the action config objects (for example, handling different summaries for text vs number columns).
","{""total_count"": 0, ""+1"": 0, ""-1"": 0, ""laugh"": 0, ""hooray"": 0, ""confused"": 0, ""heart"": 0, ""rocket"": 0, ""eyes"": 0}",1651082214,