From 7e274eb87a36acf9ca35e3f1671ee4eb2d87d9f3 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:47:52 +0000
Subject: [PATCH 01/23] Remove String.startsWith polyfill
---
templates/switchers.js | 9 ---------
1 file changed, 9 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 999ca10..ad31a03 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -1,15 +1,6 @@
(function() {
'use strict';
- if (!String.prototype.startsWith) {
- Object.defineProperty(String.prototype, 'startsWith', {
- value: function(search, rawPos) {
- const pos = rawPos > 0 ? rawPos|0 : 0;
- return this.substring(pos, pos + search.length) === search;
- }
- });
- }
-
// Parses versions in URL segments like:
// "3", "dev", "release/2.7" or "3.6rc2"
const version_regexs = [
From 27e2dc7fbf61c48bd58c79152b5a0480c2d02ef1 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:53:09 +0000
Subject: [PATCH 02/23] Remove create_placeholders_if_missing()
The placeholders have been in the theme since v2021.5
---
templates/switchers.js | 30 ------------------------------
1 file changed, 30 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index ad31a03..ffedb7d 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -132,41 +132,11 @@
return ''
}
- function create_placeholders_if_missing() {
- const version_segment = version_segment_from_url();
- const language_segment = language_segment_from_url();
- const index = "/" + language_segment + version_segment;
-
- if (document.querySelectorAll('.version_switcher_placeholder').length > 0) {
- return;
- }
-
- const html = ' \
- \
-Documentation »';
-
- const probable_places = [
- "body>div.related>ul>li:not(.right):contains('Documentation'):first",
- "body>div.related>ul>li:not(.right):contains('documentation'):first",
- ];
-
- for (let i = 0; i < probable_places.length; i++) {
- let probable_place = $(probable_places[i]);
- if (probable_place.length == 1) {
- probable_place.html(html);
- document.getElementById('indexlink').href = index;
- return;
- }
- }
- }
-
document.addEventListener('DOMContentLoaded', function() {
const language_segment = language_segment_from_url();
const current_language = language_segment.replace(/\/+$/g, '') || 'en';
const version_select = build_version_select(DOCUMENTATION_OPTIONS.VERSION);
- create_placeholders_if_missing();
-
let placeholders = document.querySelectorAll('.version_switcher_placeholder');
placeholders.forEach(function(placeholder) {
placeholder.innerHTML = version_select;
From 75594be5806eb6ed91aecac46a9a4036f734dc02 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:54:10 +0000
Subject: [PATCH 03/23] Use exact comparison operators
---
templates/switchers.js | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index ffedb7d..664db12 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -55,7 +55,7 @@
function navigate_to_first_existing(urls) {
// Navigate to the first existing URL in urls.
const url = urls.shift();
- if (urls.length == 0 || url.startsWith("file:///")) {
+ if (urls.length === 0 || url.startsWith("file:///")) {
window.location.href = url;
return;
}
@@ -79,7 +79,7 @@
const current_version = version_segment_from_url();
const new_url = url.replace('/' + current_language + current_version,
'/' + current_language + selected_version);
- if (new_url != url) {
+ if (new_url !== url) {
navigate_to_first_existing([
new_url,
url.replace('/' + current_language + current_version,
@@ -96,11 +96,11 @@
const url = window.location.href;
const current_language = language_segment_from_url();
const current_version = version_segment_from_url();
- if (selected_language == 'en/') // Special 'default' case for English.
+ if (selected_language === 'en/') // Special 'default' case for English.
selected_language = '';
let new_url = url.replace('/' + current_language + current_version,
'/' + selected_language + current_version);
- if (new_url != url) {
+ if (new_url !== url) {
navigate_to_first_existing([
new_url,
'/'
From 8a71e4273a287deb62e8ed84cc9d837a1a13a0f4 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:56:33 +0000
Subject: [PATCH 04/23] Remove an unneeded variable
---
templates/switchers.js | 9 +++------
1 file changed, 3 insertions(+), 6 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 664db12..70997e1 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -135,10 +135,9 @@
document.addEventListener('DOMContentLoaded', function() {
const language_segment = language_segment_from_url();
const current_language = language_segment.replace(/\/+$/g, '') || 'en';
- const version_select = build_version_select(DOCUMENTATION_OPTIONS.VERSION);
- let placeholders = document.querySelectorAll('.version_switcher_placeholder');
- placeholders.forEach(function(placeholder) {
+ const version_select = build_version_select(DOCUMENTATION_OPTIONS.VERSION);
+ document.querySelectorAll('.version_switcher_placeholder').forEach((placeholder) => {
placeholder.innerHTML = version_select;
let selectElement = placeholder.querySelector('select');
@@ -146,9 +145,7 @@
});
const language_select = build_language_select(current_language);
-
- placeholders = document.querySelectorAll('.language_switcher_placeholder');
- placeholders.forEach(function(placeholder) {
+ document.querySelectorAll('.language_switcher_placeholder').forEach((placeholder) => {
placeholder.innerHTML = language_select;
let selectElement = placeholder.querySelector('select');
From ce8b4742aa957612ce6734b78bdf6e242a6bd43c Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:57:55 +0000
Subject: [PATCH 05/23] Remove anonymous function (IIFE)
---
templates/switchers.js | 284 ++++++++++++++++++++---------------------
1 file changed, 141 insertions(+), 143 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 70997e1..d436d5e 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -1,155 +1,153 @@
-(function() {
- 'use strict';
-
- // Parses versions in URL segments like:
- // "3", "dev", "release/2.7" or "3.6rc2"
- const version_regexs = [
- '(?:\\d)',
- '(?:\\d\\.\\d[\\w\\d\\.]*)',
- '(?:dev)',
- '(?:release/\\d.\\d[\\x\\d\\.]*)'];
-
- const all_versions = $VERSIONS;
- const all_languages = $LANGUAGES;
-
- function quote_attr(str) {
- return '"' + str.replace('"', '\\"') + '"';
- }
+'use strict';
+
+// Parses versions in URL segments like:
+// "3", "dev", "release/2.7" or "3.6rc2"
+const version_regexs = [
+ '(?:\\d)',
+ '(?:\\d\\.\\d[\\w\\d\\.]*)',
+ '(?:dev)',
+ '(?:release/\\d.\\d[\\x\\d\\.]*)'];
+
+const all_versions = $VERSIONS;
+const all_languages = $LANGUAGES;
+
+function quote_attr(str) {
+ return '"' + str.replace('"', '\\"') + '"';
+}
+
+function build_version_select(release) {
+ let buf = ['');
- return buf.join('');
- }
-
- function navigate_to_first_existing(urls) {
- // Navigate to the first existing URL in urls.
- const url = urls.shift();
- if (urls.length === 0 || url.startsWith("file:///")) {
- window.location.href = url;
- return;
- }
- fetch(url)
- .then(function(response) {
- if (response.ok) {
- window.location.href = url;
- } else {
- navigate_to_first_existing(urls);
- }
- })
- .catch(function(error) {
- navigate_to_first_existing(urls);
- });
- }
-
- function on_version_switch() {
- const selected_version = this.options[this.selectedIndex].value + '/';
- const url = window.location.href;
- const current_language = language_segment_from_url();
- const current_version = version_segment_from_url();
- const new_url = url.replace('/' + current_language + current_version,
- '/' + current_language + selected_version);
- if (new_url !== url) {
- navigate_to_first_existing([
- new_url,
- url.replace('/' + current_language + current_version,
- '/' + selected_version),
- '/' + current_language + selected_version,
- '/' + selected_version,
- '/'
- ]);
- }
- }
-
- function on_language_switch() {
- let selected_language = this.options[this.selectedIndex].value + '/';
- const url = window.location.href;
- const current_language = language_segment_from_url();
- const current_version = version_segment_from_url();
- if (selected_language === 'en/') // Special 'default' case for English.
- selected_language = '';
- let new_url = url.replace('/' + current_language + current_version,
- '/' + selected_language + current_version);
- if (new_url !== url) {
- navigate_to_first_existing([
- new_url,
- '/'
- ]);
- }
- }
-
- // Returns the path segment of the language as a string, like 'fr/'
- // or '' if not found.
- function language_segment_from_url() {
- const path = window.location.pathname;
- const language_regexp = '/((?:' + Object.keys(all_languages).join("|") + ')/)'
- const match = path.match(language_regexp);
- if (match !== null)
- return match[1];
- return '';
+}
+
+function on_version_switch() {
+ const selected_version = this.options[this.selectedIndex].value + '/';
+ const url = window.location.href;
+ const current_language = language_segment_from_url();
+ const current_version = version_segment_from_url();
+ const new_url = url.replace('/' + current_language + current_version,
+ '/' + current_language + selected_version);
+ if (new_url !== url) {
+ navigate_to_first_existing([
+ new_url,
+ url.replace('/' + current_language + current_version,
+ '/' + selected_version),
+ '/' + current_language + selected_version,
+ '/' + selected_version,
+ '/'
+ ]);
}
-
- // Returns the path segment of the version as a string, like '3.6/'
- // or '' if not found.
- function version_segment_from_url() {
- const path = window.location.pathname;
- const language_segment = language_segment_from_url();
- const version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
- const version_regexp = language_segment + '(' + version_segment + ')';
- const match = path.match(version_regexp);
- if (match !== null)
- return match[1];
- return ''
+}
+
+function on_language_switch() {
+ let selected_language = this.options[this.selectedIndex].value + '/';
+ const url = window.location.href;
+ const current_language = language_segment_from_url();
+ const current_version = version_segment_from_url();
+ if (selected_language === 'en/') // Special 'default' case for English.
+ selected_language = '';
+ let new_url = url.replace('/' + current_language + current_version,
+ '/' + selected_language + current_version);
+ if (new_url !== url) {
+ navigate_to_first_existing([
+ new_url,
+ '/'
+ ]);
}
+}
+
+// Returns the path segment of the language as a string, like 'fr/'
+// or '' if not found.
+function language_segment_from_url() {
+ const path = window.location.pathname;
+ const language_regexp = '/((?:' + Object.keys(all_languages).join("|") + ')/)'
+ const match = path.match(language_regexp);
+ if (match !== null)
+ return match[1];
+ return '';
+}
+
+// Returns the path segment of the version as a string, like '3.6/'
+// or '' if not found.
+function version_segment_from_url() {
+ const path = window.location.pathname;
+ const language_segment = language_segment_from_url();
+ const version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
+ const version_regexp = language_segment + '(' + version_segment + ')';
+ const match = path.match(version_regexp);
+ if (match !== null)
+ return match[1];
+ return ''
+}
+
+document.addEventListener('DOMContentLoaded', function() {
+ const language_segment = language_segment_from_url();
+ const current_language = language_segment.replace(/\/+$/g, '') || 'en';
+
+ const version_select = build_version_select(DOCUMENTATION_OPTIONS.VERSION);
+ document.querySelectorAll('.version_switcher_placeholder').forEach((placeholder) => {
+ placeholder.innerHTML = version_select;
+
+ let selectElement = placeholder.querySelector('select');
+ selectElement.addEventListener('change', on_version_switch);
+ });
- document.addEventListener('DOMContentLoaded', function() {
- const language_segment = language_segment_from_url();
- const current_language = language_segment.replace(/\/+$/g, '') || 'en';
-
- const version_select = build_version_select(DOCUMENTATION_OPTIONS.VERSION);
- document.querySelectorAll('.version_switcher_placeholder').forEach((placeholder) => {
- placeholder.innerHTML = version_select;
-
- let selectElement = placeholder.querySelector('select');
- selectElement.addEventListener('change', on_version_switch);
- });
-
- const language_select = build_language_select(current_language);
- document.querySelectorAll('.language_switcher_placeholder').forEach((placeholder) => {
- placeholder.innerHTML = language_select;
+ const language_select = build_language_select(current_language);
+ document.querySelectorAll('.language_switcher_placeholder').forEach((placeholder) => {
+ placeholder.innerHTML = language_select;
- let selectElement = placeholder.querySelector('select');
- selectElement.addEventListener('change', on_language_switch);
- });
+ let selectElement = placeholder.querySelector('select');
+ selectElement.addEventListener('change', on_language_switch);
});
-})();
+});
From cdcd52305ee0b7b6d88f2cf859ae5d2f37e2ddd3 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:59:28 +0000
Subject: [PATCH 06/23] Name the initialisation function
---
templates/switchers.js | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index d436d5e..8bdf3d5 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -130,8 +130,7 @@ function version_segment_from_url() {
return match[1];
return ''
}
-
-document.addEventListener('DOMContentLoaded', function() {
+const _initialise_switchers = () => {
const language_segment = language_segment_from_url();
const current_language = language_segment.replace(/\/+$/g, '') || 'en';
@@ -150,4 +149,10 @@ document.addEventListener('DOMContentLoaded', function() {
let selectElement = placeholder.querySelector('select');
selectElement.addEventListener('change', on_language_switch);
});
-});
+};
+
+if (document.readyState !== 'loading') {
+ _initialise_switchers();
+} else {
+ document.addEventListener('DOMContentLoaded', _initialise_switchers);
+}
From 84a3f9c5d8794fa20e738ddf195d2f6c0abb36f7 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 14:09:38 +0000
Subject: [PATCH 07/23] Construct DOM nodes instead of parsing HTML
---
templates/switchers.js | 90 ++++++++++++++++++++++--------------------
1 file changed, 48 insertions(+), 42 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 8bdf3d5..094c2ce 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -15,41 +15,45 @@ function quote_attr(str) {
return '"' + str.replace('"', '\\"') + '"';
}
-function build_version_select(release) {
- let buf = ['');
- return buf.join('');
-}
+ select.add(option);
+ }
-function build_language_select(current_language) {
- let buf = ['');
- return buf.join('');
-}
+
+ const select = document.createElement('select');
+ select.className = 'language-select';
+
+ for (const [language, title] in all_languages) {
+ const option = document.createElement('option');
+ option.value = language;
+ option.text = title;
+ if (language === current_language) option.selected = true;
+ select.add(option);
+ }
+
+ return select;
+};
function navigate_to_first_existing(urls) {
// Navigate to the first existing URL in urls.
@@ -134,21 +138,23 @@ const _initialise_switchers = () => {
const language_segment = language_segment_from_url();
const current_language = language_segment.replace(/\/+$/g, '') || 'en';
- const version_select = build_version_select(DOCUMENTATION_OPTIONS.VERSION);
- document.querySelectorAll('.version_switcher_placeholder').forEach((placeholder) => {
- placeholder.innerHTML = version_select;
-
- let selectElement = placeholder.querySelector('select');
- selectElement.addEventListener('change', on_version_switch);
- });
-
- const language_select = build_language_select(current_language);
- document.querySelectorAll('.language_switcher_placeholder').forEach((placeholder) => {
- placeholder.innerHTML = language_select;
+ const version_select = _create_version_select(DOCUMENTATION_OPTIONS.VERSION);
+ document
+ .querySelectorAll('.version_switcher_placeholder')
+ .forEach((placeholder) => {
+ const s = version_select.cloneNode(true);
+ s.addEventListener('change', on_version_switch);
+ placeholder.append(s);
+ });
- let selectElement = placeholder.querySelector('select');
- selectElement.addEventListener('change', on_language_switch);
- });
+ const language_select = _create_language_select(current_language);
+ document
+ .querySelectorAll('.language_switcher_placeholder')
+ .forEach((placeholder) => {
+ const s = language_select.cloneNode(true);
+ s.addEventListener('change', on_language_switch);
+ placeholder.append(s);
+ });
};
if (document.readyState !== 'loading') {
From 2a5adf99c1af5d8b2f1874c696651ca72c2a0518 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 14:18:22 +0000
Subject: [PATCH 08/23] Use arrow functions
---
templates/switchers.js | 25 +++++++++++++------------
1 file changed, 13 insertions(+), 12 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 094c2ce..b5b46ba 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -55,7 +55,7 @@ const _create_language_select = (current_language) => {
return select;
};
-function navigate_to_first_existing(urls) {
+const _navigate_to_first_existing = (urls) => {
// Navigate to the first existing URL in urls.
const url = urls.shift();
if (urls.length === 0 || url.startsWith("file:///")) {
@@ -63,19 +63,20 @@ function navigate_to_first_existing(urls) {
return;
}
fetch(url)
- .then(function(response) {
+ .then((response) => {
if (response.ok) {
window.location.href = url;
} else {
navigate_to_first_existing(urls);
}
})
- .catch(function(error) {
+ .catch((err) => {
+ void err;
navigate_to_first_existing(urls);
});
-}
+};
-function on_version_switch() {
+const _on_version_switch = () => {
const selected_version = this.options[this.selectedIndex].value + '/';
const url = window.location.href;
const current_language = language_segment_from_url();
@@ -83,7 +84,7 @@ function on_version_switch() {
const new_url = url.replace('/' + current_language + current_version,
'/' + current_language + selected_version);
if (new_url !== url) {
- navigate_to_first_existing([
+ _navigate_to_first_existing([
new_url,
url.replace('/' + current_language + current_version,
'/' + selected_version),
@@ -92,9 +93,9 @@ function on_version_switch() {
'/'
]);
}
-}
+};
-function on_language_switch() {
+const _on_language_switch = () => {
let selected_language = this.options[this.selectedIndex].value + '/';
const url = window.location.href;
const current_language = language_segment_from_url();
@@ -104,12 +105,12 @@ function on_language_switch() {
let new_url = url.replace('/' + current_language + current_version,
'/' + selected_language + current_version);
if (new_url !== url) {
- navigate_to_first_existing([
+ _navigate_to_first_existing([
new_url,
'/'
]);
}
-}
+};
// Returns the path segment of the language as a string, like 'fr/'
// or '' if not found.
@@ -143,7 +144,7 @@ const _initialise_switchers = () => {
.querySelectorAll('.version_switcher_placeholder')
.forEach((placeholder) => {
const s = version_select.cloneNode(true);
- s.addEventListener('change', on_version_switch);
+ s.addEventListener('change', _on_version_switch);
placeholder.append(s);
});
@@ -152,7 +153,7 @@ const _initialise_switchers = () => {
.querySelectorAll('.language_switcher_placeholder')
.forEach((placeholder) => {
const s = language_select.cloneNode(true);
- s.addEventListener('change', on_language_switch);
+ s.addEventListener('change', _on_language_switch);
placeholder.append(s);
});
};
From b4b36c0983a8693cdfdd743268630678c737b158 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 14:18:37 +0000
Subject: [PATCH 09/23] Remove unused quote_attr() function
---
templates/switchers.js | 4 ----
1 file changed, 4 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index b5b46ba..d70fc8f 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -11,10 +11,6 @@ const version_regexs = [
const all_versions = $VERSIONS;
const all_languages = $LANGUAGES;
-function quote_attr(str) {
- return '"' + str.replace('"', '\\"') + '"';
-}
-
const _create_version_select = (release) => {
const major_minor = release.split('.').slice(0, 2).join('.');
const select = document.createElement('select');
From 2cac9f627ffc927ade8c09b3b0eec45181ff7c46 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 14:25:08 +0000
Subject: [PATCH 10/23] Run prettier
---
templates/switchers.js | 44 +++++++++++++++++++++++-------------------
1 file changed, 24 insertions(+), 20 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index d70fc8f..1b7a71d 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -6,7 +6,8 @@ const version_regexs = [
'(?:\\d)',
'(?:\\d\\.\\d[\\w\\d\\.]*)',
'(?:dev)',
- '(?:release/\\d.\\d[\\x\\d\\.]*)'];
+ '(?:release/\\d.\\d[\\x\\d\\.]*)',
+];
const all_versions = $VERSIONS;
const all_languages = $LANGUAGES;
@@ -54,7 +55,7 @@ const _create_language_select = (current_language) => {
const _navigate_to_first_existing = (urls) => {
// Navigate to the first existing URL in urls.
const url = urls.shift();
- if (urls.length === 0 || url.startsWith("file:///")) {
+ if (urls.length === 0 || url.startsWith('file:///')) {
window.location.href = url;
return;
}
@@ -77,16 +78,20 @@ const _on_version_switch = () => {
const url = window.location.href;
const current_language = language_segment_from_url();
const current_version = version_segment_from_url();
- const new_url = url.replace('/' + current_language + current_version,
- '/' + current_language + selected_version);
+ const new_url = url.replace(
+ '/' + current_language + current_version,
+ '/' + current_language + selected_version,
+ );
if (new_url !== url) {
_navigate_to_first_existing([
new_url,
- url.replace('/' + current_language + current_version,
- '/' + selected_version),
+ url.replace(
+ '/' + current_language + current_version,
+ '/' + selected_version,
+ ),
'/' + current_language + selected_version,
'/' + selected_version,
- '/'
+ '/',
]);
}
};
@@ -96,15 +101,15 @@ const _on_language_switch = () => {
const url = window.location.href;
const current_language = language_segment_from_url();
const current_version = version_segment_from_url();
- if (selected_language === 'en/') // Special 'default' case for English.
+ if (selected_language === 'en/')
+ // Special 'default' case for English.
selected_language = '';
- let new_url = url.replace('/' + current_language + current_version,
- '/' + selected_language + current_version);
+ let new_url = url.replace(
+ '/' + current_language + current_version,
+ '/' + selected_language + current_version,
+ );
if (new_url !== url) {
- _navigate_to_first_existing([
- new_url,
- '/'
- ]);
+ _navigate_to_first_existing([new_url, '/']);
}
};
@@ -112,10 +117,10 @@ const _on_language_switch = () => {
// or '' if not found.
function language_segment_from_url() {
const path = window.location.pathname;
- const language_regexp = '/((?:' + Object.keys(all_languages).join("|") + ')/)'
+ const language_regexp =
+ '/((?:' + Object.keys(all_languages).join('|') + ')/)';
const match = path.match(language_regexp);
- if (match !== null)
- return match[1];
+ if (match !== null) return match[1];
return '';
}
@@ -127,9 +132,8 @@ function version_segment_from_url() {
const version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
const version_regexp = language_segment + '(' + version_segment + ')';
const match = path.match(version_regexp);
- if (match !== null)
- return match[1];
- return ''
+ if (match !== null) return match[1];
+ return '';
}
const _initialise_switchers = () => {
const language_segment = language_segment_from_url();
From 7b5e7730954e7b788195ecddb12f8f7056b92675 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 14:29:30 +0000
Subject: [PATCH 11/23] Make the regular expression for version parts a
constant
---
templates/switchers.js | 19 +++++++++----------
1 file changed, 9 insertions(+), 10 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 1b7a71d..6b12e32 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -1,13 +1,14 @@
'use strict';
// Parses versions in URL segments like:
-// "3", "dev", "release/2.7" or "3.6rc2"
-const version_regexs = [
- '(?:\\d)',
- '(?:\\d\\.\\d[\\w\\d\\.]*)',
- '(?:dev)',
- '(?:release/\\d.\\d[\\x\\d\\.]*)',
-];
+const _VERSION_PATTERN = (
+ '((?:'
+ + '(?:\\d)' // e.g. "3"
+ +'|(?:\\d\\.\\d[\\w\\d\\.]*)' // e.g. "3.6rc2"
+ +'|(?:dev)' // e.g. "dev"
+ +'|(?:release/\\d.\\d[\\x\\d\\.]*)'// e.g. "release/2.7"
+ + ')/)'
+);
const all_versions = $VERSIONS;
const all_languages = $LANGUAGES;
@@ -128,9 +129,7 @@ function language_segment_from_url() {
// or '' if not found.
function version_segment_from_url() {
const path = window.location.pathname;
- const language_segment = language_segment_from_url();
- const version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
- const version_regexp = language_segment + '(' + version_segment + ')';
+ const version_regexp = language_segment_from_url() + _VERSION_PATTERN;
const match = path.match(version_regexp);
if (match !== null) return match[1];
return '';
From ab3b07962977ace9fea0c8c4034d53cb129872d0 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 15:05:32 +0000
Subject: [PATCH 12/23] Use constants from DOCUMENTATION_OPTIONS where possible
---
templates/switchers.js | 39 +++++++++++++++++++++------------------
1 file changed, 21 insertions(+), 18 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 6b12e32..f98de05 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -1,5 +1,18 @@
'use strict';
+const _CURRENT_VERSION = DOCUMENTATION_OPTIONS.VERSION;
+const _CURRENT_LANGUAGE = DOCUMENTATION_OPTIONS.LANGUAGE?.toLowerCase() || 'en';
+const _CURRENT_PREFIX = (() => {
+ // Sphinx 7.2+ defines the content root data attribute in the HTML element.
+ const _CONTENT_ROOT = document.documentElement.dataset.content_root;
+ if (_CONTENT_ROOT !== undefined) {
+ return new URL(_CONTENT_ROOT, window.location).pathname;
+ }
+ // Fallback for older versions of Sphinx (used in Python 3.10 and older).
+ const _NUM_PREFIX_PARTS = _CURRENT_LANGUAGE === 'en' ? 2 : 3;
+ return window.location.pathname.split('/', _NUM_PREFIX_PARTS).join('/') + '/';
+})();
+
// Parses versions in URL segments like:
const _VERSION_PATTERN = (
'((?:'
@@ -77,20 +90,15 @@ const _navigate_to_first_existing = (urls) => {
const _on_version_switch = () => {
const selected_version = this.options[this.selectedIndex].value + '/';
const url = window.location.href;
- const current_language = language_segment_from_url();
- const current_version = version_segment_from_url();
const new_url = url.replace(
- '/' + current_language + current_version,
- '/' + current_language + selected_version,
+ _CURRENT_PREFIX,
+ '/' + _CURRENT_LANGUAGE + selected_version,
);
if (new_url !== url) {
_navigate_to_first_existing([
new_url,
- url.replace(
- '/' + current_language + current_version,
- '/' + selected_version,
- ),
- '/' + current_language + selected_version,
+ url.replace(_CURRENT_PREFIX, '/' + selected_version),
+ '/' + _CURRENT_LANGUAGE + selected_version,
'/' + selected_version,
'/',
]);
@@ -100,14 +108,12 @@ const _on_version_switch = () => {
const _on_language_switch = () => {
let selected_language = this.options[this.selectedIndex].value + '/';
const url = window.location.href;
- const current_language = language_segment_from_url();
- const current_version = version_segment_from_url();
if (selected_language === 'en/')
// Special 'default' case for English.
selected_language = '';
let new_url = url.replace(
- '/' + current_language + current_version,
- '/' + selected_language + current_version,
+ _CURRENT_PREFIX,
+ '/' + selected_language + _CURRENT_VERSION,
);
if (new_url !== url) {
_navigate_to_first_existing([new_url, '/']);
@@ -135,10 +141,7 @@ function version_segment_from_url() {
return '';
}
const _initialise_switchers = () => {
- const language_segment = language_segment_from_url();
- const current_language = language_segment.replace(/\/+$/g, '') || 'en';
-
- const version_select = _create_version_select(DOCUMENTATION_OPTIONS.VERSION);
+ const version_select = _create_version_select(_CURRENT_VERSION);
document
.querySelectorAll('.version_switcher_placeholder')
.forEach((placeholder) => {
@@ -147,7 +150,7 @@ const _initialise_switchers = () => {
placeholder.append(s);
});
- const language_select = _create_language_select(current_language);
+ const language_select = _create_language_select(_CURRENT_LANGUAGE);
document
.querySelectorAll('.language_switcher_placeholder')
.forEach((placeholder) => {
From a5936462d9811cd843ddb9337208272d996a098d Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 15:06:10 +0000
Subject: [PATCH 13/23] Remove now-unused segment_from_url() functions
---
templates/switchers.js | 30 ------------------------------
1 file changed, 30 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index f98de05..600c955 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -13,16 +13,6 @@ const _CURRENT_PREFIX = (() => {
return window.location.pathname.split('/', _NUM_PREFIX_PARTS).join('/') + '/';
})();
-// Parses versions in URL segments like:
-const _VERSION_PATTERN = (
- '((?:'
- + '(?:\\d)' // e.g. "3"
- +'|(?:\\d\\.\\d[\\w\\d\\.]*)' // e.g. "3.6rc2"
- +'|(?:dev)' // e.g. "dev"
- +'|(?:release/\\d.\\d[\\x\\d\\.]*)'// e.g. "release/2.7"
- + ')/)'
-);
-
const all_versions = $VERSIONS;
const all_languages = $LANGUAGES;
@@ -120,26 +110,6 @@ const _on_language_switch = () => {
}
};
-// Returns the path segment of the language as a string, like 'fr/'
-// or '' if not found.
-function language_segment_from_url() {
- const path = window.location.pathname;
- const language_regexp =
- '/((?:' + Object.keys(all_languages).join('|') + ')/)';
- const match = path.match(language_regexp);
- if (match !== null) return match[1];
- return '';
-}
-
-// Returns the path segment of the version as a string, like '3.6/'
-// or '' if not found.
-function version_segment_from_url() {
- const path = window.location.pathname;
- const version_regexp = language_segment_from_url() + _VERSION_PATTERN;
- const match = path.match(version_regexp);
- if (match !== null) return match[1];
- return '';
-}
const _initialise_switchers = () => {
const version_select = _create_version_select(_CURRENT_VERSION);
document
From b62ea7a325fb2dc53350f07be9c0129de1f11c6a Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 15:08:12 +0000
Subject: [PATCH 14/23] Use the event argument of select element callback
functions
---
templates/switchers.js | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 600c955..dbd4809 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -77,8 +77,8 @@ const _navigate_to_first_existing = (urls) => {
});
};
-const _on_version_switch = () => {
- const selected_version = this.options[this.selectedIndex].value + '/';
+const _on_version_switch = (event) => {
+ const selected_version = event.target.value + '/';
const url = window.location.href;
const new_url = url.replace(
_CURRENT_PREFIX,
@@ -95,8 +95,8 @@ const _on_version_switch = () => {
}
};
-const _on_language_switch = () => {
- let selected_language = this.options[this.selectedIndex].value + '/';
+const _on_language_switch = (event) => {
+ let selected_language = event.target.value + '/';
const url = window.location.href;
if (selected_language === 'en/')
// Special 'default' case for English.
From e5b53bbf6d545d0d95cff2b9f74c1f602efb2511 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 15:43:21 +0000
Subject: [PATCH 15/23] Improve logic for the callback functions
---
templates/switchers.js | 90 ++++++++++++++++++++++++------------------
1 file changed, 51 insertions(+), 39 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index dbd4809..ababf04 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -58,55 +58,67 @@ const _create_language_select = (current_language) => {
const _navigate_to_first_existing = (urls) => {
// Navigate to the first existing URL in urls.
- const url = urls.shift();
- if (urls.length === 0 || url.startsWith('file:///')) {
- window.location.href = url;
- return;
+ for (const url of urls) {
+ if (url.startsWith('file:///')) {
+ window.location.href = url;
+ return;
+ }
+ fetch(url)
+ .then((response) => {
+ if (response.ok) {
+ window.location.href = url;
+ return url;
+ }
+ })
+ .catch((err) => {
+ console.error(`Error when fetching '${url}'!`);
+ console.error(err);
+ });
}
- fetch(url)
- .then((response) => {
- if (response.ok) {
- window.location.href = url;
- } else {
- navigate_to_first_existing(urls);
- }
- })
- .catch((err) => {
- void err;
- navigate_to_first_existing(urls);
- });
+
+ // if all else fails, redirect to the d.p.o root
+ window.location.href = '/';
+ return '/';
};
const _on_version_switch = (event) => {
- const selected_version = event.target.value + '/';
- const url = window.location.href;
- const new_url = url.replace(
- _CURRENT_PREFIX,
- '/' + _CURRENT_LANGUAGE + selected_version,
- );
- if (new_url !== url) {
+ const selected_version = event.target.value;
+ // English has no language prefix.
+ const new_prefix_en = `/${selected_version}/`;
+ const new_prefix =
+ _CURRENT_LANGUAGE === 'en'
+ ? new_prefix_en
+ : `/${_CURRENT_LANGUAGE}/${selected_version}/`;
+ if (_CURRENT_PREFIX !== new_prefix) {
+ // Try the following pages in order:
+ // 1. The current page in the current language with the new version
+ // 2. The current page in English with the new version
+ // 3. The documentation home in the current language with the new version
+ // 4. The documentation home in English with the new version
_navigate_to_first_existing([
- new_url,
- url.replace(_CURRENT_PREFIX, '/' + selected_version),
- '/' + _CURRENT_LANGUAGE + selected_version,
- '/' + selected_version,
- '/',
+ window.location.href.replace(_CURRENT_PREFIX, new_prefix),
+ window.location.href.replace(_CURRENT_PREFIX, new_prefix_en),
+ new_prefix,
+ new_prefix_en,
]);
}
};
const _on_language_switch = (event) => {
- let selected_language = event.target.value + '/';
- const url = window.location.href;
- if (selected_language === 'en/')
- // Special 'default' case for English.
- selected_language = '';
- let new_url = url.replace(
- _CURRENT_PREFIX,
- '/' + selected_language + _CURRENT_VERSION,
- );
- if (new_url !== url) {
- _navigate_to_first_existing([new_url, '/']);
+ const selected_language = event.target.value;
+ // English has no language prefix.
+ const new_prefix =
+ selected_language === 'en'
+ ? `/${_CURRENT_VERSION}/`
+ : `/${selected_language}/${_CURRENT_VERSION}/`;
+ if (_CURRENT_PREFIX !== new_prefix) {
+ // Try the following pages in order:
+ // 1. The current page in the new language with the current version
+ // 2. The documentation home in the new language with the current version
+ _navigate_to_first_existing([
+ window.location.href.replace(_CURRENT_PREFIX, new_prefix),
+ new_prefix,
+ ]);
}
};
From 1179ee9d3b62ee38f978ffa6b97e311b2775d230 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 15:49:33 +0000
Subject: [PATCH 16/23] Iterate over arrays with for...of
---
templates/switchers.js | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index ababf04..af73ced 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -21,7 +21,7 @@ const _create_version_select = (release) => {
const select = document.createElement('select');
select.className = 'version-select';
- for (const [version, title] in all_versions) {
+ for (const [version, title] of Object.entries(all_versions)) {
const option = document.createElement('option');
option.value = version;
if (version === major_minor) {
@@ -45,7 +45,7 @@ const _create_language_select = (current_language) => {
const select = document.createElement('select');
select.className = 'language-select';
- for (const [language, title] in all_languages) {
+ for (const [language, title] of Object.entries(all_languages)) {
const option = document.createElement('option');
option.value = language;
option.text = title;
From d1b7ad8450b1ef58b307c61882c0336c60ef1276 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 15:52:54 +0000
Subject: [PATCH 17/23] Fix _CURRENT_VERSION for pre-releases
---
templates/switchers.js | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index af73ced..afa26f4 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -1,6 +1,7 @@
'use strict';
-const _CURRENT_VERSION = DOCUMENTATION_OPTIONS.VERSION;
+const _CURRENT_RELEASE = DOCUMENTATION_OPTIONS.VERSION || '';
+const _CURRENT_VERSION = _CURRENT_RELEASE.split('.', 2).join('.');
const _CURRENT_LANGUAGE = DOCUMENTATION_OPTIONS.LANGUAGE?.toLowerCase() || 'en';
const _CURRENT_PREFIX = (() => {
// Sphinx 7.2+ defines the content root data attribute in the HTML element.
From 7efb6bf363a2f22338d0f9732e39895fa28abbe7 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:00:10 +0000
Subject: [PATCH 18/23] Use _CURRENT_RELEASE in _create_version_select()
---
templates/switchers.js | 9 ++++-----
1 file changed, 4 insertions(+), 5 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index afa26f4..774f04e 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -17,16 +17,15 @@ const _CURRENT_PREFIX = (() => {
const all_versions = $VERSIONS;
const all_languages = $LANGUAGES;
-const _create_version_select = (release) => {
- const major_minor = release.split('.').slice(0, 2).join('.');
+const _create_version_select = () => {
const select = document.createElement('select');
select.className = 'version-select';
for (const [version, title] of Object.entries(all_versions)) {
const option = document.createElement('option');
option.value = version;
- if (version === major_minor) {
- option.text = release;
+ if (version === _CURRENT_VERSION) {
+ option.text = _CURRENT_RELEASE;
option.selected = true;
} else {
option.text = title;
@@ -124,7 +123,7 @@ const _on_language_switch = (event) => {
};
const _initialise_switchers = () => {
- const version_select = _create_version_select(_CURRENT_VERSION);
+ const version_select = _create_version_select();
document
.querySelectorAll('.version_switcher_placeholder')
.forEach((placeholder) => {
From 359c393d92dbec5f383b974652f19259edf9fdbb Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:02:14 +0000
Subject: [PATCH 19/23] Use _CURRENT_LANGUAGE in _create_language_select()
---
templates/switchers.js | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 774f04e..740cc12 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -36,10 +36,10 @@ const _create_version_select = () => {
return select;
};
-const _create_language_select = (current_language) => {
- if (!(current_language in all_languages)) {
+const _create_language_select = () => {
+ if (!(_CURRENT_LANGUAGE in all_languages)) {
// In case we are browsing a language that is not yet in all_languages.
- all_languages[current_language] = current_language;
+ all_languages[_CURRENT_LANGUAGE] = _CURRENT_LANGUAGE;
}
const select = document.createElement('select');
@@ -49,7 +49,7 @@ const _create_language_select = (current_language) => {
const option = document.createElement('option');
option.value = language;
option.text = title;
- if (language === current_language) option.selected = true;
+ if (language === _CURRENT_LANGUAGE) option.selected = true;
select.add(option);
}
@@ -132,7 +132,7 @@ const _initialise_switchers = () => {
placeholder.append(s);
});
- const language_select = _create_language_select(_CURRENT_LANGUAGE);
+ const language_select = _create_language_select();
document
.querySelectorAll('.language_switcher_placeholder')
.forEach((placeholder) => {
From e55b26c44c6410d2720d8d4b0b73d5140a29721e Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:05:57 +0000
Subject: [PATCH 20/23] Add better handling for file URIs
---
templates/switchers.js | 21 +++++++++++++++++----
1 file changed, 17 insertions(+), 4 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index 740cc12..025daed 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -1,9 +1,14 @@
'use strict';
+// File URIs must begin with either one or three forward slashes
+const _is_file_uri = (uri) => uri.startsWith('file:/');
+
+const _IS_LOCAL = _is_file_uri(window.location.href);
const _CURRENT_RELEASE = DOCUMENTATION_OPTIONS.VERSION || '';
const _CURRENT_VERSION = _CURRENT_RELEASE.split('.', 2).join('.');
const _CURRENT_LANGUAGE = DOCUMENTATION_OPTIONS.LANGUAGE?.toLowerCase() || 'en';
const _CURRENT_PREFIX = (() => {
+ if (_IS_LOCAL) return null;
// Sphinx 7.2+ defines the content root data attribute in the HTML element.
const _CONTENT_ROOT = document.documentElement.dataset.content_root;
if (_CONTENT_ROOT !== undefined) {
@@ -20,6 +25,10 @@ const all_languages = $LANGUAGES;
const _create_version_select = () => {
const select = document.createElement('select');
select.className = 'version-select';
+ if (_IS_LOCAL) {
+ select.disabled = true;
+ select.title = 'Version switching is disabled in local builds';
+ }
for (const [version, title] of Object.entries(all_versions)) {
const option = document.createElement('option');
@@ -44,6 +53,10 @@ const _create_language_select = () => {
const select = document.createElement('select');
select.className = 'language-select';
+ if (_IS_LOCAL) {
+ select.disabled = true;
+ select.title = 'Language switching is disabled in local builds';
+ }
for (const [language, title] of Object.entries(all_languages)) {
const option = document.createElement('option');
@@ -59,10 +72,6 @@ const _create_language_select = () => {
const _navigate_to_first_existing = (urls) => {
// Navigate to the first existing URL in urls.
for (const url of urls) {
- if (url.startsWith('file:///')) {
- window.location.href = url;
- return;
- }
fetch(url)
.then((response) => {
if (response.ok) {
@@ -82,6 +91,8 @@ const _navigate_to_first_existing = (urls) => {
};
const _on_version_switch = (event) => {
+ if (_IS_LOCAL) return;
+
const selected_version = event.target.value;
// English has no language prefix.
const new_prefix_en = `/${selected_version}/`;
@@ -105,6 +116,8 @@ const _on_version_switch = (event) => {
};
const _on_language_switch = (event) => {
+ if (_IS_LOCAL) return;
+
const selected_language = event.target.value;
// English has no language prefix.
const new_prefix =
From 4c495ccf8bb0eb512a4b7acba7b6d682babdf91c Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:35:03 +0000
Subject: [PATCH 21/23] Remove placeholder classes when initialisation is
complete
---
templates/switchers.js | 2 ++
1 file changed, 2 insertions(+)
diff --git a/templates/switchers.js b/templates/switchers.js
index 025daed..c6dd30e 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -143,6 +143,7 @@ const _initialise_switchers = () => {
const s = version_select.cloneNode(true);
s.addEventListener('change', _on_version_switch);
placeholder.append(s);
+ placeholder.classList.remove('version_switcher_placeholder');
});
const language_select = _create_language_select();
@@ -152,6 +153,7 @@ const _initialise_switchers = () => {
const s = language_select.cloneNode(true);
s.addEventListener('change', _on_language_switch);
placeholder.append(s);
+ placeholder.classList.remove('language_switcher_placeholder');
});
};
From 3031085ac20893336bd9f317b66d97db0ce21af1 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:46:44 +0000
Subject: [PATCH 22/23] Use a Map for versions and languages
---
templates/switchers.js | 25 ++++++++++++++-----------
1 file changed, 14 insertions(+), 11 deletions(-)
diff --git a/templates/switchers.js b/templates/switchers.js
index c6dd30e..2e4fd76 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -19,10 +19,10 @@ const _CURRENT_PREFIX = (() => {
return window.location.pathname.split('/', _NUM_PREFIX_PARTS).join('/') + '/';
})();
-const all_versions = $VERSIONS;
-const all_languages = $LANGUAGES;
+const _ALL_VERSIONS = new Map(Object.entries($VERSIONS));
+const _ALL_LANGUAGES = new Map(Object.entries($LANGUAGES));
-const _create_version_select = () => {
+const _create_version_select = (versions) => {
const select = document.createElement('select');
select.className = 'version-select';
if (_IS_LOCAL) {
@@ -30,7 +30,7 @@ const _create_version_select = () => {
select.title = 'Version switching is disabled in local builds';
}
- for (const [version, title] of Object.entries(all_versions)) {
+ for (const [version, title] of versions) {
const option = document.createElement('option');
option.value = version;
if (version === _CURRENT_VERSION) {
@@ -45,10 +45,10 @@ const _create_version_select = () => {
return select;
};
-const _create_language_select = () => {
- if (!(_CURRENT_LANGUAGE in all_languages)) {
- // In case we are browsing a language that is not yet in all_languages.
- all_languages[_CURRENT_LANGUAGE] = _CURRENT_LANGUAGE;
+const _create_language_select = (languages) => {
+ if (!languages.has(_CURRENT_LANGUAGE)) {
+ // In case we are browsing a language that is not yet in languages.
+ languages.set(_CURRENT_LANGUAGE, _CURRENT_LANGUAGE);
}
const select = document.createElement('select');
@@ -58,7 +58,7 @@ const _create_language_select = () => {
select.title = 'Language switching is disabled in local builds';
}
- for (const [language, title] of Object.entries(all_languages)) {
+ for (const [language, title] of languages) {
const option = document.createElement('option');
option.value = language;
option.text = title;
@@ -136,7 +136,10 @@ const _on_language_switch = (event) => {
};
const _initialise_switchers = () => {
- const version_select = _create_version_select();
+ const versions = _ALL_VERSIONS;
+ const languages = _ALL_LANGUAGES;
+
+ const version_select = _create_version_select(versions);
document
.querySelectorAll('.version_switcher_placeholder')
.forEach((placeholder) => {
@@ -146,7 +149,7 @@ const _initialise_switchers = () => {
placeholder.classList.remove('version_switcher_placeholder');
});
- const language_select = _create_language_select();
+ const language_select = _create_language_select(languages);
document
.querySelectorAll('.language_switcher_placeholder')
.forEach((placeholder) => {
From 8cb67060a4fd9e4508b006df3052d91c2d545a3a Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:51:02 +0000
Subject: [PATCH 23/23] Add JSDoc comments
---
templates/switchers.js | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/templates/switchers.js b/templates/switchers.js
index 2e4fd76..cd4cbc2 100644
--- a/templates/switchers.js
+++ b/templates/switchers.js
@@ -22,6 +22,11 @@ const _CURRENT_PREFIX = (() => {
const _ALL_VERSIONS = new Map(Object.entries($VERSIONS));
const _ALL_LANGUAGES = new Map(Object.entries($LANGUAGES));
+/**
+ * @param {Map} versions
+ * @returns {HTMLSelectElement}
+ * @private
+ */
const _create_version_select = (versions) => {
const select = document.createElement('select');
select.className = 'version-select';
@@ -45,6 +50,11 @@ const _create_version_select = (versions) => {
return select;
};
+/**
+ * @param {Map} languages
+ * @returns {HTMLSelectElement}
+ * @private
+ */
const _create_language_select = (languages) => {
if (!languages.has(_CURRENT_LANGUAGE)) {
// In case we are browsing a language that is not yet in languages.
@@ -69,6 +79,11 @@ const _create_language_select = (languages) => {
return select;
};
+/**
+ * Change the current page to the first existing URL in the list.
+ * @param {Array} urls
+ * @private
+ */
const _navigate_to_first_existing = (urls) => {
// Navigate to the first existing URL in urls.
for (const url of urls) {
@@ -90,6 +105,12 @@ const _navigate_to_first_existing = (urls) => {
return '/';
};
+/**
+ * Callback for the version switcher.
+ * @param {Event} event
+ * @returns {void}
+ * @private
+ */
const _on_version_switch = (event) => {
if (_IS_LOCAL) return;
@@ -115,6 +136,12 @@ const _on_version_switch = (event) => {
}
};
+/**
+ * Callback for the language switcher.
+ * @param {Event} event
+ * @returns {void}
+ * @private
+ */
const _on_language_switch = (event) => {
if (_IS_LOCAL) return;
@@ -135,6 +162,11 @@ const _on_language_switch = (event) => {
}
};
+/**
+ * Initialisation function for the version and language switchers.
+ * @returns {void}
+ * @private
+ */
const _initialise_switchers = () => {
const versions = _ALL_VERSIONS;
const languages = _ALL_LANGUAGES;