Merge pull request #910 from ethereum/docPlugins

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](./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.

docs/remix_plugin_api.md

+Remix Plugin API usage
+======================
+
+This section list all the available key and value pair which define this API:
+
+## 1) notifications
+
+### app (key: app)
+ 
+ - unfocus `[]`
+ - focus `[]`
+
+### compiler (key: compiler)
+
+ - compilationFinished `[success (bool), data (obj), source (obj)]`
+ - compilationData `[compilationResult (obj)]`
+ 
+### transaction listener (key: txlistener)
+
+ - newTransaction `[tx (obj)]`
+
+### addendum
+ 
+`newTransaction` is broadcasted to all loaded plugins.
+`compilationFinished` is sent to the plugin that currently has the focus.
+`focus / unfocus` is sent to the plugin which currently has the focus or is unfocused.
+`compilationData` is sent always just upon the `focus` event and gives the last compilation result.
+
+## 2) requests
+
+### app
+
+ - getExecutionContextProvider `@return {String} provider (injected | web3 | vm)`
+ - updateTitle `@param {String} title`
+ 
+### config
+
+ - setConfig `@param {String} path, @param {String} content`
+ - getConfig `@param {String} path`
+ - removeConfig `@param {String} path`
+
+### compiler
+ - getCompilationResult `@return {Object} compilation result`
+
+### udapp (only VM)
+ - runTx `@param {Object} tx`
+ - getAccounts `@return {Array} acccounts`
+ - createVMAccount `@param {String} privateKey, @param {String} balance (hex)`
+ 
+
+