Merge pull request #175 from BibMartin/plugins_readme

Plugins readme

Author: ocefpaf

docs/developer/plugins_introduction.ipynb

@@ -0,0 +1,134 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Introduction to `folium.plugins`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Just a small description of `plugins`, what they are, how they work, and how to implement one."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Template structure"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To undestand how plugins work, you have to know how Folium template is made. Basically, it is made of four parts :\n",
+    "\n",
+    "* The **header** : where one defines imports of CSS stylesheets and Javascript external scripts. For example, the link to Leaflet library and stylesheets are there.\n",
+    "* The **css** : where one defines specific styles.\n",
+    "* The **html** body : where one defines the document object model. For example, the map(s)' `div`s are defined there.\n",
+    "* The **javascript** : where the Leaflet script is written. For example, the map objects, layers, markers... are defined here.\n",
+    "\n",
+    "Now, a plugin is an object that inherits from `folium.plugins.Plugin`, whose goal is to write *things* into these four parts."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Quick and dirty example"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is an example of plugin, that imports a Javascript library, defines a css class, creates a new div, defines a Javascript object and add it to the map.\n",
+    "```python\n",
+    "from folium.plugins.plugin import Plugin\n",
+    "\n",
+    "class MyPlugin(Plugin):\n",
+    "    def __init__(self, data):\n",
+    "        \"\"\"Creates a MyPlugin plugin to append into a map with\n",
+    "        Map.add_plugin.\n",
+    "        \"\"\"\n",
+    "        super(MyPlugin, self).__init__()      # We call Plugin.__init__.\n",
+    "        # This will (in particular) define self.object_id as a random hexadecimal string (unique).\n",
+    "\n",
+    "        self.plugin_name = 'MyPlugin'         # This will help to name variables in html and js.\n",
+    "\n",
+    "    def render_header(self, nb):\n",
+    "        \"\"\"Generates the header part of the plugin.\"\"\"\n",
+    "        return \"\"\"\n",
+    "        <link rel=\"stylesheet\" href=\"https://myplugin_stylesheet.css\">\n",
+    "        <script src=\"https://myplugin_script.js\">\n",
+    "        \"\"\" if nb==0 else \"\"\n",
+    "\n",
+    "    def render_css(self, nb):\n",
+    "        \"\"\"Generates the css part of the plugin.\"\"\"\n",
+    "        return \"\"\"\n",
+    "        #myplugin {\n",
+    "            color: #ff00ff,\n",
+    "            width: 314px\n",
+    "            };\n",
+    "        \"\"\"\n",
+    "\n",
+    "    def render_html(self, nb):\n",
+    "        \"\"\"Generates the html part of the plugin.\"\"\"\n",
+    "        return \"\"\"\n",
+    "        <div id=\"myplugin{id}\"></div>\n",
+    "        \"\"\".format(id = self.object_name)\n",
+    "\n",
+    "    def render_js(self, nb):\n",
+    "        \"\"\"Generates the Javascript part of the plugin.\"\"\"\n",
+    "        return \"\"\"\n",
+    "        var MyPlugin_{id} = myplugin_script.someObject();\n",
+    "        map.addLayer(MyPlugin_{id});\n",
+    "        \"\"\".format(id = self.object_name)\n",
+    "```\n",
+    "Note that you may be willing to put on a map several instances of the same plugin. But you don't want the header to be written several times. This is why each method has a `nb` argument, that will be incremented at each instance's render.\n",
+    "Hence the line\n",
+    "\n",
+    "     if nb==0 else \"\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### More sophisticated example"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "TODO : write something interesting here."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 2",
+   "language": "python",
+   "name": "python2"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}