Plugin Concepts

A plugin combines a declaration with code. The declaration tells Eidos its name, where users can open it and which data it needs. The code provides the interface and operations.

Plugin declaration

Set the plugin’s id, name and version in plugin.json. List views under views and choose their entry points under placements.

The id is the plugin’s stable identity. Keep it when publishing an update and increase version so settings and saved views remain associated with the same plugin.

Page views: open independently

Set a view’s kind to page and add a navigation placement to open it from the sidebar. For example, a project dashboard uses this declaration fragment:

{
  "views": [
    {
      "id": "dashboard",
      "title": "Project dashboard",
      "kind": "page",
      "entry": "./src/dashboard.ts"
    }
  ],
  "placements": [{ "location": "navigation", "view": "dashboard" }]
}

A page can use routes such as / and /settings to organize its content. Read the current route from ctx.binding.route. Declare workspace.files permission when the page needs files from the Space.

File views: open with content

Set a view’s kind to file, then add a file/open placement with supported file extensions. Users can select it from a file’s Open with menu.

Choose a data interface for the operation. For example, a text editor declares capabilities: ["document"] and uses ctx.capabilities.document to read, edit and save. Eidos maintains unsaved content and undo history.

Eidos file operations live under ctx.capabilities.eidos: schema reads the file structure, table queries the current table, and config accesses your plugin configuration. Combine eidos/schema, eidos/table and eidos/config declarations as needed.

To visualize a table inside an Eidos file, declare capabilities: ["eidos/table"] with a table/view placement. Users add it from the table’s view menu, and the plugin queries the bound table through ctx.capabilities.eidos.table.

Read file information from ctx.binding.file. When the view opens inside a table, ctx.binding.location also supplies table and view IDs. See the API reference for data methods.

Use the context in code

Eidos opens a view by calling its default export, mount(ctx, root). Build the interface inside root and use ctx for:

• ctx.binding: the current file, table location or page route.
• ctx.capabilities: operations such as reading data, saving content and showing notifications.
• ctx.signal: cancellation of asynchronous work when the view closes.
• ctx.subscriptions: subscriptions to release with the view.

Return an object with dispose() from mount to clean up your interface. For example, a React plugin calls reactRoot.unmount() there.

Commands and formatting

Commands execute actions such as creating today’s note or processing selected records. Declare commands in actions, export activate(ctx) from the module named by extension, and register handlers through ctx.capabilities.actions.

A formatter receives document text and returns formatted text. Register it through ctx.capabilities.formatters so users can invoke it through Eidos’s formatting operation.

Request access

Views and actions default to access: "read". Declare access: "write" when an operation changes data. Access to files throughout a Space also requires workspace.files, for example:

{ "workspace": { "files": { "read": true, "write": false } } }

This suits an index page that reads workspace content. To create or change files, set write to true and give the relevant view or action write access. Eidos shows the requested access scope when the user enables the plugin.