theme/mkdocs_windmill/js/base.js

   1 /* global window, document, $, hljs, elasticlunr, base_url, is_top_frame */
   2 /* exported getParam, onIframeLoad */
   3 "use strict";
   4
   5 // The full page consists of a main window with navigation and table of contents, and an inner
   6 // iframe containing the current article. Which article is shown is determined by the main
   7 // window's #hash portion of the URL. In fact, we use the simple rule: main window's URL of
   8 // "rootUrl#relPath" corresponds to iframe's URL of "rootUrl/relPath".
   9 //
  10 // The main frame and the contents of the index page actually live in a single generated html
  11 // file: the outer frame hides one half, and the inner hides the other. TODO: this should be
  12 // possible to greatly simplify after mkdocs-1.0 release.
  13
  14 var mainWindow = is_top_frame ? window : (window.parent !== window ? window.parent : null);
  15 var iframeWindow = null;
  16 var rootUrl = qualifyUrl(base_url);
  17 var searchIndex = null;
  18 var showPageToc = true;
  19 var MutationObserver = window.MutationObserver || window.WebKitMutationObserver;
  20
  21 var Keys = {
  22   ENTER:  13,
  23   ESCAPE: 27,
  24   UP:     38,
  25   DOWN:   40,
  26 };
  27
  28 function startsWith(str, prefix) { return str.lastIndexOf(prefix, 0) === 0; }
  29 function endsWith(str, suffix) { return str.indexOf(suffix, str.length - suffix.length) !== -1; }
  30
  31 /**
  32  * Returns whether to use small-screen mode. Note that the same size is used in css @media block.
  33  */
  34 function isSmallScreen() {
  35   return window.matchMedia("(max-width: 600px)").matches;
  36 }
  37
  38 /**
  39  * Given a relative URL, returns the absolute one, relying on the browser to convert it.
  40  */
  41 function qualifyUrl(url) {
  42   var a = document.createElement('a');
  43   a.href = url;
  44   return a.href;
  45 }
  46
  47 /**
  48  * Turns an absolute path to relative, stripping out rootUrl + separator.
  49  */
  50 function getRelPath(separator, absUrl) {
  51   var prefix = rootUrl + (endsWith(rootUrl, separator) ? '' : separator);
  52   return startsWith(absUrl, prefix) ? absUrl.slice(prefix.length) : null;
  53 }
  54
  55 /**
  56  * Turns a relative path to absolute, adding a prefix of rootUrl + separator.
  57  */
  58 function getAbsUrl(separator, relPath) {
  59   var sep = endsWith(rootUrl, separator) ? '' : separator;
  60   return relPath === null ? null : rootUrl + sep + relPath;
  61 }
  62
  63 /**
  64  * Redirects the iframe to reflect the path represented by the main window's current URL.
  65  * (In our design, nothing should change iframe's src except via updateIframe(), or back/forward
  66  * history is likely to get messed up.)
  67  */
  68 function updateIframe(enableForwardNav) {
  69   // Grey out the "forward" button if we don't expect 'forward' to work.
  70   $('#hist-fwd').toggleClass('greybtn', !enableForwardNav);
  71
  72   var targetRelPath = getRelPath('#', mainWindow.location.href) || '';
  73   var targetIframeUrl = getAbsUrl('/', targetRelPath);
  74   var loc = iframeWindow.location;
  75   var currentIframeUrl = _safeGetLocationHref(loc);
  76
  77   console.log("updateIframe: %s -> %s (%s)", currentIframeUrl, targetIframeUrl,
  78     currentIframeUrl === targetIframeUrl ? "same" : "replacing");
  79
  80   if (currentIframeUrl !== targetIframeUrl) {
  81     loc.replace(targetIframeUrl);
  82     onIframeBeforeLoad(targetIframeUrl);
  83   }
  84   document.body.scrollTop = 0;
  85 }
  86
  87 /**
  88  * Returns location.href, catching exception that's triggered if the iframe is on a different domain.
  89  */
  90 function _safeGetLocationHref(location) {
  91   try {
  92     return location.href;
  93   } catch (e) {
  94     return null;
  95   }
  96 }
  97
  98 /**
  99  * Returns the value of the given parameter in the URL's query portion.
 100  */
 101 function getParam(key) {
 102   var params = window.location.search.substring(1).split('&');
 103   for (var i = 0; i < params.length; i++) {
 104     var param = params[i].split('=');
 105     if (param[0] === key) {
 106       return decodeURIComponent(param[1].replace(/\+/g, '%20'));
 107     }
 108   }
 109 }
 110
 111 /**
 112  * Update the state of the button toggling table-of-contents. TOC has different behavior
 113  * depending on screen size, so the button's behavior depends on that too.
 114  */
 115 function updateTocButtonState() {
 116   var shown;
 117   if (isSmallScreen()) {
 118     shown = $('.wm-toc-pane').hasClass('wm-toc-dropdown');
 119   } else {
 120     shown = !$('#main-content').hasClass('wm-toc-hidden');
 121   }
 122   $('#wm-toc-button').toggleClass('active', shown);
 123 }
 124
 125 /**
 126  * Update the height of the iframe container. On small screens, we adjust it to fit the iframe
 127  * contents, so that the page scrolls as a whole rather than inside the iframe.
 128  */
 129 function updateContentHeight() {
 130   if (isSmallScreen()) {
 131     $('.wm-content-pane').height(iframeWindow.document.body.offsetHeight + 20);
 132     $('.wm-article').attr('scrolling', 'no');
 133   } else {
 134     $('.wm-content-pane').height('');
 135     $('.wm-article').attr('scrolling', 'auto');
 136   }
 137 }
 138
 139 /**
 140  * When TOC is a dropdown (on small screens), close it.
 141  */
 142 function closeTempItems() {
 143   $('.wm-toc-dropdown').removeClass('wm-toc-dropdown');
 144   $('#mkdocs-search-query').closest('.wm-top-tool').removeClass('wm-top-tool-expanded');
 145   updateTocButtonState();
 146 }
 147
 148 /**
 149  * Visit the given URL. This changes the hash of the top page to reflect the new URL's relative
 150  * path, and points the iframe to the new URL.
 151  */
 152 function visitUrl(url, event) {
 153   var relPath = getRelPath('/', url);
 154   if (relPath !== null) {
 155     event.preventDefault();
 156     var newUrl = getAbsUrl('#', relPath);
 157     if (newUrl !== mainWindow.location.href) {
 158       mainWindow.history.pushState(null, '', newUrl);
 159       updateIframe(false);
 160     }
 161     closeTempItems();
 162     iframeWindow.focus();
 163   }
 164 }
 165
 166 /**
 167  * Adjusts link to point to a top page, converting URL from "base/path" to "base#path". It also
 168  * sets a data-adjusted attribute on the link, to skip adjustments on future clicks.
 169  */
 170 function adjustLink(linkEl) {
 171   if (!linkEl.hasAttribute('data-wm-adjusted')) {
 172     linkEl.setAttribute('data-wm-adjusted', 'done');
 173     var relPath = getRelPath('/', linkEl.href);
 174     if (relPath !== null) {
 175       var newUrl = getAbsUrl('#', relPath);
 176       linkEl.href = newUrl;
 177     }
 178   }
 179 }
 180
 181 /**
 182  * Given a URL, strips query and fragment, returning just the path.
 183  */
 184 function cleanUrlPath(relUrl) {
 185   return relUrl.replace(/[#?].*/, '');
 186 }
 187
 188 /**
 189  * Initialize the main window.
 190  */
 191 function initMainWindow() {
 192   // wm-toc-button either opens the table of contents in the side-pane, or (on smaller screens)
 193   // shows the side-pane as a drop-down.
 194   $('#wm-toc-button').on('click', function(e) {
 195     if (isSmallScreen()) {
 196       $('.wm-toc-pane').toggleClass('wm-toc-dropdown');
 197       $('#wm-main-content').removeClass('wm-toc-hidden');
 198     } else {
 199       $('#main-content').toggleClass('wm-toc-hidden');
 200       closeTempItems();
 201     }
 202     updateTocButtonState();
 203   });
 204
 205   // Update the state of the wm-toc-button
 206   updateTocButtonState();
 207   $(window).on('resize', function() {
 208     updateTocButtonState();
 209     updateContentHeight();
 210   });
 211
 212   // Connect up the Back and Forward buttons (if present).
 213   $('#hist-back').on('click', function(e) { window.history.back(); });
 214   $('#hist-fwd').on('click', function(e) { window.history.forward(); });
 215
 216   // When the side-pane is a dropdown, hide it on click-away.
 217   $(window).on('blur', closeTempItems);
 218
 219   // When we click on an opener in the table of contents, open it.
 220   $('.wm-toc-pane').on('click', '.wm-toc-opener', function(e) {
 221     $(this).toggleClass('wm-toc-open');
 222     $(this).next('.wm-toc-li-nested').collapse('toggle');
 223   });
 224   $('.wm-toc-pane').on('click', '.wm-page-toc-opener', function(e) {
 225     // Ignore clicks while transitioning.
 226     if ($(this).next('.wm-page-toc').hasClass('collapsing')) { return; }
 227     showPageToc = !showPageToc;
 228     $(this).toggleClass('wm-page-toc-open', showPageToc);
 229     $(this).next('.wm-page-toc').collapse(showPageToc ? 'show' : 'hide');
 230   });
 231
 232   // Once the article loads in the side-pane, close the dropdown.
 233   $('.wm-article').on('load', function() {
 234     document.title = iframeWindow.document.title;
 235     updateContentHeight();
 236
 237     // We want to update content height whenever the height of the iframe's content changes.
 238     // Using MutationObserver seems to be the best way to do that.
 239     var observer = new MutationObserver(updateContentHeight);
 240     observer.observe(iframeWindow.document.body, {
 241       attributes: true,
 242       childList: true,
 243       characterData: true,
 244       subtree: true
 245     });
 246
 247     iframeWindow.focus();
 248   });
 249
 250   // Initialize search functionality.
 251   initSearch();
 252
 253   // Load the iframe now, and whenever we navigate the top frame.
 254   setTimeout(function() { updateIframe(false); }, 0);
 255   // For our usage, 'popstate' or 'hashchange' would work, but only 'hashchange' work on IE.
 256   $(window).on('hashchange', function() { updateIframe(true); });
 257 }
 258
 259 function onIframeBeforeLoad(url) {
 260   $('.wm-current').removeClass('wm-current');
 261   closeTempItems();
 262
 263   var tocLi = getTocLi(url);
 264   tocLi.addClass('wm-current');
 265   tocLi.parents('.wm-toc-li-nested')
 266     // It's better to open parent items immediately without a transition.
 267     .removeClass('collapsing').addClass('collapse in').height('')
 268     .prev('.wm-toc-opener').addClass('wm-toc-open');
 269 }
 270
 271 function getTocLi(url) {
 272   var relPath = getAbsUrl('#', getRelPath('/', cleanUrlPath(url)));
 273   var selector = '.wm-article-link[href="' + relPath + '"]';
 274   return $(selector).closest('.wm-toc-li');
 275 }
 276
 277 var _deferIframeLoad = false;
 278
 279 // Sometimes iframe is loaded before main window's ready callback. In this case, we defer
 280 // onIframeLoad call until the main window has initialized.
 281 function ensureIframeLoaded() {
 282   if (_deferIframeLoad) {
 283     onIframeLoad();
 284   }
 285 }
 286
 287 function onIframeLoad() {
 288   if (!iframeWindow) { _deferIframeLoad = true; return; }
 289   var url = iframeWindow.location.href;
 290   onIframeBeforeLoad(url);
 291
 292   if (iframeWindow.pageToc) {
 293     var relPath = getAbsUrl('#', getRelPath('/', cleanUrlPath(url)));
 294     renderPageToc(getTocLi(url), relPath, iframeWindow.pageToc);
 295   }
 296   iframeWindow.focus();
 297 }
 298
 299 /**
 300  * Hides a bootstrap collapsible element, and removes it from DOM once hidden.
 301  */
 302 function collapseAndRemove(collapsibleElem) {
 303   if (!collapsibleElem.hasClass('in')) {
 304     // If the element is already hidden, just remove it immediately.
 305     collapsibleElem.remove();
 306   } else {
 307     collapsibleElem.on('hidden.bs.collapse', function() {
 308       collapsibleElem.remove();
 309     })
 310     .collapse('hide');
 311   }
 312 }
 313
 314 function renderPageToc(parentElem, pageUrl, pageToc) {
 315   var ul = $('<ul class="wm-toctree">');
 316   function addItem(tocItem) {
 317     ul.append($('<li class="wm-toc-li">')
 318       .append($('<a class="wm-article-link wm-page-toc-text">')
 319         .attr('href', pageUrl + tocItem.url)
 320         .attr('data-wm-adjusted', 'done')
 321         .text(tocItem.title)));
 322     if (tocItem.children) {
 323       tocItem.children.forEach(addItem);
 324     }
 325   }
 326   pageToc.forEach(addItem);
 327
 328   $('.wm-page-toc-opener').removeClass('wm-page-toc-opener wm-page-toc-open');
 329   collapseAndRemove($('.wm-page-toc'));
 330
 331   parentElem.addClass('wm-page-toc-opener').toggleClass('wm-page-toc-open', showPageToc);
 332   $('<li class="wm-page-toc wm-toc-li-nested collapse">').append(ul).insertAfter(parentElem)
 333     .collapse(showPageToc ? 'show' : 'hide');
 334 }
 335
 336
 337 if (!mainWindow) {
 338   // This is a page that ought to be in an iframe. Redirect to load the top page instead.
 339   var topUrl = getAbsUrl('#', getRelPath('/', window.location.href));
 340   if (topUrl) {
 341     window.location.href = topUrl;
 342   }
 343
 344 } else {
 345   // Adjust all links to point to the top page with the right hash fragment.
 346   $(document).ready(function() {
 347     $('a').each(function() { adjustLink(this); });
 348   });
 349
 350   // For any dynamically-created links, adjust them on click.
 351   $(document).on('click', 'a:not([data-wm-adjusted])', function(e) { adjustLink(this); });
 352 }
 353
 354 if (is_top_frame) {
 355   // Main window.
 356   $(document).ready(function() {
 357     iframeWindow = $('.wm-article')[0].contentWindow;
 358     initMainWindow();
 359     ensureIframeLoaded();
 360   });
 361
 362 } else {
 363   // Article contents.
 364   iframeWindow = window;
 365   if (mainWindow) {
 366     mainWindow.onIframeLoad();
 367   }
 368
 369   // Other initialization of iframe contents.
 370   hljs.initHighlightingOnLoad();
 371   $(document).ready(function() {
 372     $('table').addClass('table table-striped table-hover table-bordered table-condensed');
 373   });
 374 }
 375
 376
 377 var searchIndexReady = false;
 378
 379 /**
 380  * Initialize search functionality.
 381  */
 382 function initSearch() {
 383   // Create elasticlunr index.
 384   searchIndex = elasticlunr(function() {
 385     this.setRef('location');
 386     this.addField('title');
 387     this.addField('text');
 388   });
 389
 390   var searchBox = $('#mkdocs-search-query');
 391   var searchResults = $('#mkdocs-search-results');
 392
 393   // Fetch the prebuilt index data, and add to the index.
 394   $.getJSON(base_url + '/search/search_index.json')
 395   .done(function(data) {
 396     data.docs.forEach(function(doc) {
 397       searchIndex.addDoc(doc);
 398     });
 399     searchIndexReady = true;
 400     $(document).trigger('searchIndexReady');
 401   });
 402
 403   function showSearchResults(optShow) {
 404     var show = (optShow === false ? false : Boolean(searchBox.val()));
 405     if (show) {
 406       doSearch({
 407         resultsElem: searchResults,
 408         query: searchBox.val(),
 409         snippetLen: 100,
 410         limit: 10
 411       });
 412     }
 413     searchResults.parent().toggleClass('open', show);
 414     return show;
 415   }
 416
 417   searchBox.on('click', function(e) {
 418     if (!searchResults.parent().hasClass('open')) {
 419       if (showSearchResults()) {
 420         e.stopPropagation();
 421       }
 422     }
 423   });
 424
 425   // Search automatically and show results on keyup event.
 426   searchBox.on('keyup', function(e) {
 427     var show = (e.which !== Keys.ESCAPE && e.which !== Keys.ENTER);
 428     showSearchResults(show);
 429   });
 430
 431   // Open the search box (and run the search) on up/down arrow keys.
 432   searchBox.on('keydown', function(e) {
 433     if (e.which === Keys.UP || e.which === Keys.DOWN) {
 434       if (showSearchResults()) {
 435         e.stopPropagation();
 436         e.preventDefault();
 437         setTimeout(function() {
 438           searchResults.find('a').eq(e.which === Keys.UP ? -1 : 0).focus();
 439         }, 0);
 440       }
 441     }
 442   });
 443
 444   searchResults.on('keydown', function(e) {
 445     if (e.which === Keys.UP || e.which === Keys.DOWN) {
 446       if (searchResults.find('a').eq(e.which === Keys.UP ? 0 : -1)[0] === e.target) {
 447         searchBox.focus();
 448         e.stopPropagation();
 449         e.preventDefault();
 450       }
 451     }
 452   });
 453
 454   $(searchResults).on('click', '.search-all', function(e) {
 455     e.stopPropagation();
 456     e.preventDefault();
 457     $('#wm-search-form').trigger('submit');
 458   });
 459
 460   // Redirect to the search page on Enter or button-click (form submit).
 461   $('#wm-search-form').on('submit', function(e) {
 462     var url = this.action + '?' + $(this).serialize();
 463     visitUrl(url, e);
 464     searchResults.parent().removeClass('open');
 465   });
 466
 467   $('#wm-search-show,#wm-search-go').on('click', function(e) {
 468     if (isSmallScreen()) {
 469       e.preventDefault();
 470       var el = $('#mkdocs-search-query').closest('.wm-top-tool');
 471       el.toggleClass('wm-top-tool-expanded');
 472       if (el.hasClass('wm-top-tool-expanded')) {
 473         setTimeout(function() {
 474           $('#mkdocs-search-query').focus();
 475           showSearchResults();
 476         }, 0);
 477         $('#mkdocs-search-query').focus();
 478       }
 479     }
 480   });
 481 }
 482
 483 function escapeRegex(s) {
 484   return s.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
 485 }
 486
 487 /**
 488  * This helps construct useful snippets to show in search results, and highlight matches.
 489  */
 490 function SnippetBuilder(query) {
 491   var termsPattern = elasticlunr.tokenizer(query).map(escapeRegex).join("|");
 492   this._termsRegex = termsPattern ? new RegExp(termsPattern, "gi") : null;
 493 }
 494
 495 SnippetBuilder.prototype.getSnippet = function(text, len) {
 496   if (!this._termsRegex) {
 497     return text.slice(0, len);
 498   }
 499
 500   // Find a position that includes something we searched for.
 501   var pos = text.search(this._termsRegex);
 502   if (pos < 0) { pos = 0; }
 503
 504   // Find a period before that position (a good starting point).
 505   var start = text.lastIndexOf('.', pos) + 1;
 506   if (pos - start > 30) {
 507     // If too long to previous period, give it 30 characters, and find a space before that.
 508     start = text.lastIndexOf(' ', pos - 30) + 1;
 509   }
 510   var rawSnippet = text.slice(start, start + len);
 511   return rawSnippet.replace(this._termsRegex, '<b>$&</b>');
 512 };
 513
 514 /**
 515  * Search the elasticlunr index for the given query, and populate the dropdown with results.
 516  */
 517 function doSearch(options) {
 518   var resultsElem = options.resultsElem;
 519   resultsElem.empty();
 520
 521   // If the index isn't ready, wait for it, and search again when ready.
 522   if (!searchIndexReady) {
 523     resultsElem.append($('<li class="disabled"><a class="search-link">SEARCHING...</a></li>'));
 524     $(document).one('searchIndexReady', function() { doSearch(options); });
 525     return;
 526   }
 527
 528   var query = options.query;
 529   var snippetLen = options.snippetLen;
 530   var limit = options.limit;
 531
 532   if (query === '') { return; }
 533
 534   var results = searchIndex.search(query, {
 535     fields: { title: {boost: 10}, text: { boost: 1 } },
 536     expand: true,
 537     bool: "AND"
 538   });
 539
 540   var snippetBuilder = new SnippetBuilder(query);
 541   if (results.length > 0){
 542     var len = Math.min(results.length, limit || Infinity);
 543     for (var i = 0; i < len; i++) {
 544       var doc = searchIndex.documentStore.getDoc(results[i].ref);
 545       var snippet = snippetBuilder.getSnippet(doc.text, snippetLen);
 546       resultsElem.append(
 547         $('<li>').append($('<a class="search-link">').attr('href', pathJoin(base_url, doc.location))
 548           .append($('<div class="search-title">').text(doc.title))
 549           .append($('<div class="search-text">').html(snippet)))
 550       );
 551     }
 552     resultsElem.find('a').each(function() { adjustLink(this); });
 553     if (limit) {
 554       resultsElem.append($('<li role="separator" class="divider"></li>'));
 555       resultsElem.append($(
 556         '<li><a class="search-link search-all" href="' + base_url + '/search.html">' +
 557         '<div class="search-title">SEE ALL RESULTS</div></a></li>'));
 558     }
 559   } else {
 560     resultsElem.append($('<li class="disabled"><a class="search-link">NO RESULTS FOUND</a></li>'));
 561   }
 562 }
 563
 564 function pathJoin(prefix, suffix) {
 565   var nPrefix = endsWith(prefix, "/") ? prefix.slice(0, -1) : prefix;
 566   var nSuffix = startsWith(suffix, "/") ? suffix.slice(1) : suffix;
 567   return nPrefix + "/" + nSuffix;
 568 }