Blog Plugins Plans Help Log in
Help Center » Plugin Creation: Define settings, name and metadata for a plugin

Plugin Creation: Define settings, name and metadata for a plugin

linkPlugin API Reference Documentation: Plugin creation

To create a plugin, you'll need a note that contains two things: a table of plugin information, and a code block containing the Javascript code of the plugin.


open_in_new

linkMetadata table

A plugin metadata table contains (at least) two columns: the name of the setting, and a value for the setting.

setting name

setting value

The setting name is not case sensitive. All columns are interpreted as strings.


linkname

The only required setting is the name of the plugin, which can be defined as:

name

Plugin name here

This is the name that the user will see when invoking the plugin, and will be used as a prefix in cases where the plugin defines multiple options presented to the user.


linkicon

The name of a Material Design Icon that will be used to identify the plugin. If not provided, a generic "extension" icon will be used.

icon

search


linkdescription

A short description shown when installing or configuring a plugin.

description

Count the number of words in a note.


linkinstructions

More detailed information about using the plugin that will be shown if the plugin is published to the Plugin Directory.

instructions

Here are some helpful words of advice on using this plugin:
1. Instruction one
2. Instruction two
3. Instruction three


linksetting

Defines settings that the user can provide to configure the plugin. The user will be able to supply a string for each setting when configuring the note as a plugin. When plugin code is invoked, it has access to the settings values that the user has provided. All setting values are provided as strings.

setting

API Key


This setting name can be repeated multiple times to define multiple settings.

setting

API Key

setting

Name


linkCode

The first code block in the note will be used as the plugin's code. Any subsequent code blocks will be ignored. The plugin code should define a Javascript object. Any functions defined on this object that match the name of an action will register the plugin to handle that action.

{
insertText(app) {
return "Hello World!"
}
}


To define multiple actions for a single action type, make the action-named field an object. The keys should be the name of the action, with the corresponding function as the value.

{
insertText: {
"one word": function(app) {
return "hello";
},
"two words": function(app) {
return "hello world";
}
}
}


Plugin actions can either be a function - as shown above - or an object with run and check keys with functions as the values (see actions section for further explanation):

{
insertText: {
check(app) {
return true;
},
run(app) {
return "Hello World!";
}
}
}

and:

{
insertText: {
"one word": {
check(app) {
return true;
},
run(app) {
return "hello";
}
},
"two words": function() {
check(app) {
return true;
},
run(app) {
return "hello world";
}
}
}
}


When plugin code is invoked, the plugin object will be this, for example:

{
insertText(app) {
return this._text();
},
 
_text() {
return "hello world";
}
}


The plugin object will be instantiated when the plugin is installed in the client, retaining any state until it is reloaded (e.g. due to the plugin code being changed in the source note).

{
insertText(app) {
this._counter++;
return "hello " + this._counter;
},
 
_counter: 0,
}


Plugin action functions (both run and check) can return promises, which will be awaited.

{
insertText: {
check(app) {
return new Promise(function(resolve) {
setTimeout(resolve, 2000);
}).then(function() {
return true;
});
},
run(app) {
return new Promise(function(resolve) {
setTimeout(resolve, 2000);
}).then(function() {
return "hello world, eventually";
});
}
}
}

Or, they can use async/await syntax:

{
insertText: {
async check(app) {
await new Promise(function(resolve) { setTimeout(resolve, 2000); });
return true;
},
async run(app) {
await new Promise(function(resolve) { setTimeout(resolve, 2000); });
return "hello world, eventually";
}
}
}


The first argument passed to a plugin action function is an application interface object that can be used to access settings and call into the host application itself.


linkAccessing settings

Given a plugin with the following metadata table entry:

setting

API Key

A plugin can access the setting through app.settings:

{
insertText(app) {
return app.settings["API Key"];
}
}


linkAction function arguments

For action functions that receive arguments, the app argument will still be the first argument, before any other arguments:

{
replaceText(app, text) {
return text + " more";
}
}


When using check and run functions, they will receive the same arguments as the action would. So for the linkOption action, for example:

{
linkOption: {
check(app, link) {
return true;
},
 
run(app, link) {
console.log("Hello!");
}
}
}