| 1 |
/* |
| 2 |
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. |
| 3 |
|
| 4 |
Licensed under the Apache License, Version 2.0 (the "License"). |
| 5 |
You may not use this file except in compliance with the License. |
| 6 |
You may obtain a copy of the License at |
| 7 |
|
| 8 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
|
| 10 |
Unless required by applicable law or agreed to in writing, software |
| 11 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
See the License for the specific language governing permissions and |
| 14 |
limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
const nonResourceSubHeadings = [ |
| 18 |
"client", |
| 19 |
"waiters", |
| 20 |
"paginators", |
| 21 |
"resources", |
| 22 |
"examples", |
| 23 |
]; |
| 24 |
// Checks if an html doc name matches a service class name. |
| 25 |
function isValidServiceName(serviceClassName) { |
| 26 |
const pageTitle = document.getElementsByTagName("h1")[0]; |
| 27 |
const newDocName = pageTitle.innerText.replace("#", ""); |
| 28 |
return newDocName.toLowerCase() === serviceClassName; |
| 29 |
} |
| 30 |
// Checks if all elements of the split fragment are valid. |
| 31 |
// Fragment items should only contain alphanumerics, hyphens, & underscores. |
| 32 |
// A fragment should also only be redirected if it contain 3-5 items. |
| 33 |
function isValidFragment(splitFragment) { |
| 34 |
const regex = /^[a-z0-9-_]+$/i; |
| 35 |
for (index in splitFragment) { |
| 36 |
if (!regex.test(splitFragment[index])) { |
| 37 |
return false; |
| 38 |
} |
| 39 |
} |
| 40 |
return splitFragment.length >= 1 && splitFragment.length < 5; |
| 41 |
} |
| 42 |
// Checks if a name is a possible resource name. |
| 43 |
function isValidResource(name, serviceDocName) { |
| 44 |
return ( |
| 45 |
name !== serviceDocName.replaceAll("-", "") && |
| 46 |
!nonResourceSubHeadings.includes(name) |
| 47 |
); |
| 48 |
} |
| 49 |
// Reroutes previously existing links to the new path. |
| 50 |
// Old: <root_url>/reference/services/s3.html#S3.Client.delete_bucket |
| 51 |
// New: <root_url>/reference/services/s3/client/delete_bucket.html |
| 52 |
// This must be done client side since the fragment (#S3.Client.delete_bucket) is never |
| 53 |
// passed to the server. |
| 54 |
(function () { |
| 55 |
const currentPath = window.location.pathname.split("/"); |
| 56 |
const fragment = window.location.hash.substring(1); |
| 57 |
const splitFragment = fragment |
| 58 |
.split(".") |
| 59 |
.map((part) => part.replace(/serviceresource/i, "service-resource")); |
| 60 |
// Only redirect when viewing a top-level service page. |
| 61 |
if ( |
| 62 |
isValidFragment(splitFragment) && |
| 63 |
currentPath[currentPath.length - 2] === "services" |
| 64 |
) { |
| 65 |
const serviceDocName = currentPath[currentPath.length - 1].replace( |
| 66 |
".html", |
| 67 |
"", |
| 68 |
); |
| 69 |
if (splitFragment.length > 1) { |
| 70 |
splitFragment[0] = splitFragment[0].toLowerCase(); |
| 71 |
splitFragment[1] = splitFragment[1].toLowerCase(); |
| 72 |
} |
| 73 |
let newPath; |
| 74 |
if (splitFragment.length >= 3 && isValidServiceName(splitFragment[0])) { |
| 75 |
splitFragment[0] = serviceDocName; |
| 76 |
newPath = `${splitFragment.slice(0, 3).join("/")}.html#${splitFragment.length > 3 ? fragment : ""}`; |
| 77 |
} else if ( |
| 78 |
splitFragment.length == 2 && |
| 79 |
isValidResource(splitFragment[1].toLowerCase(), serviceDocName) |
| 80 |
) { |
| 81 |
newPath = `${splitFragment.join("/")}/index.html#${fragment}`; |
| 82 |
} else if ( |
| 83 |
splitFragment.length == 1 && |
| 84 |
isValidResource(splitFragment[0], serviceDocName) |
| 85 |
) { |
| 86 |
newPath = `${serviceDocName}/${splitFragment.join("/")}/index.html`; |
| 87 |
} else { |
| 88 |
return; |
| 89 |
} |
| 90 |
window.location.assign(newPath); |
| 91 |
} |
| 92 |
})(); |
| 93 |
// Given a service name, we apply the html classes which indicate a current page to the corresponsing list item. |
| 94 |
// Before: <li class="toctree-l2"><a class="reference internal" href="../../acm.html">ACM</a></li> |
| 95 |
// After: <li class="toctree-l2 current current-page"><a class="reference internal" href="../../acm.html">ACM</a></li> |
| 96 |
function makeServiceLinkCurrent(serviceName) { |
| 97 |
const servicesSection = [...document.querySelectorAll("a")].find((e) => |
| 98 |
e.innerHTML.includes("Available Services"), |
| 99 |
).parentElement; |
| 100 |
var linkElement = servicesSection.querySelectorAll( |
| 101 |
`a[href*="../${serviceName}.html"]`, |
| 102 |
); |
| 103 |
if (linkElement.length === 0) { |
| 104 |
linkElement = servicesSection.querySelectorAll(`a[href="#"]`)[0]; |
| 105 |
} else { |
| 106 |
linkElement = linkElement[0]; |
| 107 |
} |
| 108 |
let linkParent = linkElement.parentElement; |
| 109 |
linkParent.classList.add("current"); |
| 110 |
linkParent.classList.add("current-page"); |
| 111 |
} |
| 112 |
const currentPagePath = window.location.pathname.split("/"); |
| 113 |
const codeBlockSelector = "div.highlight pre"; |
| 114 |
// Expands the "Available Services" sub-menu in the side-bar when viewing |
| 115 |
// nested doc pages and highlights the corresponding service list item. |
| 116 |
function expandSubMenu() { |
| 117 |
if (currentPagePath.includes("services")) { |
| 118 |
document.getElementById("toctree-checkbox-11").checked = true; |
| 119 |
// Example Nested Path: /reference/services/<service_name>/client/<operation_name>.html |
| 120 |
const serviceNameIndex = currentPagePath.indexOf("services") + 1; |
| 121 |
const serviceName = currentPagePath[serviceNameIndex]; |
| 122 |
makeServiceLinkCurrent(serviceName); |
| 123 |
} |
| 124 |
} |
| 125 |
// Allows code blocks to be scrollable by keyboard only users. |
| 126 |
function makeCodeBlocksScrollable() { |
| 127 |
const codeCells = document.querySelectorAll(codeBlockSelector); |
| 128 |
codeCells.forEach((codeCell) => { |
| 129 |
codeCell.tabIndex = 0; |
| 130 |
}); |
| 131 |
} |
| 132 |
// Determines which of the two table-of-contents menu labels is visible. |
| 133 |
function determineVisibleTocOpenMenu() { |
| 134 |
const mediaQuery = window.matchMedia("(max-width: 67em)"); |
| 135 |
return mediaQuery.matches ? "toc-menu-open-sm" : "toc-menu-open-md"; |
| 136 |
} |
| 137 |
|
| 138 |
// A mapping of current to next focus id's. For example, We want a corresponsing |
| 139 |
// menu's close button to be highlighted after a menu is opened with a keyboard. |
| 140 |
const NEXT_FOCUS_ID_MAP = { |
| 141 |
"nav-menu-open": "nav-menu-close", |
| 142 |
"nav-menu-close": "nav-menu-open", |
| 143 |
"toc-menu-open-sm": "toc-menu-close", |
| 144 |
"toc-menu-open-md": "toc-menu-close", |
| 145 |
"toc-menu-close": determineVisibleTocOpenMenu(), |
| 146 |
}; |
| 147 |
|
| 148 |
// Toggles the visibility of a sidebar menu to prevent keyboard focus on hidden elements. |
| 149 |
function toggleSidebarMenuVisibility(elementQuery, inputQuery) { |
| 150 |
const sidebarElement = document.querySelector(elementQuery); |
| 151 |
const sidebarInput = document.querySelector(inputQuery); |
| 152 |
sidebarInput.addEventListener("change", () => { |
| 153 |
setTimeout( |
| 154 |
() => { |
| 155 |
sidebarElement.classList.toggle("hide-sidebar", !sidebarInput.checked); |
| 156 |
}, |
| 157 |
sidebarInput.checked ? 0 : 250, |
| 158 |
); |
| 159 |
}); |
| 160 |
window.matchMedia("(max-width: 67em)").addEventListener("change", (event) => { |
| 161 |
NEXT_FOCUS_ID_MAP["toc-menu-close"] = determineVisibleTocOpenMenu(); |
| 162 |
if (!event.matches) { |
| 163 |
document |
| 164 |
.querySelector(".sidebar-drawer") |
| 165 |
.classList.remove("hide-sidebar"); |
| 166 |
} |
| 167 |
}); |
| 168 |
window.matchMedia("(max-width: 82em)").addEventListener("change", (event) => { |
| 169 |
if (!event.matches) { |
| 170 |
document.querySelector(".toc-drawer").classList.remove("hide-sidebar"); |
| 171 |
} |
| 172 |
}); |
| 173 |
} |
| 174 |
|
| 175 |
// Activates labels when a user focuses on them and clicks "Enter". |
| 176 |
// Also highlights the next appropriate input label. |
| 177 |
function activateLabelOnEnter() { |
| 178 |
const labels = document.querySelectorAll("label"); |
| 179 |
labels.forEach((element) => { |
| 180 |
element.setAttribute("tabindex", "0"); |
| 181 |
element.addEventListener("keypress", (event) => { |
| 182 |
if (event.key === "Enter") { |
| 183 |
const targetId = element.getAttribute("for"); |
| 184 |
document.getElementById(targetId).click(); |
| 185 |
const nextFocusId = NEXT_FOCUS_ID_MAP[element.id]; |
| 186 |
if (nextFocusId) { |
| 187 |
// Timeout is needed to let the label become visible. |
| 188 |
setTimeout(() => { |
| 189 |
document.getElementById(nextFocusId).focus(); |
| 190 |
}, 250); |
| 191 |
} |
| 192 |
} |
| 193 |
}); |
| 194 |
}); |
| 195 |
} |
| 196 |
|
| 197 |
function loadThemeFromLocalStorage() { |
| 198 |
document.body.dataset.theme = localStorage.getItem("theme") || "auto"; |
| 199 |
} |
| 200 |
|
| 201 |
// Improves accessibility for keyboard-only users. |
| 202 |
function setupKeyboardFriendlyNavigation() { |
| 203 |
activateLabelOnEnter(); |
| 204 |
toggleSidebarMenuVisibility(".toc-drawer", "#__toc"); |
| 205 |
toggleSidebarMenuVisibility(".sidebar-drawer", "#__navigation"); |
| 206 |
} |
| 207 |
|
| 208 |
function loadShortbread() { |
| 209 |
if (typeof AWSCShortbread !== "undefined") { |
| 210 |
const shortbread = AWSCShortbread({ |
| 211 |
// If you're testing in your dev environment, use ".cloudfront.net" for domain, else "boto3.amazonaws.com" |
| 212 |
domain: "boto3.amazonaws.com", |
| 213 |
}); |
| 214 |
|
| 215 |
// Check for cookie consent |
| 216 |
shortbread.checkForCookieConsent(); |
| 217 |
|
| 218 |
const cookiePreferencesLink = document.getElementById("cookie-button-link"); |
| 219 |
if (cookiePreferencesLink) { |
| 220 |
cookiePreferencesLink.addEventListener("click", function (event) { |
| 221 |
event.preventDefault(); |
| 222 |
shortbread.customizeCookies(); |
| 223 |
}); |
| 224 |
} |
| 225 |
|
| 226 |
console.log("AWSCShortbread successfully loaded...!!!"); |
| 227 |
} else { |
| 228 |
console.error("AWSCShortbread failed to load!!!"); |
| 229 |
} |
| 230 |
} |
| 231 |
|
| 232 |
// Functions to run after the DOM loads. |
| 233 |
function runAfterDOMLoads() { |
| 234 |
expandSubMenu(); |
| 235 |
makeCodeBlocksScrollable(); |
| 236 |
setupKeyboardFriendlyNavigation(); |
| 237 |
loadThemeFromLocalStorage(); |
| 238 |
loadShortbread(); |
| 239 |
} |
| 240 |
// Run a function after the DOM loads. |
| 241 |
function ready(fn) { |
| 242 |
if (document.readyState !== "loading") { |
| 243 |
fn(); |
| 244 |
} else { |
| 245 |
document.addEventListener("DOMContentLoaded", fn); |
| 246 |
} |
| 247 |
} |
| 248 |
ready(runAfterDOMLoads); |