issue_comments: 1510423051
This data as json
| 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 | NONE | # 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 |