rewrote quickstart, build-process
[AGL/documentation.git] / 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 }