Input sources

What an input source is

An input source is another way to get structures onto the page. In API 1 that means a search source: when a person opens Quick insert (press /) and types, Athanor asks your plugin for candidates, shows them in the list labeled "source title · plugin name", and inserts the one the person picks.

Your plugin only answers the search. Athanor does the inserting, so a search source needs no permissions at all.

A minimal source

This is the Input source template from New plugin: Input source template…. It offers six common solvents.

manifest.json:

{
  "id": "local.common-solvents",
  "name": "Common solvents",
  "version": "0.1.0",
  "api": "1.0.0",
  "author": "You",
  "description": "Common solvents, made from the source template.",
  "main": "main.js",
  "permissions": [],
  "contributes": {
    "inputSources": [{ "key": "solvents", "title": "Common solvents", "kind": "search" }]
  }
}

main.js:

// @ts-check
/// <reference path="./athanor.d.ts" />
 
// An input source: Athanor asks it as the user types, and inserts the candidate the user picks.
const SOLVENTS = [
  { name: 'Water', smiles: 'O' }, { name: 'Ethanol', smiles: 'CCO' }, { name: 'Acetone', smiles: 'CC(C)=O' },
  { name: 'Dichloromethane', smiles: 'ClCCl' }, { name: 'Tetrahydrofuran', smiles: 'C1CCOC1' }, { name: 'Toluene', smiles: 'Cc1ccccc1' },
];
athanor.sources.onSearch('solvents', (query) => {
  const q = query.trim().toLowerCase();
  return SOLVENTS.filter((s) => !q || s.name.toLowerCase().includes(q)).slice(0, 8);
});

Open Quick insert, type "eth", and Ethanol appears in the list.

The search handler

athanor.sources.onSearch(key, fn) registers the handler for the source with that key. Athanor calls it with the text the person typed (up to 200 characters), a moment after typing pauses. It returns a list of candidates, or a promise of one:

Candidates without a valid smiles string are dropped, never inserted. Athanor uses the first 20 a source returns, and shows up to 12 plugin candidates in all.

The official example

The Periodic table plugin adds an "Elements" source, so typing an element's name or symbol offers that element:

athanor.sources.onSearch('elements', (query) => {
  const q = query.trim().toLowerCase();
  if (!q) return [];
  return ELEMENTS.filter((e) => e[1].toLowerCase() === q || e[2].toLowerCase().startsWith(q)).slice(0, 6).map((e) => ({ name: e[2] + ' (' + e[1] + ')', smiles: '[' + e[1] + ']' }));
});

Rules and limits

• Up to 50 input sources per plugin. key follows the command key rule; title is required, at most 40 characters; icon is optional.
• Return quickly. A source that fails or answers slowly adds nothing to the list, and the rest of Quick insert carries on without it.
• Return an empty list for an empty query if your source has nothing useful to show before the person types.
• A structure picked from your source is inserted by Quick insert itself, the same way as any other candidate in its list.

Reserved

"kind": "stream", for a source that pushes structures over time, is accepted in the manifest and reserved. API 1 asks only search sources.