Plugins

Note: Plugins are an experimental feature. They may change significantly as they develop. If you decide to write a plugin, you may need to update it a little every time a new version of the editor is released until the feature stabilizes. If you have suggestions or requests for features to include in the plugin API, please let us know.

Plugins are small programs that let you, or third parties, extend the editor with new functionality. A plugin is a text file with the file extension .micd-plugin that contains a small program that can access and modify parts of the editor.

Using plugins

To use a plugin, first you must install it. Choose Plugin/Manage Plugins from the menu. Then choose the add button and select the plugin file you wish to install. If the plugin is valid, it will be added to the list of installed plugins. From this window you can also uninstall plugins and change their order. The order of the plugins sets their order in the Plugin menu.

Looking for plugins to try? Download this collection of example plugins.

Once a plugin is installed, you can close the plugin manager. The plugin can be activated from any editor window by choosing the plugin by name from the Plugin menu.

Plugins cannot start automatically. They can only be started manually by choosing them from the Plugin menu.

Some plugins, such as those that register custom command palettes, only need to run once and can be uninstalled again immediately after use. But most plugins behave more like extra commands. You will want to keep them installed in the plugin menu so you can run them whenever they are needed.

Developing plugins

Plugins access and modify the active editor using the Math I Can Do API. The plugin also has access to a special micd.App object that provides additional functionality specific to the desktop edition of the editor.

Tip: Many API features are demonstrated in the API playground. Although intended for developers who want to embed the editor in a Web app, most of these examples also apply to plugin development.

Sample code

A repository of plugin sample code is available on GitHub to get you started.

Development tools

Any text editor capable of saving text with the UTF-8 encoding can be used to write a plugin, but experienced programmers will find it easier to use a modern editing tool with TypeScript support.

Development cycle

Once you have a script file with a metadata block with at least a name property, you can start running and testing your plugin. Save your script with the file extension .micd-plugin, then open the app and choose Plugin/Manage Plugins. Choose the add button, then select your plugin file to install it. Now close the plugin manager window, and:

  1. Choose your plugin from by name from the Plugin menu.
  2. Observe the results.
  3. Return to your script editor and make changes as needed.
  4. Save the plugin file.
  5. Return to the app and repeat from Step 1 as needed until you are satisfied.

Once the plugin works as expected, you can share it with others just by sharing the .micd-plugin file.

What’s in a plugin file?

Plugin files are plain text files with two parts: a descriptive metadata block, followed by the plugin code. The metadata block contains only data, no code, so it can be read without running the plugin. The plugin code only runs when the plugin is chosen from the Plugin menu by the user.

Metadata

The metadata block comes at the top of a plugin script, before any code. It starts and ends with a backtick (`) character. Between the backticks comes a list of keys and values, one per line, optionally followed by a blank line and a plugin description. Like this: 

// Optional comments
`
    name: Wonder Plugin
    version: 1.0.0
    credits: H.T. Murgatroyd
    link: https://wonderplugin.tld

    Does something wonderful. (A blank line separates the property keys from
    the description section.)
`
// Plugin code starts here…

Only the name property is requried. It determines the name of the plugin as shown in the Plugin menu and the plugin manager. Note that a plugin’s name is fixed when it is installed. If you change the name in the source file, it will only change in the editor if you uninstall and reinstall the file.

Escaping characters in the metadata block: Backticks mark the start and end of the metadata. They also turn it into valid but harmless JavaScript so that your development tools don’t flag it as an error. However, certain rarely-needed characters must be escaped if they need to appear inside of the block: backticks (escape with \u0060), the dollar sign (escape with \$) and the backslash (escape with \\).

Plugin code

The main body of your plugin is executed as JavaScript code when the plugin is selected. You have access to the Math I Can Do API through the micd object just as you would if you were using the API on a Web page. The variables editor, view, and shell are predefined to the Editor, View, and Shell objects of the current editor window.

Example

Here is a short but complete example that, when installed and activated, inserts a short message into the editor:

// Example plugin
`
    name: Example
`

view.type(".txt Greetings!\n");

Contents