Merge pull request #2 from KevinAst/next2

publish: v1.0.1 Added Configuration
KevinAst · Sep 8, 2018 · c72497b · c72497b
2 parents d956b4a + d74b06d
commit c72497b
Show file tree

Hide file tree

Showing 4 changed files with 164 additions and 92 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -7,6 +7,17 @@ one section at a time** _(the active section)_.
 
 [![NPM Version Badge](https://img.shields.io/npm/v/gitbook-plugin-folding-menu.svg)](https://www.npmjs.com/package/gitbook-plugin-folding-menu)
 
+
+## At a Glance
+
+- [Overview]
+- [Install]
+- [Configuration]
+- [Revision History]
+  * [v1.0.1] - Added Configuration *(September 8, 2018)*
+  * [v1.0.0] - Initial Release *(September 7, 2018)*
+
+
 ## Overview
 
 The high-level points of interest are:
@@ -39,29 +50,119 @@ This project is a significant improvement on other similar plugins.
 
 ## Install
 
-- Add the `"folding-menu"` plugin to your **book.json** file:
-
-  ```js
-  {
-    "plugins": [
-      ... other plugins you may be using
-      "folding-menu"
-    ]
+1. Add the `"folding-menu"` plugin to your **book.json** file:
+
+   **book.json**   
+   ```js
+   {
+     ...
+     "plugins": [
+       ... other plugins you may be using
+       "folding-menu"
+     ]
+     ...
+   }
+   ```
+
+2. Install the plugin using **one** of the following options _(based on your gitbook usage)_:
+
+   - For https://legacy.gitbook.com/ usage, plugins are automatically installed.
+
+   - For local gitbook usage run `gitbook install` to install and prepare
+     all plugins for your books:
+
+     ```shell
+     gitbook install
+     ```
+
+   - For technical users _(ex: open source documentation)_, install the
+     plugin to your **devDependencies** as follows:
+
+     ```shell
+     npm install --save-dev gitbook-plugin-folding-menu
+     ```
+
+
+## Configuration
+
+You may optionally supply the following configuration to this plugin:
+
+<ul><!--- indentation hack for github - other attempts with style is stripped (be careful with number bullets) ---> 
+
+**book.json**   
+```js
+{
+  ...
+  "pluginsConfig": {
+    "folding-menu":	{
+      "animationDuration": 500,
+      "sticky":            true
+    }
   }
-  ```
+  ...
+}
+```
+
+</ul>
+
+- **animationDuration** - The animation duration in mills ... use 0
+  (zero) to disable animation ... **DEFAULT: 400**
+
+- **sticky** - Leave the last section expanded when a the current
+  active section has NO sub-content ... **DEFAULT: false**
+
+
+## Revision History
+
+
+Release  | What                                            | *When*
+---------|-------------------------------------------------|------------------
+[v1.0.1] | Added Configuration                             | *September 8, 2018*
+[v1.0.0] | Initial Release                                 | *September 7, 2018*
+
+
+
+<!-- *** RELEASE *************************************************************** -->
+
+### v1.0.1 - Added Configuration *(September 8, 2018)*
+
+<ul><ul><!--- indentation hack for github - other attempts with style is stripped (be careful with number bullets) ---> 
+
+[GitHub Content](https://github.com/KevinAst/gitbook-plugin-folding-menu/tree/v1.0.1)
+&bull;
+[GitHub Release](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases/tag/v1.0.1)
+&bull;
+[Diff](https://github.com/KevinAst/gitbook-plugin-folding-menu/compare/v1.0.0...v1.0.1)
+
+**NOTE**: This release is a **non-breaking change** _(i.e. no API was affected)_.
+
+- This plugin is now configurable _(see: [Configuration])_.
+
+</ul></ul>
+
+
+
+<!-- *** RELEASE *************************************************************** -->
+
+### v1.0.0 - Initial Release *(September 7, 2018)*
+
+<ul><ul><!--- indentation hack for github - other attempts with style is stripped (be careful with number bullets) ---> 
+
+[GitHub Content](https://github.com/KevinAst/gitbook-plugin-folding-menu/tree/v1.0.0)
+&bull;
+[GitHub Release](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases/tag/v1.0.0)
+
+**This is where it all began ...**
 
-- For https://legacy.gitbook.com/ usage, plugins are automatically installed.
+</ul></ul>
 
-- For local gitbook usage run `gitbook install` to install and prepare
-  all plugins for your books:
 
-  ```shell
-  gitbook install
-  ```
 
-- For technical users _(ex: open source documentation)_, install the
-  plugin to your **devDependencies** as follows:
 
-  ```shell
-  npm install --save-dev gitbook-plugin-folding-menu
-  ```
+<!--- *** REFERENCE LINKS *** ---> 
+[Overview]:          #overview
+[Install]:           #install
+[Configuration]:     #configuration
+[Revision History]:  #revision-history
+ [v1.0.1]:           #v101---added-configuration-september-8-2018
+ [v1.0.0]:           #v100---initial-release-september-7-2018
diff --git a/book/plugin.js b/book/plugin.js
@@ -5,6 +5,23 @@
 //***
 require(["gitbook", "jQuery"], function(gitbook, $) {
 
+  // our plugin configuration object
+  // ... optionally defined in client book.json
+  // ... auto defaulted by gitbook as follows:
+  //     config: {
+  //       animationDuration: 400,
+  //       sticky:            false
+  //     }
+  var config = null;
+
+  // glean plugin configuration on start event
+  gitbook.events.bind('start', function(e, myConfig) {
+    // simply retain in parent scope (for subsequent use)
+    config = myConfig['folding-menu'];
+    diag('start event ... config: ', config);
+  });
+
+
   // listen for gitbook "page.change" events
   // ... emitted whenever a file.md changes
   gitbook.events.bind("page.change", function(e) {
@@ -50,9 +67,10 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
       //     starts out with leftNav expanded!!!
       baselinePriorVisibility($topSections);
 
-      // leave the last expanded section in-tact, when a the current section has NO content
+      // when necessary, leave the last section expanded
       // ... by simply no-oping
-      if ($activeTopSection.length === 0) {
+      if (config.sticky &&                  // when configured to be sticky -AND-
+          $activeTopSection.length === 0) { // the current active section has NO sub-content
         return;
       }
 
@@ -136,28 +154,26 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
   //     - resulting in a MUCH better visual
   function setVisible(elmSection, directive) {
 
-    var animationDelay = 400; // utilize an appropriate animation delay (nice visual)
-
     var sectionKey           = getSectionKey(elmSection);
     var curSectionVisibility = getCurSectionVisibility(sectionKey);
 
     var diagMsg = 'setVisible(elmSection: ' + sectionKey + ', directive: ' + directive + ') ... curSectionVisibility: ' + curSectionVisibility + ' ... ';
 
     // apply the visibility directive, when needed (based on cached current visibility)
     if (directive === 'show') {
-      if (curSectionVisibility !== 'show') {  // when out-of-sync
-        $(elmSection).show(animationDelay);   // ... change visiblity WITH animation
-        visibilityCache[sectionKey] = 'show'; // ... maintaining our cache
+      if (curSectionVisibility !== 'show') {          // when out-of-sync
+        $(elmSection).show(config.animationDuration); // ... change visiblity WITH animation
+        visibilityCache[sectionKey] = 'show';         // ... maintaining our cache
         diagMsg += 'SHOWING';
       }
       else {
         diagMsg += 'no-oping';
       }
     }
     else {
-      if (curSectionVisibility !== 'hide') {  // when out-of-sync
-        $(elmSection).hide(animationDelay);   // ... change visiblity WITH animation
-        visibilityCache[sectionKey] = 'hide'; // ... maintaining our cache
+      if (curSectionVisibility !== 'hide') {          // when out-of-sync
+        $(elmSection).hide(config.animationDuration); // ... change visiblity WITH animation
+        visibilityCache[sectionKey] = 'hide';         // ... maintaining our cache
         diagMsg += 'HIDING';
       }
       else {

diff --git a/package.json b/package.json
@@ -1,11 +1,27 @@
 {
   "name": "gitbook-plugin-folding-menu",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "GitBook plugin that tames large left-nav menus by visualizing one section at a time",
   "main": "index.js",
   "engines": {
     "gitbook": "*"
   },
+  "gitbook": {
+    "properties": {
+      "animationDuration": {
+        "type":        "number",
+        "default":     400,
+        "description": "The animation duration in mills ... use 0 (zero) to disable animation ... DEFAULT: 400",
+        "min":         0,
+        "max":         5000
+      },
+      "sticky": {
+        "type":        "boolean",
+        "default":     false,
+        "description": "Leave the last section expanded when a the current active section has NO sub-content ... DEFAULT: false"
+      }
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/KevinAst/gitbook-plugin-folding-menu.git"