Skip to content

Commit

Permalink
Track if users has dismissed a version warning banner for a given ver…
Browse files Browse the repository at this point in the history
…sion. (#1763)

See #1384

See #1384

If a user dismiss the banner it should apply to all pages.
One remaining questions is :

 - does it apply to all versions ?

This implement a dismiss button and store in local storage which
version and when the user has dismissed it.

This is enough informations to refine the logic later with what/when we want to show.

This also has a rough implementation of not showing banner for current dismissed version for the next 14 days following any banner dismissal.

Co-authored-by: Daniel McCloy <[email protected]>
  • Loading branch information
Carreau and drammock authored May 24, 2024
1 parent 6719f1c commit 7cc72f6
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 5 deletions.
54 changes: 52 additions & 2 deletions src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,28 @@ var getCurrentUrlPath = () => {
return `${DOCUMENTATION_OPTIONS.pagename}.html`;
};

/**
* Allow user to dismiss the warning banner about the docs version being dev / old.
* We store the dismissal date and version, to give us flexibility about making the
* dismissal last for longer than one browser session, if we decide to do that.
*
* @param {event} event the event that trigger the check
*/
async function DismissBannerAndStorePref(event) {
const banner = document.querySelector("#bd-header-version-warning");
banner.remove();
const version = DOCUMENTATION_OPTIONS.VERSION;
const now = new Date();
const banner_pref = JSON.parse(
localStorage.getItem("pst_banner_pref") || "{}",
);
console.debug(
`[PST] Dismissing the version warning banner on ${version} starting ${now}.`,
);
banner_pref[version] = now;
localStorage.setItem("pst_banner_pref", JSON.stringify(banner_pref));
}

/**
* Check if corresponding page path exists in other version of docs
* and, if so, go there instead of the homepage of the other docs version
Expand Down Expand Up @@ -485,23 +507,50 @@ function showVersionWarningBanner(data) {
// if already on preferred version, nothing to do
const versionsAreComparable = validate(version) && validate(preferredVersion);
if (versionsAreComparable && compare(version, preferredVersion, "=")) {
console.log(
"This is the prefered version of the docs, not showing the warning banner.",
);
return;
}
// check if banner has been dismissed recently
const dismiss_date_str = JSON.parse(
localStorage.getItem("pst_banner_pref") || "{}",
)[version];
if (dismiss_date_str != null) {
const dismiss_date = new Date(dismiss_date_str);
const now = new Date();
const milliseconds_in_a_day = 24 * 60 * 60 * 1000;
const days_passed = (now - dismiss_date) / milliseconds_in_a_day;
const timeout_in_days = 14;
if (days_passed < timeout_in_days) {
console.info(
`[PST] Suppressing version warning banner; was dismissed ${Math.floor(days_passed)} day(s) ago`,
);
return;
}
}

// now construct the warning banner
const banner = document.querySelector(".bd-header-version-warning");
const banner = document.querySelector("#bd-header-version-warning");
const middle = document.createElement("div");
const inner = document.createElement("div");
const bold = document.createElement("strong");
const button = document.createElement("a");
const close_btn = document.createElement("a");
// these classes exist since pydata-sphinx-theme v0.10.0
// the init class is used for animation
middle.classList = "bd-header-announcement__content";
middle.classList = "bd-header-announcement__content ms-auto me-auto";
inner.classList = "sidebar-message";
button.classList =
"btn text-wrap font-weight-bold ms-3 my-1 align-baseline pst-button-link-to-stable-version";
button.href = `${preferredURL}${getCurrentUrlPath()}`;
button.innerText = "Switch to stable version";
button.onclick = checkPageExistsAndRedirect;
close_btn.classList = "ms-3 my-1 align-baseline";
const close_x = document.createElement("i");
close_btn.append(close_x);
close_x.classList = "fa-solid fa-xmark";
close_btn.onclick = DismissBannerAndStorePref;
// add the version-dependent text
inner.innerText = "This is documentation for ";
const isDev =
Expand All @@ -520,6 +569,7 @@ function showVersionWarningBanner(data) {
bold.innerText = `version ${version}`;
}
banner.appendChild(middle);
banner.append(close_btn);
middle.appendChild(inner);
inner.appendChild(bold);
inner.appendChild(document.createTextNode("."));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
}
}

.bd-header-version-warning,
#bd-header-version-warning,
.bd-header-announcement {
min-height: 3rem;
width: 100%;
Expand Down Expand Up @@ -69,6 +69,6 @@
background-color: var(--pst-color-secondary-bg);
}

.bd-header-version-warning {
#bd-header-version-warning {
background-color: var(--pst-color-danger-bg);
}
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{#- The "revealer" allows async banners to be loaded, revealed, and animated together in a controlled way -#}
<div class="pst-async-banner-revealer d-none">
{#- Version warning banner is always loaded remotely/asynchronously #}
<aside class="bd-header-version-warning d-none d-print-none" aria-label="{{ _('Version warning') }}"></aside>
<aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="{{ _('Version warning') }}"></aside>
{#- But the announcement banner might be loaded locally or remotely -#}
{%- set announcement_banner_label = _("Announcement") -%}
{%- set announcement_banner_classes = "bd-header-announcement d-print-none" -%}
Expand Down

0 comments on commit 7cc72f6

Please sign in to comment.