remix-project/docs/remix_plugin.md

Remix Plugin API

This section provides informations about developing plugin for Remix.

Introduction

A plugin is basically a front end interface loaded through an iframe. Plugins have access to remix main features through an API. This API consist of notification and request messages built over iframe messages (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) plugin resources (html, js, img, ...) needs to have their own hosting, either using normal web or using decentralized infrastructure like Swarm and IPFS.

A plugin declaration is a JSON value which contains the properties url and title.

{
    "title": "<plugin name>",
    "url": "<plugin url>"
}

Loading / Registering a plugin in Remix IDE can be done:

• Creating a PR which add a new entry: https://github.com/ethereum/remix-ide/blob/master/src/app/plugin/plugins.js , the plugin can then be loaded directly from remix IDE with a single click.
• In the settings tab, paste a plugin declaration in the plugin section and hit load.
• Load Remix IDE with the following url parameters: pluginurl and plugintitle

Using the API with iframe post message

A message (either received by the plugin or sent to it) is defined as follow:

    {
      action: <request, response or notification>,
      key: '<key>',
      type: '<type>',
      value: [<value1>, <value2>, ...],
      id: <call id> <used to track response>
    }

example:

    window.parent.postMessage(JSON.stringify({
        action: 'request',
        key: 'config',
        type: 'setConfig',
        value: [document.getElementById('filename').value, document.getElementById('valuetosend').value],
        id: 34
    }), '*')

There are 2 ways for interacting with the API, listening on notification and sending request

    function receiveMessage (event) {
        if (event.data.action === 'notification') {
            ...
        }
        if (event.data.action === 'response') {
            < listen on the response of the request app / updateTitle >
            < contain event.data.error if any >
            ...
        }
    }
    window.addEventListener('message', receiveMessage, false)
    
    window.parent.postMessage(JSON.stringify({
      action: 'request',
      key: 'app',
      type: 'updateTitle',
      value: ['changed title ' + k++],
      id: 39
    }), '*')

from a response point of view, The error property is undefined if no error happened. In case of error (due to permission, system error, API error, etc...), error contains a string describing the error

see Remix Plugin API usage for a list of available key / value describing the API.

Using the API with remix extension NPM package

The remix-plugin NPM package can be used to abstract the iframe layer:

    var extension = require('remix-plugin')
    
    extension.listen('<key>', '<type>', function () {})
    extension.call('<key>', '<type>', '<array of parameters>', function (error, result) {})
    
    // examples
    extension.listen('compiler', 'compilationFinished', function () {})
    extension.call('app', 'detectNetWork', [], function (error, result) {})
    extension.call('config', 'setConfig', ['<filename>', '<content>'], function (error, result) {})

error is either null or a string, result is an array.