Note Toolbar API - chrisgurney/obsidian-note-toolbar GitHub Wiki

The Note Toolbar API provides basic toolbar access, and the ability to show UI (e.g., suggesters, prompts, and modals). The latter enables Dataview JS, JS Engine, or Templater scripts to ask for information, or to show helpful text.

Using the ntb object, below are the functions that can be called in scripts that are executed from Note Toolbar items.

I would appreciate your feedback, which you can leave in the discussions.

In each item's More actions... menu, use Copy developer ID to copy the unique identifier (UUID) for any toolbar item to the clipboard.

From code you can then target the item and make changes to it:

const item = ntb.getItem('112c7ed3-d5c2-4750-b95d-75bc84e23513');
item.setIcon('alert');

// or fetch the HTML element (for non-floating-button toolbars)
const itemEl = activeDocument.getElementById('112c7ed3-d5c2-4750-b95d-75bc84e23513');

clipboard: () => Promise<null | string>

Gets the clipboard value.

Promise<null | string>

The clipboard value or null.

// gets the clipboard value
const value = await ntb.clipboard();

new Notice(value);

fileSuggester: (options?) => Promise<null | TAbstractFile>

Shows a file suggester modal and waits for the user's selection.

Promise<null | TAbstractFile>

The selected TAbstractFile.

const fileOrFolder = await ntb.fileSuggester();
new Notice(fileOrFolder.name);
// show only folders
const folder = await ntb.fileSuggester({
 foldersonly: true
});
new Notice(folder.name);

getActiveItem: () => undefined | IItem

Gets the active (last activated) toolbar item.

undefined | IItem

The active (last activated) item.

This does not work with Note Toolbar Callouts.

getItem: (id) => undefined | IItem

Gets an item by its ID, if it exists.

undefined | IItem

The item, or undefined.

getProperty: (property) => undefined | string

Gets the value of the given property in the active note.

undefined | string

The frontmatter value for the given property, or undefined if it does not exist.

const createdDate = ntb.getProperty('created');

getToolbars: () => IToolbar[]

Gets all toolbars.

IToolbar[]

All toolbars.

modal: (content, options?) => Promise<void>

Shows a modal with the provided content.

Promise<void>

// shows a modal with the provided string
await ntb.modal("_Hello_ world!");

// shows a modal with the rendered contents of a file
const filename = "Welcome.md";
const file = app.vault.getAbstractFileByPath(filename);

if (file) {
  await ntb.modal(file, {
    title: `**${file.basename}**`
  });
}
else {
  new Notice(`File not found: ${filename}`);
}

NtbModal.js in the examples/Scripts folder.

prompt: (options?) => Promise<null | string>

Shows the prompt modal and waits for the user's input.

Promise<null | string>

The user's input.

// default (one-line) prompt with default placeholder message
const result = await ntb.prompt();

new Notice(result);

// large prompt with message, overridden placeholder, and default value 
const result = await ntb.prompt({
  label: "Enter some text",
  large: true,
  placeholder: "Placeholder",
  default: "Default"
});

new Notice(result);

NtbPrompt.js in the examples/Scripts folder.

setProperty: (property, value) => Promise<void>

Sets the given property's value in the active note.

Promise<void>

await ntb.setProperty('Created', moment().format('YYYY-MM-DD'));
await ntb.setProperty('cssclasses', 'myclass');
await ntb.setProperty('A Link', '[[Some Note]]');
await ntb.setProperty('A Number', 1234);
await ntb.setProperty('A List', ['asdf', 'asdf2']);

suggester: (values, keys?, options?) => Promise<null | T>

Shows a suggester modal and waits for the user's selection.

Promise<null | T>

The selected value, or corresponding key if keys are provided.

// shows a suggester that returns the selected value 
const values = ["value `1`", "value `2`"];

const selectedValue = await ntb.suggester(values);

new Notice(selectedValue);

// shows a suggester that returns a key corresponding to the selected value, and overrides placeholder text
const values = ["value `1`", "value `2`"];
const keys = ["key1", "key2"];

const selectedKey = await ntb.suggester(values, keys, {
  placeholder: "Pick something"
});

new Notice(selectedKey);

NtbSuggester.js in the examples/Scripts folder.

t: string

This is the i18next translation function, scoped to Note Toolbar's localized strings.

The string translation corresponding with the provided key, if it exists, with a fallback to English. If the key does not exist, the key is returned.

// shows "Copied to clipboard" if the language is English, or in another langauge if the translation exists
new Notice(ntb.t('api.msg.clipboard-copied'));

• For usage, see the i18next documentation.
• en.json and other translations in the src/I18n folder.