✨ NEW: Add dt-past/dt-future class to item divs

Author: chrisjsewell

docs/_static/custom.css

@@ -1,3 +1,8 @@
+/** highlight future events **/
+ol.timeline-default>li.timeline>div.tl-item.dt-future {
+    outline-color: green;
+}
+
 /** furo and pydata-sphinx-theme **/
 body[data-theme="dark"] {
     --tl-dot-color: #9a9a9a;

docs/index.md

@@ -17,7 +17,7 @@ A scrolling horizontal timeline is created for HTML output, and other formats de
   name: 4th event
 - start: 2020-02-04
   name: 5th event
-- start: 2021-02-04
+- start: 2030-02-04
   name: 6th event
 ---
 **{{dtrange}}**
@@ -161,7 +161,9 @@ class
 class-item
 : Classes to add to each item.
 
-## CSS Variables
+## Customise HTML output
+
+### CSS Variables
 
 The following CSS variables can be used to customize the appearance of the timeline:
 
@@ -211,3 +213,24 @@ body[data-theme="dark"] {
     }
 }
 ```
+
+### Data attributes
+
+On the containing div for each event, the `data-dt` data attribute is added, which contains the event's `start` data/time in ISO format.
+JavaScript (if enabled) will also run, to add `dt-future` or `dt-past` class to each div, depending on whether the event is in the future or past.
+This means that you can use CSS selectors to style events based on their date/time.
+
+For example, to highlight future events, you can add the following to your `conf.py`:
+
+```python
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+```
+
+Then add to the CSS `_static/custom.css`:
+
+```css
+ol.timeline-default>li.timeline>div.tl-item.dt-future {
+    outline-color: green;
+}
+```

src/sphinx_timeline/main.py

@@ -25,7 +25,8 @@ def setup(app: Sphinx) -> None:
     """Setup the extension."""
     from sphinx_timeline import __version__
 
-    app.connect("builder-inited", add_css)
+    app.connect("builder-inited", add_html_assets)
+    app.connect("html-page-context", load_html_assets)
     app.add_directive("timeline", TimelineDirective)
     app.add_node(
         TimelineDiv,
@@ -43,23 +44,47 @@ def setup(app: Sphinx) -> None:
     }
 
 
-def add_css(app: Sphinx):
-    """Copy the CSS to the build directory."""
+def add_html_assets(app: Sphinx) -> None:
+    """Add the HTML assets to the build directory."""
+    if (not app.builder) or app.builder.format != "html":
+        return
     # setup up new static path in output dir
     static_path = (Path(app.outdir) / "_sphinx_timeline_static").absolute()
     static_path.mkdir(exist_ok=True)
+    for path in static_path.glob("**/*"):
+        path.unlink()
     app.config.html_static_path.append(str(static_path))
-    # Read the css content and hash it
-    content = resources.read_text(static_module, "default.css")
-    hash = hashlib.md5(content.encode("utf8")).hexdigest()
-    # Write the css file
-    css_path = static_path / f"tl_default.{hash}.css"
-    app.add_css_file(css_path.name)
-    if css_path.exists():
+    for resource in resources.contents(static_module):
+        if not resource.endswith(".css") and not resource.endswith(".js"):
+            continue
+        # Read the content and hash it
+        content = resources.read_text(static_module, resource)
+        hash = hashlib.md5(content.encode("utf8")).hexdigest()
+        # Write the file
+        name, ext = resource.split(".", maxsplit=1)
+        write_path = static_path / f"{name}.{hash}.{ext}"
+        write_path.write_text(content, encoding="utf8")
+
+
+def load_html_assets(app: Sphinx, pagename: str, *args, **kwargs) -> None:
+    """Ensure the HTML assets are loaded in the page, if necessary."""
+    if (not app.builder) or app.builder.format != "html":
         return
-    for path in static_path.glob("*.css"):
-        path.unlink()
-    css_path.write_text(content, encoding="utf8")
+    if (not app.env) or not app.env.metadata.get(pagename, {}).get("timeline", False):
+        return
+    for resource in resources.contents(static_module):
+        if not resource.endswith(".css") and not resource.endswith(".js"):
+            continue
+        # Read the content and hash it
+        content = resources.read_text(static_module, resource)
+        hash = hashlib.md5(content.encode("utf8")).hexdigest()
+        # add the file to the context
+        name, ext = resource.split(".", maxsplit=1)
+        write_name = f"{name}.{hash}.{ext}"
+        if ext == "css":
+            app.add_css_file(write_name)
+        if ext == "js":
+            app.add_js_file(write_name)
 
 
 class TimelineDiv(nodes.General, nodes.Element):
@@ -251,6 +276,8 @@ def run(self) -> list[nodes.Element]:
             )
             item_node.append(item_container)
 
+        self.env.metadata[self.env.docname]["timeline"] = True
+
         return [container]
 
 

src/sphinx_timeline/static/datetime.js

@@ -0,0 +1,20 @@
+// On page load,
+// look for all divs with class "tl-item" and attribute "data-dt"
+// and a "dt-future" or "dt-past" class to each div, based on the current date.
+document.addEventListener("DOMContentLoaded", function () {
+  const now = new Date();
+  const nodes = document.querySelectorAll("div.tl-item[data-dt]");
+  for (var i = 0, len = nodes.length; i < len; i++) {
+    try {
+      var dt = new Date(nodes[i].getAttribute("data-dt"));
+    } catch (e) {
+      console.warn(`Error parsing date: ${dt}`);
+      continue;
+    }
+    if (dt > now) {
+      nodes[i].classList.add("dt-future");
+    } else {
+      nodes[i].classList.add("dt-past");
+    }
+  }
+});