.. _javascript_plugins: JavaScript plugins ================== Datasette can run custom JavaScript in several different ways: - Datasette plugins written in Python can use the :ref:`extra_js_urls() ` or :ref:`extra_body_script() ` plugin hooks to inject JavaScript into a page - Datasette instances with :ref:`custom templates ` can include additional JavaScript in those templates - The ``extra_js_urls`` key in ``datasette.yaml`` :ref:`can be used to include extra JavaScript ` There are no limitations on what this JavaScript can do. It is executed directly by the browser, so it can manipulate the DOM, fetch additional data and do anything else that JavaScript is capable of. .. warning:: Custom JavaScript has security implications, especially for authenticated Datasette instances where the JavaScript might run in the context of the authenticated user. It's important to carefully review any JavaScript you run in your Datasette instance. .. _javascript_datasette_init: The datasette_init event ------------------------ Datasette emits a custom event called ``datasette_init`` when the page is loaded. This event is dispatched on the ``document`` object, and includes a ``detail`` object with a reference to the :ref:`datasetteManager ` object. Your JavaScript code can listen out for this event using ``document.addEventListener()`` like this: .. code-block:: javascript document.addEventListener("datasette_init", function (evt) { const manager = evt.detail; console.log("Datasette version:", manager.VERSION); }); .. _javascript_datasette_manager: datasetteManager ---------------- The ``datasetteManager`` object ``VERSION`` - string The version of Datasette ``plugins`` - ``Map()`` A Map of currently loaded plugin names to plugin implementations ``registerPlugin(name, implementation)`` Call this to register a plugin, passing its name and implementation ``makeColumnField(context)`` Calls the ``makeColumnField()`` hook on registered plugins, returning the first custom insert/edit field control that matches the provided field context. This is used internally by Datasette's row insert and edit dialogs. ``createModal(options)`` Creates a :ref:`\ ` element, appends it to the page and returns it. Returns ``null`` in browsers without ```` support. ``selectors`` - object An object providing named aliases to useful CSS selectors, :ref:`listed below ` .. _javascript_plugins_datasette_modal: Modal dialogs: the datasette-modal element ------------------------------------------ Datasette provides a ```` Web Component that renders a modal dialog in the same visual style as Datasette's own dialogs - the create/alter table dialogs, the insert/edit/delete row dialogs, the column chooser, the mobile column actions sheet and the ``/`` jump menu are all built on it. The element, and the ``DatasetteModal`` class exposed as ``window.DatasetteModal``, are a stable public API for plugins. Plugins that need a modal dialog should use this component rather than building their own, so their dialogs automatically match Datasette's styling, keyboard handling and accessibility behavior. The component wraps a native ```` element and provides: - Datasette's standard modal frame: sizing, rounded corners, backdrop, open/close animations and an optional header with a title and a "meta" chip - Close on backdrop click and on the ``Escape`` key - A ``busy`` property that blocks the user from dismissing the dialog while a save or delete is in flight - A ``closeGuard`` hook for "Discard unsaved changes?" style confirmation prompts - Focus restoration to the triggering element when the dialog closes - ``datasette-modal-open`` and ``datasette-modal-close`` events Creating a modal ~~~~~~~~~~~~~~~~ The simplest way to create a modal from a plugin is ``datasetteManager.createModal()`` (or the equivalent ``window.DatasetteModal.create()``), which creates the element, appends it to ``document.body`` and returns it: .. code-block:: javascript document.addEventListener("datasette_init", function (event) { const manager = event.detail; const modal = manager.createModal({ id: "my-plugin-dialog", className: "my-plugin-dialog", title: "My plugin", content: `

Hello from a plugin!

`, }); if (!modal) { return; // Browser does not support } modal.dialog .querySelector(".my-plugin-cancel") .addEventListener("click", () => modal.requestClose("cancel")); // Open it later, for example from a button click: // modal.showModal({trigger: button}); }); Calling ``modal.showModal()`` then displays the dialog: .. image:: datasette-modal-example.png :alt: A modal dialog titled "My plugin" containing the text "Hello from a plugin!" and Cancel and Save buttons, shown over a dimmed and blurred Datasette table page. :width: 550px ``createModal(options)`` / ``DatasetteModal.create(options)`` accepts: ``id`` - string, optional ``id`` attribute for the inner ```` element. ``className`` - string, optional ``class`` attribute for the inner ````, useful for scoping custom CSS. ``title`` - string, optional Text for the standard header title. If omitted no header is created and the modal content fills the whole dialog. ``meta`` - string, optional Text for the small "meta" chip shown on the right of the header, for example ``"3 of 12 selected"``. ``titleId`` - string, optional ``id`` for the generated title element. Defaults to ``"-title"``. ``labelledBy`` / ``describedBy`` - strings, optional Explicit ``aria-labelledby`` / ``aria-describedby`` values for the dialog. By default the dialog is labelled by the generated title element. ``content`` - string or DOM node, optional Content placed inside the dialog, after the header. By convention this ends with a ``
`` containing an optional ```` and buttons using the ``btn`` classes shown above. ``parent`` - element, optional Element to append the modal to. Defaults to ``document.body``. The element can also be used declaratively in a template - light DOM children become the dialog content: .. code-block:: html

Dialog content

 The ``dialog-id``, ``dialog-class``, ``modal-title``, ``modal-meta``, ``title-id``, ``labelled-by`` and ``described-by`` attributes correspond to the options above. ``modal-title`` and ``modal-meta`` can be updated at any time and the header will update to match. Properties, methods and events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``DatasetteModal.supported`` - boolean, static True if the browser supports everything the component needs. ``createModal()`` returns ``null`` when this is false. ``modal.dialog`` - ``HTMLDialogElement`` The underlying native dialog element. Query this for elements inside the modal. ``modal.open`` - boolean True while the modal is open. ``modal.showModal(options)`` Opens the modal. ``options.trigger`` is the element that focus should return to when the modal closes - it defaults to the element that was focused when ``showModal()`` was called. ``modal.close(options)`` Closes the modal unconditionally, skipping ``busy`` and ``closeGuard``. Pass ``{restoreFocus: false}`` to leave focus where it is, for example when the page is about to navigate. ``modal.requestClose(reason)`` Asks the modal to close on the user's behalf, respecting ``busy`` and ``closeGuard``. Returns true if the modal closed. Backdrop clicks and the ``Escape`` key call this internally with reasons ``"backdrop"`` and ``"escape"``. Wire Cancel buttons to this method. ``modal.busy`` - boolean While true, ``Escape``, backdrop clicks and ``requestClose()`` will not close the modal. Set this while an operation is in flight. A ``busy`` attribute is reflected on the element for CSS. ``modal.closeGuard`` - function or null If set, called with the reason string whenever the user tries to dismiss the modal. Return false to keep the modal open - for example after a ``confirm("Discard unsaved changes?")`` returns false. Not consulted by direct ``close()`` calls. ``modal.setTitle(text)`` / ``modal.setMeta(text)`` Update the header title and meta chip. Setting the meta text to ``""`` hides the chip. ``modal.titleElement`` and ``modal.metaElement`` expose the underlying elements for richer markup. The element dispatches two bubbling events: ``datasette-modal-open`` Fired when the modal opens. ``datasette-modal-close`` Fired when the modal closes, however that happened. Use this to reset dialog state. Styling ~~~~~~~ Modal content uses light DOM, so page-level CSS and plugin CSS can style it directly. The component provides the frame plus styles for these conventional class names inside it: ``.modal-header``, ``.modal-title``, ``.modal-meta``, ``.modal-footer``, ``.footer-info`` and the button classes ``.btn``, ``.btn-primary``, ``.btn-ghost`` and ``.btn-danger``. Sizing can be customized with CSS custom properties on the dialog: .. code-block:: css dialog.my-plugin-dialog { --datasette-modal-width: min(700px, calc(100vw - 32px)); --datasette-modal-max-height: min(600px, calc(100vh - 32px)); } The dialog frame also respects the page-wide theme properties ``--modal-border-radius``, ``--modal-shadow``, ``--modal-backdrop-bg``, ``--modal-backdrop-blur`` and ``--modal-animation-duration``. ```` also works inside the shadow DOM of other Web Components - Datasette's own ```` and ```` components use it this way. The shared frame styles are automatically adopted into whichever document or shadow root the element is connected to. .. _javascript_plugin_objects: JavaScript plugin objects ------------------------- JavaScript plugins are blocks of code that can be registered with Datasette using the ``registerPlugin()`` method on the :ref:`datasetteManager ` object. The ``implementation`` object passed to this method should include a ``version`` key defining the plugin version, and one or more of the following named functions providing the implementation of the plugin: .. _javascript_plugins_makeJumpSections: makeJumpSections(context) ~~~~~~~~~~~~~~~~~~~~~~~~~ This method should return a JavaScript array of objects defining additional sections to be added to the blank state of the ``/`` jump menu, before the user starts typing a search. It should return an array of objects, each with the following: ``id`` - string A unique string ID for the section, for example ``agent-chat`` ``render(node, context)`` - function A function that will be called with a DOM node to render the section into Datasette passes a ``context`` object to both ``makeJumpSections(context)`` and ``render(node, context)``. It has the following keys: ``navigationSearch`` The ```` custom element instance. ``container`` - only for ``render()`` The ``.results-container`` element used by the jump menu. ``input`` - only for ``render()`` The ``.search-input`` element used by the jump menu. This example shows how a plugin might add a button for starting a new chat: .. code-block:: javascript document.addEventListener('datasette_init', function(ev) { ev.detail.registerPlugin('agent-plugin', { version: 0.1, makeJumpSections: (context) => { return [ { id: 'agent-chat', render: (node, context) => { node.innerHTML = ''; node.querySelector('button').addEventListener('click', () => { location.href = '/-/agent/new'; }); } } ]; } }); }); .. _javascript_plugins_makeAboveTablePanelConfigs: makeAboveTablePanelConfigs() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This method should return a JavaScript array of objects defining additional panels to be added to the top of the table page. Each object should have the following: ``id`` - string A unique string ID for the panel, for example ``map-panel`` ``label`` - string A human-readable label for the panel ``render(node)`` - function A function that will be called with a DOM node to render the panel into This example shows how a plugin might define a single panel: .. code-block:: javascript document.addEventListener('datasette_init', function(ev) { ev.detail.registerPlugin('panel-plugin', { version: 0.1, makeAboveTablePanelConfigs: () => { return [ { id: 'first-panel', label: 'First panel', render: node => { node.innerHTML = '

My custom panel

This is a custom panel that I added using a JavaScript plugin

'; } } ] } }); }); When a page with a table loads, all registered plugins that implement ``makeAboveTablePanelConfigs()`` will be called and panels they return will be added to the top of the table page. .. _javascript_plugins_makeColumnActions: makeColumnActions(columnDetails) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This method, if present, will be called when Datasette is rendering the cog action menu icons that appear at the top of the table view. By default these include options like "Sort ascending/descending" and "Facet by this", but plugins can return additional actions to be included in this menu. The method will be called with a ``columnDetails`` object with the following keys: ``columnName`` - string The name of the column ``columnNotNull`` - boolean True if the column is defined as NOT NULL ``columnType`` - string The SQLite data type of the column ``isPk`` - boolean True if the column is part of the primary key It should return a JavaScript array of objects each with a ``label`` and ``onClick`` property: ``label`` - string The human-readable label for the action ``onClick(evt)`` - function A function that will be called when the action is clicked The ``evt`` object passed to the ``onClick`` is the standard browser event object that triggered the click. This example plugin adds two menu items - one to copy the column name to the clipboard and another that displays the column metadata in an ``alert()`` window: .. code-block:: javascript document.addEventListener('datasette_init', function(ev) { ev.detail.registerPlugin('column-name-plugin', { version: 0.1, makeColumnActions: (columnDetails) => { return [ { label: 'Copy column to clipboard', onClick: async (evt) => { await navigator.clipboard.writeText(columnDetails.columnName) } }, { label: 'Alert column metadata', onClick: () => alert(JSON.stringify(columnDetails, null, 2)) } ]; } }); }); .. _javascript_plugins_makeColumnField: makeColumnField(context) ~~~~~~~~~~~~~~~~~~~~~~~~ This method, if present, can provide a custom form field for a column in Datasette's row insert and edit dialogs. It is designed for plugins that :ref:`register custom column types ` using the Python ``register_column_types()`` plugin hook. For example, a plugin that defines a ``file`` column type can use ``makeColumnField()`` to replace a plain text input with a file picker, and a plugin that defines a rich text column type can use it to enhance the field with an editor. Datasette calls ``makeColumnField(context)`` on each registered JavaScript plugin when it renders an editable insert/edit field. Plugins should inspect the ``context`` object and only return a control object if they can handle that field. Otherwise, use a bare ``return;``. The first plugin to return a truthy control object is used for that field. Plugins are called in registration order. If a plugin raises an exception, Datasette logs the error to the browser console and continues to the next plugin. The row dialog tracks the value that will be sent to the insert/update API. The ``context`` object describes the column and form environment; custom controls should read and write field values using the ``field`` helper object passed to ``render(field)``. Context object ^^^^^^^^^^^^^^ ``makeColumnField(context)`` is called with a context object describing the field. The current context object has these keys: ``mode`` - string ``"insert"`` or ``"edit"``. ``database`` - string or null The database name. ``table`` - string or null The table name. ``tableUrl`` - string or null The path to the table page, including any configured :ref:`base URL prefix `. ``column`` - string The column name. ``columnType`` - object or null The configured Datasette column type for this column, if one exists. This is ``null`` if no column type has been configured. If present, this object has exactly these keys: ``type`` - string The :ref:`registered column type name `, matching the ``name`` attribute of the Python ``ColumnType`` subclass. ``config`` - object Configuration for this specific column type assignment. This is ``{}`` if no configuration has been set. ``sqliteType`` - string or null The SQLite affinity for this column, if known. This is one of ``"TEXT"``, ``"INTEGER"``, ``"REAL"``, ``"BLOB"``, ``"NUMERIC"`` or ``null`` if Datasette could not determine the affinity. ``notNull`` - boolean True if the column is defined as ``NOT NULL``. ``isPk`` - boolean True if this column is part of the table's primary key. ``defaultExpression`` - string or null The SQLite default expression for the column, if available. This is ``null`` if the column has no SQLite default. For example, a column defined with ``DEFAULT (datetime('now'))`` will have ``"datetime('now')"`` here. This is the expression from the table schema, not the actual value SQLite will insert. ``form`` - ``HTMLFormElement`` or null The row insert/edit form element. ``dialog`` - ``HTMLDialogElement`` or null The modal dialog element. Returned control object ^^^^^^^^^^^^^^^^^^^^^^^ A plugin that wants to handle a field should return an object. Datasette currently recognizes these properties: ``useTextarea`` - boolean, optional If true, Datasette creates a ``