Skip to content

Commit c72497b

Browse files
KevinAstKevinAst
authored
Merge pull request #2 from KevinAst/next2
publish: v1.0.1 Added Configuration
2 parents d956b4a + d74b06d commit c72497b

File tree

4 files changed

+164
-92
lines changed

4 files changed

+164
-92
lines changed

‎CHANGELOG.md‎

Lines changed: 0 additions & 61 deletions
This file was deleted.

‎README.md‎

Lines changed: 121 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,17 @@ one section at a time** _(the active section)_.
77

88
[![NPM Version Badge](https://img.shields.io/npm/v/gitbook-plugin-folding-menu.svg)](https://www.npmjs.com/package/gitbook-plugin-folding-menu)
99

10+
11+
## At a Glance
12+
13+
- [Overview]
14+
- [Install]
15+
- [Configuration]
16+
- [Revision History]
17+
* [v1.0.1] - Added Configuration *(September 8, 2018)*
18+
* [v1.0.0] - Initial Release *(September 7, 2018)*
19+
20+
1021
## Overview
1122

1223
The high-level points of interest are:
@@ -39,29 +50,119 @@ This project is a significant improvement on other similar plugins.
3950

4051
## Install
4152

42-
- Add the `"folding-menu"` plugin to your **book.json** file:
43-
44-
```js
45-
{
46-
"plugins": [
47-
... other plugins you may be using
48-
"folding-menu"
49-
]
53+
1. Add the `"folding-menu"` plugin to your **book.json** file:
54+
55+
**book.json**
56+
```js
57+
{
58+
...
59+
"plugins": [
60+
... other plugins you may be using
61+
"folding-menu"
62+
]
63+
...
64+
}
65+
```
66+
67+
2. Install the plugin using **one** of the following options _(based on your gitbook usage)_:
68+
69+
- For https://legacy.gitbook.com/ usage, plugins are automatically installed.
70+
71+
- For local gitbook usage run `gitbook install` to install and prepare
72+
all plugins for your books:
73+
74+
```shell
75+
gitbook install
76+
```
77+
78+
- For technical users _(ex: open source documentation)_, install the
79+
plugin to your **devDependencies** as follows:
80+
81+
```shell
82+
npm install --save-dev gitbook-plugin-folding-menu
83+
```
84+
85+
86+
## Configuration
87+
88+
You may optionally supply the following configuration to this plugin:
89+
90+
<ul><!--- indentation hack for github - other attempts with style is stripped (be careful with number bullets) --->
91+
92+
**book.json**
93+
```js
94+
{
95+
...
96+
"pluginsConfig": {
97+
"folding-menu": {
98+
"animationDuration": 500,
99+
"sticky": true
100+
}
50101
}
51-
```
102+
...
103+
}
104+
```
105+
106+
</ul>
107+
108+
- **animationDuration** - The animation duration in mills ... use 0
109+
(zero) to disable animation ... **DEFAULT: 400**
110+
111+
- **sticky** - Leave the last section expanded when a the current
112+
active section has NO sub-content ... **DEFAULT: false**
113+
114+
115+
## Revision History
116+
117+
118+
Release | What | *When*
119+
---------|-------------------------------------------------|------------------
120+
[v1.0.1] | Added Configuration | *September 8, 2018*
121+
[v1.0.0] | Initial Release | *September 7, 2018*
122+
123+
124+
125+
<!-- *** RELEASE *************************************************************** -->
126+
127+
### v1.0.1 - Added Configuration *(September 8, 2018)*
128+
129+
<ul><ul><!--- indentation hack for github - other attempts with style is stripped (be careful with number bullets) --->
130+
131+
[GitHub Content](https://github.com/KevinAst/gitbook-plugin-folding-menu/tree/v1.0.1)
132+
&bull;
133+
[GitHub Release](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases/tag/v1.0.1)
134+
&bull;
135+
[Diff](https://github.com/KevinAst/gitbook-plugin-folding-menu/compare/v1.0.0...v1.0.1)
136+
137+
**NOTE**: This release is a **non-breaking change** _(i.e. no API was affected)_.
138+
139+
- This plugin is now configurable _(see: [Configuration])_.
140+
141+
</ul></ul>
142+
143+
144+
145+
<!-- *** RELEASE *************************************************************** -->
146+
147+
### v1.0.0 - Initial Release *(September 7, 2018)*
148+
149+
<ul><ul><!--- indentation hack for github - other attempts with style is stripped (be careful with number bullets) --->
150+
151+
[GitHub Content](https://github.com/KevinAst/gitbook-plugin-folding-menu/tree/v1.0.0)
152+
&bull;
153+
[GitHub Release](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases/tag/v1.0.0)
154+
155+
**This is where it all began ...**
52156

53-
- For https://legacy.gitbook.com/ usage, plugins are automatically installed.
157+
</ul></ul>
54158

55-
- For local gitbook usage run `gitbook install` to install and prepare
56-
all plugins for your books:
57159

58-
```shell
59-
gitbook install
60-
```
61160

62-
- For technical users _(ex: open source documentation)_, install the
63-
plugin to your **devDependencies** as follows:
64161

65-
```shell
66-
npm install --save-dev gitbook-plugin-folding-menu
67-
```
162+
<!--- *** REFERENCE LINKS *** --->
163+
[Overview]: #overview
164+
[Install]: #install
165+
[Configuration]: #configuration
166+
[Revision History]: #revision-history
167+
[v1.0.1]: #v101---added-configuration-september-8-2018
168+
[v1.0.0]: #v100---initial-release-september-7-2018

‎book/plugin.js‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,23 @@
55
//***
66
require(["gitbook", "jQuery"], function(gitbook, $) {
77

8+
// our plugin configuration object
9+
// ... optionally defined in client book.json
10+
// ... auto defaulted by gitbook as follows:
11+
// config: {
12+
// animationDuration: 400,
13+
// sticky: false
14+
// }
15+
var config = null;
16+
17+
// glean plugin configuration on start event
18+
gitbook.events.bind('start', function(e, myConfig) {
19+
// simply retain in parent scope (for subsequent use)
20+
config = myConfig['folding-menu'];
21+
diag('start event ... config: ', config);
22+
});
23+
24+
825
// listen for gitbook "page.change" events
926
// ... emitted whenever a file.md changes
1027
gitbook.events.bind("page.change", function(e) {
@@ -50,9 +67,10 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
5067
// starts out with leftNav expanded!!!
5168
baselinePriorVisibility($topSections);
5269

53-
// leave the last expanded section in-tact, when a the current section has NO content
70+
// when necessary, leave the last section expanded
5471
// ... by simply no-oping
55-
if ($activeTopSection.length === 0) {
72+
if (config.sticky && // when configured to be sticky -AND-
73+
$activeTopSection.length === 0) { // the current active section has NO sub-content
5674
return;
5775
}
5876

@@ -136,28 +154,26 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
136154
// - resulting in a MUCH better visual
137155
function setVisible(elmSection, directive) {
138156

139-
var animationDelay = 400; // utilize an appropriate animation delay (nice visual)
140-
141157
var sectionKey = getSectionKey(elmSection);
142158
var curSectionVisibility = getCurSectionVisibility(sectionKey);
143159

144160
var diagMsg = 'setVisible(elmSection: ' + sectionKey + ', directive: ' + directive + ') ... curSectionVisibility: ' + curSectionVisibility + ' ... ';
145161

146162
// apply the visibility directive, when needed (based on cached current visibility)
147163
if (directive === 'show') {
148-
if (curSectionVisibility !== 'show') { // when out-of-sync
149-
$(elmSection).show(animationDelay); // ... change visiblity WITH animation
150-
visibilityCache[sectionKey] = 'show'; // ... maintaining our cache
164+
if (curSectionVisibility !== 'show') { // when out-of-sync
165+
$(elmSection).show(config.animationDuration); // ... change visiblity WITH animation
166+
visibilityCache[sectionKey] = 'show'; // ... maintaining our cache
151167
diagMsg += 'SHOWING';
152168
}
153169
else {
154170
diagMsg += 'no-oping';
155171
}
156172
}
157173
else {
158-
if (curSectionVisibility !== 'hide') { // when out-of-sync
159-
$(elmSection).hide(animationDelay); // ... change visiblity WITH animation
160-
visibilityCache[sectionKey] = 'hide'; // ... maintaining our cache
174+
if (curSectionVisibility !== 'hide') { // when out-of-sync
175+
$(elmSection).hide(config.animationDuration); // ... change visiblity WITH animation
176+
visibilityCache[sectionKey] = 'hide'; // ... maintaining our cache
161177
diagMsg += 'HIDING';
162178
}
163179
else {

‎package.json‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,27 @@
11
{
22
"name": "gitbook-plugin-folding-menu",
3-
"version": "1.0.0",
3+
"version": "1.0.1",
44
"description": "GitBook plugin that tames large left-nav menus by visualizing one section at a time",
55
"main": "index.js",
66
"engines": {
77
"gitbook": "*"
88
},
9+
"gitbook": {
10+
"properties": {
11+
"animationDuration": {
12+
"type": "number",
13+
"default": 400,
14+
"description": "The animation duration in mills ... use 0 (zero) to disable animation ... DEFAULT: 400",
15+
"min": 0,
16+
"max": 5000
17+
},
18+
"sticky": {
19+
"type": "boolean",
20+
"default": false,
21+
"description": "Leave the last section expanded when a the current active section has NO sub-content ... DEFAULT: false"
22+
}
23+
}
24+
},
925
"repository": {
1026
"type": "git",
1127
"url": "https://github.com/KevinAst/gitbook-plugin-folding-menu.git"

0 commit comments

Comments
 (0)