Add Timeline plugin (#1870)

* Add interval support to timestamped_geo_json

* Try with separate timeline

* Fix error in documentation

* Fixed breaking test

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Based on review comments

* Add classes to namespace per review comments

* Added documentation for timeline plugin

Updated the documentation for timestamped_geojson to
clarify the difference with timeline.

Also used a simpler code example in timeline.py docstring.

* Add test + fix CDN import

* Piggyback on borders.json from the Skeat timeline repo

* Update docs/user_guide/plugins/timestamped_geojson.md

Co-authored-by: Frank Anema <33519926+Conengmo@users.noreply.github.com>

* Updated after review comments

* Made the example file smaller

* Update folium/plugins/timeline.py

Co-authored-by: Frank Anema <33519926+Conengmo@users.noreply.github.com>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Frank Anema <33519926+Conengmo@users.noreply.github.com>

Author: 3 people

docs/user_guide/plugins/timeline.md

@@ -0,0 +1,74 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+##  Timeline and TimelineSlider
+Show changing geospatial data over time.
+
+### Comparison to TimestampedGeoJson
+This is a plugin with a similar purpose to `TimestampedGeoJson`. They both
+show geospatial information that changes over time.
+
+The main difference between the two is the input format.
+
+In the `Timeline` plugin each `Feature` has its own `start` and `end` time among its properties.
+In the `TimestampedGeojson` each `Feature` has an array of start times. Each start time in
+the array corresponds to a part of the `Geometry` of that `Feature`.
+
+`TimestampedGeojson` also does not have `end` times for each `Feature`. Instead you can
+specify a global `duration` property that is valid for all features.
+
+Depending on your input geojson, one plugin may be more convenient than the other.
+
+### Comparison to Realtime
+The `Timeline` plugin can only show data from the past. If you want live updates,
+you need the `Realtime` plugin.
+
+```{code-cell} ipython3
+import folium
+from folium.utilities import JsCode
+from folium.features import GeoJsonPopup
+from folium.plugins.timeline import Timeline, TimelineSlider
+import requests
+
+m = folium.Map()
+
+data = requests.get(
+    "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/historical_country_borders.json"
+).json()
+
+timeline = Timeline(
+    data,
+    style=JsCode("""
+        function (data) {
+            function getColorFor(str) {
+                var hash = 0;
+                for (var i = 0; i < str.length; i++) {
+                    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+                }
+                var red = (hash >> 24) & 0xff;
+                var grn = (hash >> 16) & 0xff;
+                var blu = (hash >> 8) & 0xff;
+                return "rgb(" + red + "," + grn + "," + blu + ")";
+            }
+            return {
+                stroke: false,
+                color: getColorFor(data.properties.name),
+                fillOpacity: 0.5,
+            };
+        }
+    """)
+).add_to(m)
+GeoJsonPopup(fields=['name'], labels=True).add_to(timeline)
+TimelineSlider(
+    auto_play=False,
+    show_ticks=True,
+    enable_keyboard_controls=True,
+    playback_duration=30000,
+).add_timelines(timeline).add_to(m)
+m
+```

docs/user_guide/plugins/timestamped_geojson.md

@@ -7,6 +7,27 @@ import folium.plugins
 ```
 
 ##  TimestampedGeoJson
+Show changing geospatial data over time.
+
+### Relation to Timeline
+This is a plugin with a similar purpose to `Timeline`. They both
+show geospatial information that changes over time.
+
+The main difference between the two is the input format.
+
+In the `TimestampedGeojson` each `Feature` has an array of start times. Each start time in
+the array corresponds to a part of the `Geometry` of that `Feature`.
+In the `Timeline` plugin each `Feature` has its own `start` and `end` time among its properties.
+
+Also `TimestampedGeoJson` has a global `duration` property that is valid for all `Features`.
+In the `Timeline` plugin each `Feature` has its own `end` time property.
+
+Depending on your input geojson, one plugin may be more convenient than the other.
+
+### Relation to Realtime
+This plugin can only show data from the past. If you want live updates,
+you need the `Realtime` plugin.
+
 
 ### Example 1
 

examples/data/historical_country_borders.json

@@ -29,6 +29,7 @@
 from folium.plugins.tag_filter_button import TagFilterButton
 from folium.plugins.terminator import Terminator
 from folium.plugins.time_slider_choropleth import TimeSliderChoropleth
+from folium.plugins.timeline import Timeline, TimelineSlider
 from folium.plugins.timestamped_geo_json import TimestampedGeoJson
 from folium.plugins.timestamped_wmstilelayer import TimestampedWmsTileLayers
 from folium.plugins.treelayercontrol import TreeLayerControl
@@ -65,6 +66,8 @@
     "TagFilterButton",
     "Terminator",
     "TimeSliderChoropleth",
+    "Timeline",
+    "TimelineSlider",
     "TimestampedGeoJson",
     "TimestampedWmsTileLayers",
     "TreeLayerControl",