You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
101 lines
3.4 KiB
101 lines
3.4 KiB
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](./remix_plugin_api.html) 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.
|
|
|