elastic.co/guide/* redesign (#2478)

* get basic sticky nav and highlighting working * remove unused code * sticky toc, updated toc style, refine otp highlighting * adjust otp styles * add book_title styles * remove book title div * Update resources/web/template.html * use chevron icons instead of plus icons fix current_page_parent * style index page * unstick on narrow screens check on various screen sizes * remove chevron icon from book_title * use overflow auto * remove redundant font-size that was resolving to 85% of 85% * remove dupe CSS; scroll to active TOC element * revert bootstrap.css change * remove console.log * revert link color bug; swap to `container-fluid` * fix `scrollIntoView()` bug on widths <769px * Update resources/web/style/on_this_page.pcss * fix padding bug * limit width of text in collapsible toc groups * remove z-index from sticky classes * address feedback from @chandlerprall * use scrollTop instead of scrollIntoView * clean up code comments * fix `Uncaught TypeError` and variable spelling Co-authored-by: Colleen McGinnis <[email protected]>
elastic · Aug 17, 2022 · 4e1737d · 4e1737d
1 parent 54bd6b0
commit 4e1737d
Show file tree

Hide file tree

Showing 11 changed files with 284 additions and 60 deletions.
diff --git a/resources/web/docs_js/index.js b/resources/web/docs_js/index.js
@@ -19,10 +19,13 @@ import "../../../../../node_modules/details-polyfill";
 // Add support for URLSearchParams Web API in IE
 import "../../../../../node_modules/url-search-params-polyfill";
 
-export function init_headers(right_col, lang_strings) {
+// Vocab:
+// TOC = table of contents
+// OTP = on this page
+export function init_headers(sticky_content, lang_strings) {
   // Add on-this-page block
-  var this_page = $('<div id="this_page"></div>').prependTo(right_col);
-  this_page.append('<h2>' + lang_strings('On this page') + '</h2>');
+  var this_page = $('<div id="this_page"></div>').prependTo(sticky_content);
+  this_page.append('<p id="otp" class="aside-heading">' + lang_strings('On this page') + '</p>');
   var ul = $('<ul></ul>').appendTo(this_page);
   var items = 0;
   var baseHeadingLevel = 0;
@@ -57,7 +60,7 @@ export function init_headers(right_col, lang_strings) {
             .remove();
           var text = title_container.html();
           const adjustedLevel = hLevel - baseHeadingLevel;
-          const li = '<li class="heading-level-' + adjustedLevel + '"><a href="#' + this.id + '">' + text + '</a></li>';
+          const li = '<li id="otp-text-' + i + '" class="heading-level-' + adjustedLevel + '"><a href="#' + this.id + '">' + text + '</a></li>';
           ul.append(li);
         }
       }
@@ -170,6 +173,44 @@ function init_toc(lang_strings) {
     });
 }
 
+// In the OTP, highlight the heading of the section that is
+// currently visible on the page.
+// If more than one is visible, highlight the heading for the
+// section that is higher on the page.
+function highlight_otp() {
+  let visibleHeadings = []
+  const observer = new IntersectionObserver(entries => {
+    entries.forEach(entry => {
+      const id = entry.target.getAttribute('id');
+      const element = document.querySelector(`#sticky_content #this_page a[href="#${id}"]`);
+      const itemId = $(element).parent().attr('id')
+      // All heading elements have an `entry` (even the title).
+      // The title does not exist in the OTP, so we must exclude it.
+      // Checking for the existence of `itemId` ensures we don't parse elements that don't exist.
+      if (itemId){
+        const itemNumber = parseInt(itemId.match(/\d+/)[0], 10);
+        if (entry.intersectionRatio > 0){
+          visibleHeadings.push(itemNumber);
+        } else {
+          const position = visibleHeadings.indexOf(itemNumber);
+          visibleHeadings.splice(position, 1)
+        }
+        if (visibleHeadings.length > 0) {
+          visibleHeadings.sort((a, b) => a - b)
+          // Remove existing active classes
+          $('a.active').removeClass("active");
+          // Add active class to the first visible heading
+          $('#otp-text-' + visibleHeadings[0] + ' > a').addClass('active')
+        }
+      }
+    })
+  })
+
+  document.querySelectorAll('#guide a[id]').forEach((heading) => {
+    observer.observe(heading);
+  })
+}
+
 // Main function, runs on DOM ready
 $(function() {
   var lang = $('section#guide[lang]').attr('lang') || 'en';
@@ -228,7 +269,16 @@ $(function() {
 
   AlternativeSwitcher(store());
 
-  var right_col = $('#right_col'); // Move rtp container to top right and make visible
+  // Move rtp container to top right and make visible
+  var sticky_content = $('#sticky_content');
+  // Left column that contains the TOC
+  var left_col = $('#left_col');
+  // Middle column that contains the main content
+  var middle_col = $('#middle_col');
+  // Right column that contains the OTP and demand gen content
+  var right_col = $('#right_col');
+  // Empty column below TOC on small screens so the demand gen content can be positioned under the main content
+  var bottom_left_col = $('#bottom_left_col');
 
   $('.page_header > a[href="../current/index.html"]').click(function() {
     utils.get_current_page_in_version('current');
@@ -271,14 +321,24 @@ $(function() {
   if (div.length == 0 && $('#guide').find('div.article,div.book').length == 0) {
     var url = location.href.replace(/[^\/]+$/, 'toc.html');
     var toc = $.get(url, {}, function(data) {
-      right_col.append(data);
+      left_col.append(data);
       init_toc(LangStrings);
       utils.open_current(location.pathname);
     }).always(function() {
-      init_headers(right_col, LangStrings);
+      init_headers(sticky_content, LangStrings);
+      highlight_otp();
     });
   } else {
     init_toc(LangStrings);
+    // Style book landing page (no main content, just a TOC and demand gen content)
+
+    // Set the width of the left column to zero
+    left_col.removeClass().addClass('col-0');
+    bottom_left_col.removeClass().addClass('col-0');
+    // Set the width of the middle column (containing the TOC) to 9
+    middle_col.removeClass().addClass('col-12 col-lg-9 guide-section');
+    // Set the width of the demand gen content to 3
+    right_col.removeClass().addClass('col-12 col-lg-3 sticky-top-md h-almost-full-lg');
   }
 
   PR.prettyPrint();
@@ -299,6 +359,26 @@ $(function() {
     $('a.edit_me_private').show();
   }
 
+  // scroll to selected TOC element; if it doesn't exist yet, wait and try again
+  // window.width must match the breakpoint of `.sticky-top-md`
+  if($(window).width() >= 769){
+    var scrollToSelectedTOC = setInterval(() => {
+      if ($('.current_page').length) {
+          // Get scrollable element
+          var container = document.querySelector("#left_col");
+          // Get active table of contents element
+          var activeItem = document.querySelector(".current_page")
+          // If the top of the active item is out of view (or in the bottom 100px of the visible portion of the TOC)
+          // scroll so the top of the active item is at the top of the visible portion TOC
+          if (container.offsetHeight - 100 <= activeItem.offsetTop) {
+            // Scroll to active item
+            container.scrollTop = activeItem.offsetTop
+          }
+        clearInterval(scrollToSelectedTOC);
+      }
+    }, 150);
+  }
+
   // Test comment used to detect unminifed JS in tests
 });
 

diff --git a/resources/web/docs_js/utils.js b/resources/web/docs_js/utils.js
@@ -18,6 +18,7 @@ export function open_current(pathname) {
   var page = pathname.match(/[^\/]+$/)[0];
   var current = $('div.toc a[href="' + page + '"]');
   current.addClass('current_page');
+  current.parent().parent().addClass('current_page_li');
   current.parentsUntil('ul.toc', 'li.collapsible').addClass('show');
 }
 

diff --git a/resources/web/style/base_styles.pcss b/resources/web/style/base_styles.pcss
@@ -30,4 +30,60 @@
   details {
     margin-bottom: 1.15em;
   }
+
+  .container-fluid {
+    @media screen and (min-width: 1560px) {
+      max-width: 1500px;
+    }
+  }
+
+  .sticky-top-md {
+    position: -webkit-relative;
+    position: relative;
+    @media screen and (min-width: 769px) {
+      position: -webkit-sticky;
+      position: sticky;
+      top: 0;
+    }
+  }
+
+  .sticky-top-lg {
+    position: -webkit-relative;
+    position: relative;
+    @media screen and (min-width: 993px) {
+      position: -webkit-sticky;
+      position: sticky;
+      top: 0;
+    }
+  }
+
+  .h-almost-full-md {
+    @media screen and (min-width: 769px) {
+      height: 95vh;
+    }
+  }
+
+  .h-almost-full-lg {
+    @media screen and (min-width: 993px) {
+      height: 95vh;
+    }
+  }
+
+  #left_col {
+    overflow: auto;
+  }
+
+  .aside-heading {
+    font-weight: 600;
+    margin-top: 20px;
+    margin-bottom: 10px;
+  }
+
+  .media-type {
+    opacity: 0.6;
+    text-transform: uppercase;
+    font-size: 80%;
+    font-weight: 400;
+    margin-bottom: 0px;
+  }
 }
diff --git a/resources/web/style/docbook.pcss b/resources/web/style/docbook.pcss
@@ -18,3 +18,7 @@
 .guide-section {
   margin-bottom: 30px;
 }
+
+#sticky_content {
+  padding-bottom: 30px;
+}
diff --git a/resources/web/style/heading.pcss b/resources/web/style/heading.pcss
@@ -77,4 +77,11 @@
     background-image: inline("img/edit-me-private.png");
     display: none;
   }
-}
+
+  /* Titlepage headings don't need large gaps around them  */
+  .titlepage {
+    .title {
+      margin: 10px 0 16px;
+    }
+  }
+}
diff --git a/resources/web/style/link.pcss b/resources/web/style/link.pcss
@@ -1,6 +1,6 @@
 #guide {
   a {
-    color: #00a9e5;
+    color: #0077CC;
     font-weight: normal;
     text-decoration: none;
     outline: none;

diff --git a/resources/web/style/on_this_page.pcss b/resources/web/style/on_this_page.pcss
@@ -5,16 +5,16 @@
 
   .heading-level-1 {
     display: block;
-    padding-left: 1.5em !important;
+    padding-left: 1em !important;
   }
 
   .heading-level-2 {
     display: block;
-    padding-left: 3em !important;
+    padding-left: 2em !important;
   }
 
   .heading-level-3 {
     display: block;
-    padding-left: 4.5em !important;
+    padding-left: 3em !important;
   }
 }
diff --git a/resources/web/style/rtpcontainer.pcss b/resources/web/style/rtpcontainer.pcss
@@ -5,9 +5,7 @@
  * on the rtpcontainer in general. */
 #rtpcontainer {
   .mktg-promo {
-    margin: 55px 0 30px;
-    padding: 32px;
-    border: 1px solid #d4dae5;
+    padding: 12px;
   }
   h3 {
     margin: 5px 0;
@@ -47,7 +45,7 @@
     li {
       align-items: center;
       list-style: none;
-      min-height: 50px;
+      min-height: 30px;
       padding-left: 0.6em;
       display: flex;
       font-size: 14px;

diff --git a/resources/web/style/this_page.pcss b/resources/web/style/this_page.pcss
@@ -1,6 +1,12 @@
 #this_page {
-  margin-bottom: 0;
-  padding-left: 1em;
+  padding-bottom: 20px;
+  display: block;
+  border-bottom: 1px solid #dee2e6;
+  max-height:40vh;
+  overflow: auto;
+  @media screen and (max-width: 992px) {
+    display: none;
+  }
   h2 {
     font-size: 1.5em;
     line-height: 1.5em;
@@ -13,6 +19,11 @@
   }
   li {
     line-height: 1.2em;
-    margin-bottom: .5em;
+    margin-top: .3em;
+    margin-bottom: .3em;
+  }
+  .active {
+    font-weight: 700;
+    font-style: ul;
   }
 }