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 `<table/>` 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,