Index: skins/default/header.txt
==================================================================
--- skins/default/header.txt
+++ skins/default/header.txt
@@ -17,11 +17,11 @@
html "$name\n"
} else {
html "$name\n"
}
}
-html "☰"
+html "☰"
menulink $index_page Home {}
if {[anycap jor]} {
menulink /timeline Timeline {}
}
if {[hascap oh]} {
Index: skins/default/js.txt
==================================================================
--- skins/default/js.txt
+++ skins/default/js.txt
@@ -16,27 +16,53 @@
** This file contains the JS code specific to the Fossil default skin.
** Currently, the only thing this does is handle clicks on its hamburger
** menu button.
*/
(function() {
+ var hbButton = document.getElementById("hbbtn");
+ if (!hbButton) return; // no hamburger button
+ if (!document.addEventListener) {
+ // Turn the button into a link to the sitemap for incompatible browsers.
+ hbButton.href = "$home/sitemap";
+ return;
+ }
var panel = document.getElementById("hbdrop");
if (!panel) return; // site admin might've nuked it
if (!panel.style) return; // shouldn't happen, but be sure
var panelBorder = panel.style.border;
+ var panelInitialized = false; // reset if browser window is resized
+ var panelResetBorderTimerID = 0; // used to cancel post-animation tasks
// Disable animation if this browser doesn't support CSS transitions.
//
// We need this ugly calling form for old browsers that don't allow
// panel.style.hasOwnProperty('transition'); catering to old browsers
// is the whole point here.
var animate = panel.style.transition !== null && (typeof(panel.style.transition) == "string");
- var animMS = 400;
+
+ // The duration of the animation can be overridden from the default skin
+ // header.txt by setting the "data-anim-ms" attribute of the panel.
+ var animMS = panel.getAttribute("data-anim-ms");
+ if (animMS) { // not null or empty string, parse it
+ animMS = parseInt(animMS);
+ if (isNaN(animMS) || animMS == 0)
+ animate = false; // disable animation if non-numeric or zero
+ else if (animMS < 0)
+ animMS = 400; // set default animation duration if negative
+ }
+ else // attribute is null or empty string, use default
+ animMS = 400;
// Calculate panel height despite its being hidden at call time.
// Based on https://stackoverflow.com/a/29047447/142454
- var panelHeight; // computed on sitemap load
+ var panelHeight; // computed on first panel display
function calculatePanelHeight() {
+
+ // Clear the max-height CSS property in case the panel size is recalculated
+ // after the browser window was resized.
+ panel.style.maxHeight = '';
+
// Get initial panel styles so we can restore them below.
var es = window.getComputedStyle(panel),
edis = es.display,
epos = es.position,
evis = es.visibility;
@@ -62,20 +88,55 @@
// instead, that would prevent the browser from seeing the height
// change as a state transition, so it'd skip the CSS transition:
//
// https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions#JavaScript_examples
function showPanel() {
+ // Cancel the timer to remove the panel border after the closing animation,
+ // otherwise double-clicking the hamburger button with the panel opened will
+ // remove the borders from the (closed and immediately reopened) panel.
+ if (panelResetBorderTimerID) {
+ clearTimeout(panelResetBorderTimerID);
+ panelResetBorderTimerID = 0;
+ }
if (animate) {
+ if (!panelInitialized) {
+ panelInitialized = true;
+ // Set up a CSS transition to animate the panel open and
+ // closed. Only needs to be done once per page load.
+ // Based on https://stackoverflow.com/a/29047447/142454
+ calculatePanelHeight();
+ panel.style.transition = 'max-height ' + animMS +
+ 'ms ease-in-out';
+ panel.style.overflowY = 'hidden';
+ panel.style.maxHeight = '0';
+ }
setTimeout(function() {
panel.style.maxHeight = panelHeight;
panel.style.border = panelBorder;
}, 40); // 25ms is insufficient with Firefox 62
}
- else {
- panel.style.display = 'block';
- }
+ panel.style.display = 'block';
+ document.addEventListener('keydown',panelKeydown,/* useCapture == */true);
+ document.addEventListener('click',panelClick,false);
}
+
+ var panelKeydown = function(event) {
+ var key = event.which || event.keyCode;
+ if (key == 27) {
+ event.stopPropagation(); // ignore other keydown handlers
+ panelToggle(true);
+ }
+ };
+
+ var panelClick = function(event) {
+ if (!panel.contains(event.target)) {
+ // Call event.preventDefault() to have clicks outside the opened panel
+ // just close the panel, and swallow clicks on links or form elements.
+ //event.preventDefault();
+ panelToggle(true);
+ }
+ };
// Return true if the panel is showing.
function panelShowing() {
if (animate) {
return panel.style.maxHeight == panelHeight;
@@ -82,63 +143,92 @@
}
else {
return panel.style.display == 'block';
}
}
+
+ // Check if the specified HTML element has any child elements. Note that plain
+ // text nodes, comments, and any spaces (presentational or not) are ignored.
+ function hasChildren(element) {
+ var childElement = element.firstChild;
+ while (childElement) {
+ if (childElement.nodeType == 1) // Node.ELEMENT_NODE == 1
+ return true;
+ childElement = childElement.nextSibling;
+ }
+ return false;
+ }
+
+ // Reset the state of the panel to uninitialized if the browser window is
+ // resized, so the dimensions are recalculated the next time it's opened.
+ window.addEventListener('resize',function(event) {
+ panelInitialized = false;
+ },false);
// Click handler for the hamburger button.
- var needSitemapHTML = true;
- document.querySelector("div.mainmenu > a").onclick = function() {
+ hbButton.addEventListener('click',function(event) {
+ // Break the event handler chain, or the handler for document → click
+ // (about to be installed) may already be triggered by the current event.
+ event.stopPropagation();
+ event.preventDefault(); // prevent browser from acting on click
+ panelToggle(false);
+ },false);
+
+ function panelToggle(suppressAnimation) {
if (panelShowing()) {
+ document.removeEventListener('keydown',panelKeydown,/* useCapture == */true);
+ document.removeEventListener('click',panelClick,false);
// Transition back to hidden state.
if (animate) {
- panel.style.maxHeight = '0';
- setTimeout(function() {
- // Browsers show a 1px high border line when maxHeight == 0,
- // our "hidden" state, so hide the borders in that state, too.
+ if (suppressAnimation) {
+ var transition = panel.style.transition;
+ panel.style.transition = '';
+ panel.style.maxHeight = '0';
panel.style.border = 'none';
- }, animMS);
+ setTimeout(function() {
+ // Make sure CSS transition won't take effect now, so restore it
+ // asynchronously. Outer variable 'transition' still valid here.
+ panel.style.transition = transition;
+ }, 40); // 25ms is insufficient with Firefox 62
+ }
+ else {
+ panel.style.maxHeight = '0';
+ panelResetBorderTimerID = setTimeout(function() {
+ // Browsers show a 1px high border line when maxHeight == 0,
+ // our "hidden" state, so hide the borders in that state, too.
+ panel.style.border = 'none';
+ panelResetBorderTimerID = 0; // clear ID of completed timer
+ }, animMS);
+ }
}
else {
panel.style.display = 'none';
}
}
- else if (needSitemapHTML) {
- // Only get it once per page load: it isn't likely to
- // change on us.
- var xhr = new XMLHttpRequest();
- xhr.onload = function() {
- var doc = xhr.responseXML;
- if (doc) {
- var sm = doc.querySelector("ul#sitemap");
- if (sm && xhr.status == 200) {
- // Got sitemap. Insert it into the drop-down panel.
- needSitemapHTML = false;
- panel.innerHTML = sm.outerHTML;
-
- // Display the panel
- if (animate) {
- // Set up a CSS transition to animate the panel open and
- // closed. Only needs to be done once per page load.
- // Based on https://stackoverflow.com/a/29047447/142454
- calculatePanelHeight();
- panel.style.transition = 'max-height ' + animMS +
- 'ms ease-in-out';
- panel.style.overflowY = 'hidden';
- panel.style.maxHeight = '0';
+ else {
+ if (!hasChildren(panel)) {
+ // Only get the sitemap once per page load: it isn't likely to
+ // change on us.
+ var xhr = new XMLHttpRequest();
+ xhr.onload = function() {
+ var doc = xhr.responseXML;
+ if (doc) {
+ var sm = doc.querySelector("ul#sitemap");
+ if (sm && xhr.status == 200) {
+ // Got sitemap. Insert it into the drop-down panel.
+ panel.innerHTML = sm.outerHTML;
+ // Display the panel
showPanel();
}
- panel.style.display = 'block';
- }
- }
- // else, can't parse response as HTML or XML
- }
- xhr.open("GET", "$home/sitemap?popup"); // note the TH1 substitution!
- xhr.responseType = "document";
- xhr.send();
- }
- else {
- showPanel(); // just show what we built above
- }
- return false; // prevent browser from acting on click
+ }
+ // else, can't parse response as HTML or XML
+ }
+ xhr.open("GET", "$home/sitemap?popup"); // note the TH1 substitution!
+ xhr.responseType = "document";
+ xhr.send();
+ }
+ else {
+ showPanel(); // just show what we built above
+ }
+ }
}
})();
Index: src/default_css.txt
==================================================================
--- src/default_css.txt
+++ src/default_css.txt
@@ -197,10 +197,11 @@
div.columns > ul li:first-child {
margin-top:0px;
}
.columns li {
break-inside: avoid;
+ page-break-inside: avoid;
}
.filetree {
margin: 1em 0;
line-height: 1.5;
}
Index: www/customskin.md
==================================================================
--- www/customskin.md
+++ www/customskin.md
@@ -1,16 +1,16 @@
Theming
=======
Every HTML page generated by Fossil has the following basic structure:
-
| Header |
|
Fossil-Generated Content |
| Footer |
+| Javascript (optional) |
The header and footer control the "look" of Fossil pages. Those
two sections can be customized separately for each repository to
develop a new theme.
@@ -134,10 +134,69 @@
The same TH1 interpreter is used for both the header and the footer
and for all scripts contained within them both. Hence, any global
TH1 variables that are set by the header are available to the footer.
+Customizing the ≡ Hamburger Menu
+--------------------------------
+
+The menu bar of the default skin has an entry to open a drop-down menu with
+additional navigation links, represented by the ≡ button (hence the name
+"hamburger menu"). The Javascript logic to open and close the hamburger menu
+when the button is clicked is contained in the optional Javascript part (js.txt)
+of the default skin. Out of the box, the drop-down menu shows the [Site
+Map](../../../sitemap), loaded by an AJAX request prior to the first display.
+
+The ≡ button for the hamburger menu is added to the menu bar by the following
+TH1 command in the default skin header.txt, right before the menu bar links:
+
+ html "☰"
+
+The hamburger button can be repositioned between the other menu links (but the
+drop-down menu is always left-aligned with the menu bar), or it can be removed
+by deleting the above statement (the Javascript logic detects this case and
+remains idle, so it's not necessary to modify the default skin js.txt).
+
+The following empty element at the bottom of the default skin header.txt serves
+as the panel to hold the drop-down menu elements:
+
+
+
+Out of the box, the contents of the panel is populated with the [Site
+Map](../../../sitemap), but only if the panel does not already contain any HTML
+elements (that is, not just comments, plain text or non-presentational white
+space). So the hamburger menu can be customized by replacing the empty `` element with a menu structure knitted according to the
+following template:
+
+
+
+The custom `data-anim-ms` attribute can be added to the panel element to direct
+the Javascript logic to override the default menu animation duration of 400 ms.
+A faster animation duration of 80-200 ms may be preferred for smaller menus. The
+animation is disabled by setting the attribute to `"0"`.
+
TH1 Variables
-------------
Before expanding the TH1 within the header and footer, Fossil first
initializes a number of TH1 variables to values that depend on