Version selector

R/init.R

@@ -72,6 +72,10 @@ copy_assets <- function(pkg = ".") {
     copy_asset_dir(pkg, assets)
   }
 
+  if (has_versions(pkg)) {
+    copy_asset_dir(pkg, path_pkgdown("version-selector"))
+  }
+
   # extras
   copy_asset_dir(pkg, "pkgdown", file_regexp = "^extra")
   # site assets
@@ -157,3 +161,9 @@ is_non_pkgdown_site <- function(dst_path) {
 
   length(top_level) >= 1 && !"pkgdown.yml" %in% path_file(top_level)
 }
+
+has_versions <- function(pkg = ".") {
+  pkg <- as_pkgdown(pkg)
+
+  file.exists(path(pkg$src_path, "pkgdown", "assets", "versions.json"))
+}

R/render.R

@@ -107,6 +107,7 @@ data_template <- function(pkg = ".", depth = 0L) {
     css = path_first_existing(pkg$src_path, "pkgdown", "extra.css"),
     js = path_first_existing(pkg$src_path, "pkgdown", "extra.js")
   )
+  out$version_selector <- has_versions(pkg)
   out$includes <- purrr::pluck(pkg, "meta", "template", "includes", .default = list())
   out$yaml <- purrr::pluck(pkg, "meta", "template", "params", .default = list())
   # Force inclusion so you can reliably refer to objects inside yaml

inst/BS3/templates/head.html

@@ -56,6 +56,10 @@
   {{#js}}<script src="{{#site}}{{root}}{{/site}}extra.js"></script>{{/js}}
 {{/extra}}
 
+{{#version_selector}}
+  <script src="{{#site}}{{root}}{{/site}}version-selector.js"></script>
+{{/version_selector}}
+
 <meta property="og:title" content="{{{pagetitle}}}" />
 {{#opengraph}}
 {{#description}}

inst/BS5/templates/head.html

@@ -46,6 +46,10 @@
   {{#js}}<script src="{{#site}}{{root}}{{/site}}extra.js"></script>{{/js}}
 {{/extra}}
 
+{{#version_selector}}
+  <script src="{{#site}}{{root}}{{/site}}version-selector.js"></script>
+{{/version_selector}}
+
 <meta property="og:title" content="{{{pagetitle}}}" />
 {{#opengraph}}
 {{#description}}

inst/BS5/templates/navbar.html

@@ -4,7 +4,9 @@
     {{#includes}}{{{before_title}}}{{/includes}}
     <a class="navbar-brand me-2" href="{{#site}}{{root}}{{/site}}index.html">{{#site}}{{title}}{{/site}}</a>
 
-    <small class="nav-text {{#development}}text-{{version_label}}{{/development}} me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="{{#development}}{{version_tooltip}}{{/development}}">{{#package}}{{version}}{{/package}}</small>
+    <span class = "version">
+      <small class="nav-text {{#development}}text-{{version_label}}{{/development}} me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="{{#development}}{{version_tooltip}}{{/development}}">{{#package}}{{version}}{{/package}}</small>
+    </span>
 
     {{#includes}}{{{before_navbar}}}{{/includes}}
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="{{#translate}}{{toggle_nav}}{{/translate}}">

inst/version-selector/version-selector.js

@@ -0,0 +1,51 @@
+/**
+ * We need to do this so that the version dropdown doesn't used cached HTML
+ */
+$(window).bind("pageshow", function(event) {
+  if (event.originalEvent.persisted) {
+    window.location.reload()
+  }
+});
+
+$(document).ready(function () {
+
+/**
+ * This replaces the package version number in the docs with a
+ * dropdown where you can select the version of the docs to view.
+ */
+
+  // Load JSON file mapping between docs version and R package version
+  $.getJSON(window.location.origin + "/versions.json", function( data ) {
+    // get the current page's version number:
+    var displayed_version = $('.version').text().trim();
+    // Create a dropdown selector and add the appropriate attributes
+    const sel = document.createElement("select");
+    sel.name = "version-selector";
+    sel.id = "version-selector";
+    sel.classList.add("navbar-default");
+    // When the selected value is changed, take the user to the version
+    // of the page they are browsing in the selected version
+    sel.onchange = function(){
+     if (this.value) window.location.href=this.value;
+    }
+
+    // For each of the items in the JSON object (name/version pairs)
+    $.each( data, function( key, val ) {
+      // Add a new option to the dropdown selector
+      const opt = document.createElement("option");
+      // Set value to the path and the fallback path
+      opt.value = window.location.origin + val.path;
+      // Set the currently selected item based on the major and minor version numbers
+      opt.selected = val.version === displayed_version;
+      // Set the displayed text based on the 'label' field
+      opt.text = val.label;
+      // Add to the selector
+      sel.append(opt);
+    });
+
+    // Replace the HTML "version" component with the new selector
+    $("span.version").replaceWith(sel);
+  });
+});
+
+

tests/testthat/assets/version-dropdown/DESCRIPTION

@@ -0,0 +1,9 @@
+Package: testpackage
+Version: 1.0.0
+Title: A test package
+Description: A longer statement about the package.
+Authors@R: c(
+    person("Hadley", "Wickham", , "[email protected]", role = c("aut", "cre")),
+    person("RStudio", role = c("cph", "fnd"))
+    )
+RoxygenNote: 6.0.1

tests/testthat/assets/version-dropdown/README.md

@@ -0,0 +1,32 @@
+Start off by building the different versions of the package:
+
+```
+devtools::load_all()
+# Build dev version of docs
+override <- list(development = list(mode = "devel"))
+pkg <- as_pkgdown(test_path("assets/version-dropdown/"), override = override)
+pkg$version = "1.0.0.9000"
+build_site(pkg)
+
+# Build previous versions - release (1.0.0)
+pkg <- as_pkgdown(test_path("assets/version-dropdown/"))
+build_site(pkg)
+
+# Build previous versions - oldrel (0.9)
+override <- list(destination = "docs/0.9")
+pkg <- as_pkgdown(test_path("assets/version-dropdown/"), override = override)
+pkg$version = "0.9.0"
+build_site(pkg)
+
+# Build previous versions - oldest (0.8)
+override <- list(destination = "docs/0.8")
+pkg <- as_pkgdown(test_path("assets/version-dropdown/"), override = override)
+pkg$version = "0.8.1"
+build_site(pkg)
+```
+
+Navigate to the correct directory and start up a webserver:
+
+```
+python -m http.server 8080
+```

tests/testthat/assets/version-dropdown/_pkgdown.yml

@@ -0,0 +1,2 @@
+template:
+  bootstrap: 5

tests/testthat/assets/version-dropdown/pkgdown/assets/versions.json

@@ -0,0 +1,22 @@
+[
+    {
+        "label": "1.0.0.9000 (dev)",
+        "version": "1.0.0.9000",
+        "path": "/dev"
+    },
+    {
+        "label": "1.0.0 (release)",
+        "version": "1.0.0",
+        "path": "/"
+    },
+    {
+        "label": "0.9",
+        "version": "0.9.0",
+        "path": "/0.9"
+    },
+    {
+        "label": "0.8 is old",
+        "version": "0.8.1",
+        "path": "/0.8"
+    }
+]