Creating a Plugin

What is a Plugin?

• the easiest way to extend Peppermint's core functionalities and make it fit your own needs
• a tool that runs on-demand (the user has to trigger it, by executing it) and sits on the Tools menu

What languages to use?

Peppermint plugins can be written:

• CoffeeScript
• JavaScript
• ES6/Babel (experimental)

Note

As you may notice if you have a look into the "official" plugins' source, all of the plugins are written in CoffeeScript. But it's purely a matter of taste. If you personally don't like it (or simply prefer straight JavaScript), don't let that discourage you: Plugins can be written very easily in pure JavaScript too. ;-)

Where do I start?

All you have to do is:

• create a folder with your Plugin's title and the extension .ppPlugin
• create 2 blank files in there: info.json and script.coffee

Generally, you have to follow this folder structure:

--[ My Plugin Title.ppPlugin ]
-------[ info.json ]
-------[ script.coffee ]

Notes

• "My Plugin Title" is the title of the plugin as shown in the Tools menu.
• If your plugin is a JavaScript plugin, script.coffee becomes script.js. While, if it's Babel/ES6 (new Generation JavaScript), it becomes script.babel.
• Obviously, any additional files can be added (e.g. as in the case of Preview-based plugins)

---

The description file

Or... a basic info.json:

{
    "name"          : "MyPlugin",
    "category"      : "",
    "author"        : "",
    "author_email"  : "",
    "last_update"   : "",
    "shortcut"      : "",
    "scope"         : "Global"
}    

Note

The only required options are:

• 'name' (the name of the class/function as described in script.js)
• 'scope' (the Spec/Language it is to be attached to. E.g. "C++", "JavaScript", "HTML", or "Global" for Spec-independent plugins).

Writing the plugin (in CoffeeScript)

or... the absolute minimum script.coffee:

class MyPlugin extends $Plugin

    init:->
        # Initialisation code to be executed once
	# the first time the plugin runs

    run:->
        # This is the core function

        # Code to be executed, every time the user
        # "runs" the plugin

    halt:->
        # Termination/cleanup code to be executed
        # when the plugin is terminated manually
        # or a different plugin is executed

Writing the plugin (in JavaScript)

or... the absolute minimum script.js:

function MyPlugin() {

    this.init = function() {
        // Initialisation code to be executed once
        // the first time the plugin runs
    }

    this.run = function() {
        // This is the core function

        // Code to be executed, every time the user
        // "runs" the plugin
    }

    this.halt = function() {
        // Termination/cleanup code to be executed
        // when the plugin is terminated manually
        // or a different plugin is executed
    }
}

Writing the plugin (in ES6/Babel)

or... the absolute minimum script.babel:

class MyPlugin extends $Plugin {

    init() {
        // Initialisation code to be executed once
        // the first time the plugin runs
    }

    run() {
        // This is the core function

        // Code to be executed, every time the user
        // "runs" the plugin
    }

    halt() {
        // Termination/cleanup code to be executed
        // when the plugin is terminated manually
        // or a different plugin is executed
    }
}      

---

Testing & Running your Plugin

Before trying it out, the most appropriate way is to "Install" your Plugin.

To do so, just go to Peppermint > Extension Manager > Plugins, click on the "+" icon and select your .ppPlugin bundle from the disk.

Then, and once the appropriate spec (if any - as shown in the info.json file) is selected, you will notice it under the main Tools menu (or in the little "cog" menu in the Status Bar).

An easier (though still experimental) way of "testing" your Plugins, is:

• open your .ppPlugin folder from within Peppermint
• go to your Workspace, where the folder is
• right-click on it
• select Plugin > Debug (Yep, the plugin has been automatically recognized as such)
• have fun!