Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Martin Journois
committed
Aug 14, 2015
1 parent
ab5f476
commit 056b9b5
Showing
1 changed file
with
134 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
} |