Add FeatureGroupSubGroup plugin

This plugin [0] allows can be used to either:
* create nested overlays that can be turned on or off together or separately,

```python
fg = folium.FeatureGroup()
m.add_child(fg)

g1 = folium.plugins.FeatureGroupSubGroup(fg, 'g1')
m.add_child(g1)
g2 = folium.plugins.FeatureGroupSubGroup(fg, 'g2')
m.add_child(g2)

l = folium.LayerControl().add_to(m)
```

* make multiple overlays part of the same MarkerCluster,

```python
mcg = folium.plugins.MarkerCluster(control=False)
m.add_child(mcg)

g1 = folium.plugins.FeatureGroupSubGroup(mcg, 'g1')
m.add_child(g1)
g2 = folium.plugins.FeatureGroupSubGroup(mcg, 'g2')
m.add_child(g2)

l = folium.LayerControl().add_to(m)
```

[0] https://github.com/ghybs/Leaflet.FeatureGroup.SubGroup

Signed-off-by: Olivier Mehani <[email protected]>

Author: shtrom

folium/plugins/__init__.py

@@ -14,6 +14,7 @@
 from folium.plugins.boat_marker import BoatMarker
 from folium.plugins.draw import Draw
 from folium.plugins.fast_marker_cluster import FastMarkerCluster
+from folium.plugins.feature_group_sub_group import FeatureGroupSubGroup
 from folium.plugins.float_image import FloatImage
 from folium.plugins.fullscreen import Fullscreen
 from folium.plugins.heat_map import HeatMap
@@ -33,6 +34,7 @@
     'BoatMarker',
     'Draw',
     'FastMarkerCluster',
+    'FeatureGroupSubGroup',
     'FloatImage',
     'Fullscreen',
     'HeatMap',

folium/plugins/feature_group_sub_group.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import (absolute_import, division, print_function)
+
+from branca.element import Figure, JavascriptLink
+
+from folium.map import Layer
+
+from jinja2 import Template
+
+
+class FeatureGroupSubGroup(Layer):
+    """
+    Creates a Feature Group that adds its child layers into a parent group when
+    added to a map (e.g. through LayerControl). Useful to create nested groups,
+    or cluster markers from multiple overlays. From [0].
+
+    [0] https://github.com/ghybs/Leaflet.FeatureGroup.SubGroup
+
+    Parameters
+    ----------
+    group : Layer
+        The MarkerCluster or FeatureGroup containing this subgroup.
+
+    name : string, default None
+        The name of the Layer, as it will appear in LayerControls
+    overlay : bool, default True
+        Adds the layer as an optional overlay (True) or the base layer (False).
+    control : bool, default True
+        Whether the Layer will be included in LayerControls.
+    show: bool, default True
+        Whether the layer will be shown on opening (only for overlays).
+
+    Examples
+    -------
+
+    Nested groups
+    =============
+    >>> fg = folium.FeatureGroup()                          # Main group
+    >>> g1 = folium.plugins.FeatureGroupSubGroup(fg, 'g1')  # First subgroup of fg
+    >>> g2 = folium.plugins.FeatureGroupSubGroup(fg, 'g2')  # Second subgroup of fg
+    >>> m.add_child(fg)
+    >>> m.add_child(g1)
+    >>> m.add_child(g2)
+    >>> g1.add_child(folium.Marker([0,0]))
+    >>> g2.add_child(folium.Marker([0,1]))
+    >>> l = folium.LayerControl().add_to(m)
+
+    Multiple overlays part of the same cluster group
+    =====================================================
+    >>> mcg = folium.plugins.MarkerCluster(control=False)   # Marker Cluster, hidden in controls
+    >>> g1 = folium.plugins.FeatureGroupSubGroup(mcg, 'g1') # First group, in mcg
+    >>> g2 = folium.plugins.FeatureGroupSubGroup(mcg, 'g2') # Second group, in mcg
+    >>> m.add_child(mcg)
+    >>> m.add_child(g1)
+    >>> m.add_child(g2)
+    >>> g1.add_child(folium.Marker([0,0]))
+    >>> g2.add_child(folium.Marker([0,1]))
+    >>> l = folium.LayerControl().add_to(m)
+    """
+    _template = Template(u"""
+            {% macro script(this, kwargs) %}
+            var {{this.get_name()}} = L.featureGroup.subGroup({{this._group.get_name()}});
+            {{this.get_name()}}.addTo({{this._parent.get_name()}});
+            {% endmacro %}
+            """)
+
+    def __init__(self, group, name=None, overlay=True, control=True, show=True):
+        super(FeatureGroupSubGroup, self).__init__(name=name, overlay=overlay,
+                                                   control=control, show=show)
+
+        self._group = group
+        self._name = 'FeatureGroupSubGroup'
+
+    def render(self, **kwargs):
+        super(FeatureGroupSubGroup, self).render(**kwargs)
+
+        figure = self.get_root()
+        assert isinstance(figure, Figure), ('You cannot render this Element '
+                                            'if it is not in a Figure.')
+
+        figure.header.add_child(
+            JavascriptLink('https://unpkg.com/[email protected]/dist/leaflet.featuregroup.subgroup.js'),  # noqa
+            name='featuregroupsubgroupjs')