Plugins

Concept

Plugins were added to easily extend the base functionality of the terminal. Allowing for grouping of custom commands and shortcuts.

Plugin Structure

export default class Plugin {
  static displayName = '';
  static version = '1.0.0';
  static defaultData = '';

  static commands = {};
  static descriptions = {};
  static shortcuts = {};

  constructor(api, config = {}) {
    this.api = api;
    this.config = config;
    this.commands = {};
    this.descriptions = {};
    this.shortcuts = {};

    this.updateApi = newApi => (this.api = newApi);
    this.getPublicMethods = () => ({});
    this.readStdOut = () => true;
  }
}

Static attributes

Plugins passed into the terminal have to be classes. The class needs static attributes of displayName and version.

You can also have optional static attributes of commands, descriptions, and shortcuts. These are useful for plugins that don't need complex commands or shortcuts.

If your plugin will need data that exist across tabs then you can define a default data object with the static attribute defaultData. You can read, and edit this data via the api.

Instance attributes

For more complicated plugins you will want to use the attributes commands, descriptions, and shortcuts created per instance. These commands will then be able to take advantage of the plugin api, static commands can not.

The methods updateApi, getPublicMethods, and readStdOut are required.

updateApi is a required function because on instantiation of a plugin the api will not be ready until all plugins have been fully set up. The terminal then calls updateApi to give you the most up to date api.

getPublicMethods is used to expose functions and information to other plugins.

readStdOut is a method to allow you to spy on the output of all commands and to even stop the printing of text if false is returned.

Config

You can allow for configuration options to be passed into your plugin. This requires the user to use the format.

{
  class: YourPluginClass,
  config: {
    foo: 'bar'
  }
}

This config object will be passed into each instance of your plugin.

Plugin API

printLine

This method allows you to print out a string or jsx to the output of the terminal.

As an example here is printing an image.

this.api.printLine(<img src="http://i0.kym-cdn.com/photos/images/masonry/000/220/777/Nope.png" />);

removeLine

This method given an index will remove any line of output even the return lines. Given negative numbers this will remove lines from the bottom by default it will remove the last line of output (-1).

runCommand

This method takes a input string then will attempt to run any command found in that string.

this.api.runCommand(`edit-line Loading: ${percent}%`);

setCanScroll

This method allows you to set if the current tab can scroll. Takes one boolean as arguments.

setScrollPosition

This method takes an integer scroll position to set the current tabs scroll pos.

focusInput

This method allows you to focus the terminal input for the current tab.

setPromptPrefix

This method takes a string argument to set whatever is before the prompt symbol. ie: home/user would be the prefix to home/user >.

getData

This method allows you to get your plugin specific data. This data is tab independent.

setData

This method allows you to set your plugin specific data. This data is tab independent.

getPluginMethod

This method allows you to get a plugins public methods if you know the plugin name and the name of the method.

ie: The base code from the node-eval-plugin shows the use of this well.

...
const parsePath = this.api.getPluginMethod(this.config.filesystem, 'parsePath');
const readFile = this.api.getPluginMethod(this.config.filesystem, 'readFile');
if (args._.length > 0) {
  const path = parsePath(args._[0]);
  const file = readFile(path);
  ...
}
...

os

This is just a variable storing the current os of the machine you are on.

Base Plugin

A base plugin class is available to extend to make sure that all required values and functions are available.

import { BasePlugin } from 'terminal-in-react';