diff --git a/bootstrap-toc.js b/bootstrap-toc.js index 9311722..6fcc734 100644 --- a/bootstrap-toc.js +++ b/bootstrap-toc.js @@ -1,7 +1,12 @@ /*! * Bootstrap Table of Contents v<%= version %> (http://afeld.github.io/bootstrap-toc/) * Copyright 2015 Aidan Feldman - * Licensed under MIT (https://github.com/afeld/bootstrap-toc/blob/gh-pages/LICENSE.md) */ + * Licensed under MIT (https://github.com/afeld/bootstrap-toc/blob/gh-pages/LICENSE.md) + * + * Modified by Ircama, 2016, adding the following options: + * - headings + * - class + */ (function() { 'use strict'; @@ -56,8 +61,8 @@ return $childList; }, - generateNavEl: function(anchor, text) { - var $a = $(''); + generateNavEl: function(anchor, text, navLevel, hClass) { + var $a = $(''); $a.attr('href', '#' + anchor); $a.text(text); var $li = $('
  • '); @@ -65,11 +70,11 @@ return $li; }, - generateNavItem: function(headingEl) { + generateNavItem: function(headingEl, navLevel, hClass) { var anchor = this.generateAnchor(headingEl); var $heading = $(headingEl); var text = $heading.data('toc-text') || $heading.text(); - return this.generateNavEl(anchor, text); + return this.generateNavEl(anchor, text, navLevel, hClass); }, // Find the first heading level (`

    `, then `

    `, etc.) that has more than one element. Defaults to 1 (for `

    `). @@ -85,30 +90,34 @@ }, // returns the elements for the top level, and the next below it - getHeadings: function($scope, topLevel) { - var topSelector = 'h' + topLevel; - - var secondaryLevel = topLevel + 1; - var secondarySelector = 'h' + secondaryLevel; - - return this.findOrFilter($scope, topSelector + ',' + secondarySelector); + getHeadings: function($scope, topLevel, headingList) { + if (headingList === undefined) { + var topSelector = 'h' + topLevel; + + var secondaryLevel = topLevel + 1; + var secondarySelector = 'h' + secondaryLevel; + + return this.findOrFilter($scope, topSelector + ',' + secondarySelector); + } else { + return this.findOrFilter($scope, headingList); + } }, getNavLevel: function(el) { return parseInt(el.tagName.charAt(1), 10); }, - populateNav: function($topContext, topLevel, $headings) { + populateNav: function($topContext, topLevel, $headings, hClass) { var $context = $topContext; var $prevNav; var helpers = this; $headings.each(function(i, el) { - var $newNav = helpers.generateNavItem(el); var navLevel = helpers.getNavLevel(el); + var $newNav = helpers.generateNavItem(el, navLevel, hClass); // determine the proper $context - if (navLevel === topLevel) { + if (navLevel <= topLevel) { // use top level $context = $topContext; } else if ($prevNav && $context === $topContext) { @@ -137,16 +146,18 @@ }, // accepts a jQuery object, or an options object - init: function(opts) { + init: function(opts, conf) { opts = this.helpers.parseOps(opts); + var headingList = conf === undefined ? undefined : conf.headings; + var hClass = conf === undefined || conf.class === undefined || conf.class == '' ? 'toc-nav-h' : conf.class; // ensure that the data attribute is in place for styling opts.$nav.attr('data-toggle', 'toc'); var $topContext = this.helpers.createChildNavList(opts.$nav); var topLevel = this.helpers.getTopLevel(opts.$scope); - var $headings = this.helpers.getHeadings(opts.$scope, topLevel); - this.helpers.populateNav($topContext, topLevel, $headings); + var $headings = this.helpers.getHeadings(opts.$scope, topLevel, headingList); + this.helpers.populateNav($topContext, topLevel, $headings, hClass); } }; diff --git a/dist/bootstrap-toc.js b/dist/bootstrap-toc.js index 1cdd573..6fcc734 100644 --- a/dist/bootstrap-toc.js +++ b/dist/bootstrap-toc.js @@ -1,7 +1,12 @@ /*! - * Bootstrap Table of Contents v0.4.1 (http://afeld.github.io/bootstrap-toc/) + * Bootstrap Table of Contents v<%= version %> (http://afeld.github.io/bootstrap-toc/) * Copyright 2015 Aidan Feldman - * Licensed under MIT (https://github.com/afeld/bootstrap-toc/blob/gh-pages/LICENSE.md) */ + * Licensed under MIT (https://github.com/afeld/bootstrap-toc/blob/gh-pages/LICENSE.md) + * + * Modified by Ircama, 2016, adding the following options: + * - headings + * - class + */ (function() { 'use strict'; @@ -56,8 +61,8 @@ return $childList; }, - generateNavEl: function(anchor, text) { - var $a = $(''); + generateNavEl: function(anchor, text, navLevel, hClass) { + var $a = $(''); $a.attr('href', '#' + anchor); $a.text(text); var $li = $('
  • '); @@ -65,11 +70,11 @@ return $li; }, - generateNavItem: function(headingEl) { + generateNavItem: function(headingEl, navLevel, hClass) { var anchor = this.generateAnchor(headingEl); var $heading = $(headingEl); var text = $heading.data('toc-text') || $heading.text(); - return this.generateNavEl(anchor, text); + return this.generateNavEl(anchor, text, navLevel, hClass); }, // Find the first heading level (`

    `, then `

    `, etc.) that has more than one element. Defaults to 1 (for `

    `). @@ -85,30 +90,34 @@ }, // returns the elements for the top level, and the next below it - getHeadings: function($scope, topLevel) { - var topSelector = 'h' + topLevel; - - var secondaryLevel = topLevel + 1; - var secondarySelector = 'h' + secondaryLevel; - - return this.findOrFilter($scope, topSelector + ',' + secondarySelector); + getHeadings: function($scope, topLevel, headingList) { + if (headingList === undefined) { + var topSelector = 'h' + topLevel; + + var secondaryLevel = topLevel + 1; + var secondarySelector = 'h' + secondaryLevel; + + return this.findOrFilter($scope, topSelector + ',' + secondarySelector); + } else { + return this.findOrFilter($scope, headingList); + } }, getNavLevel: function(el) { return parseInt(el.tagName.charAt(1), 10); }, - populateNav: function($topContext, topLevel, $headings) { + populateNav: function($topContext, topLevel, $headings, hClass) { var $context = $topContext; var $prevNav; var helpers = this; $headings.each(function(i, el) { - var $newNav = helpers.generateNavItem(el); var navLevel = helpers.getNavLevel(el); + var $newNav = helpers.generateNavItem(el, navLevel, hClass); // determine the proper $context - if (navLevel === topLevel) { + if (navLevel <= topLevel) { // use top level $context = $topContext; } else if ($prevNav && $context === $topContext) { @@ -137,16 +146,18 @@ }, // accepts a jQuery object, or an options object - init: function(opts) { + init: function(opts, conf) { opts = this.helpers.parseOps(opts); + var headingList = conf === undefined ? undefined : conf.headings; + var hClass = conf === undefined || conf.class === undefined || conf.class == '' ? 'toc-nav-h' : conf.class; // ensure that the data attribute is in place for styling opts.$nav.attr('data-toggle', 'toc'); var $topContext = this.helpers.createChildNavList(opts.$nav); var topLevel = this.helpers.getTopLevel(opts.$scope); - var $headings = this.helpers.getHeadings(opts.$scope, topLevel); - this.helpers.populateNav($topContext, topLevel, $headings); + var $headings = this.helpers.getHeadings(opts.$scope, topLevel, headingList); + this.helpers.populateNav($topContext, topLevel, $headings, hClass); } }; diff --git a/dist/bootstrap-toc.min.js b/dist/bootstrap-toc.min.js index 35bae96..d6b1509 100644 --- a/dist/bootstrap-toc.min.js +++ b/dist/bootstrap-toc.min.js @@ -1,5 +1,26 @@ /*! - * Bootstrap Table of Contents v0.4.1 (http://afeld.github.io/bootstrap-toc/) - * Copyright 2015 Aidan Feldman + * Bootstrap Table of Contents v0.4.2 (http://afeld.github.io/bootstrap-toc/) + * Copyright 2015 Aidan Feldman, modified by Ircama, 2016 * Licensed under MIT (https://github.com/afeld/bootstrap-toc/blob/gh-pages/LICENSE.md) */ -!function(){"use strict";window.Toc={helpers:{findOrFilter:function(e,t){var r=e.find(t);return e.filter(t).add(r).filter(":not([data-toc-skip])")},generateUniqueIdBase:function(e){var t=$(e).text(),r=t.trim().toLowerCase().replace(/[^A-Za-z0-9]+/g,"-");return r||e.tagName.toLowerCase()},generateUniqueId:function(e){for(var t=this.generateUniqueIdBase(e),r=0;;r++){var n=t;if(r>0&&(n+="-"+r),!document.getElementById(n))return n}},generateAnchor:function(e){if(e.id)return e.id;var t=this.generateUniqueId(e);return e.id=t,t},createNavList:function(){return $('')},createChildNavList:function(e){var t=this.createNavList();return e.append(t),t},generateNavEl:function(e,t){var r=$("");r.attr("href","#"+e),r.text(t);var n=$("
  • ");return n.append(r),n},generateNavItem:function(e){var t=this.generateAnchor(e),r=$(e),n=r.data("toc-text")||r.text();return this.generateNavEl(t,n)},getTopLevel:function(e){for(var t=1;t<=6;t++){var r=this.findOrFilter(e,"h"+t);if(r.length>1)return t}return 1},getHeadings:function(e,t){var r="h"+t,n=t+1,a="h"+n;return this.findOrFilter(e,r+","+a)},getNavLevel:function(e){return parseInt(e.tagName.charAt(1),10)},populateNav:function(e,t,r){var n,a=e,i=this;r.each(function(r,o){var s=i.generateNavItem(o),u=i.getNavLevel(o);u===t?a=e:n&&a===e&&(a=i.createChildNavList(n)),a.append(s),n=s})},parseOps:function(e){var t;return t=e.jquery?{$nav:e}:e,t.$scope=t.$scope||$(document.body),t}},init:function(e){e=this.helpers.parseOps(e),e.$nav.attr("data-toggle","toc");var t=this.helpers.createChildNavList(e.$nav),r=this.helpers.getTopLevel(e.$scope),n=this.helpers.getHeadings(e.$scope,r);this.helpers.populateNav(t,r,n)}},$(function(){$('nav[data-toggle="toc"]').each(function(e,t){var r=$(t);Toc.init(r)})})}(); \ No newline at end of file +!function(){"use strict" +window.Toc={helpers:{findOrFilter:function(e,t){var r=e.find(t) +return e.filter(t).add(r).filter(":not([data-toc-skip])")},generateUniqueIdBase:function(e){var t=$(e).text(),r=t.trim().toLowerCase().replace(/[^A-Za-z0-9]+/g,"-") +return r||e.tagName.toLowerCase()},generateUniqueId:function(e){for(var t=this.generateUniqueIdBase(e),r=0;;r++){var a=t +if(r>0&&(a+="-"+r),!document.getElementById(a))return a}},generateAnchor:function(e){if(e.id)return e.id +var t=this.generateUniqueId(e) +return e.id=t,t},createNavList:function(){return $('')},createChildNavList:function(e){var t=this.createNavList() +return e.append(t),t},generateNavEl:function(e,t,r,a){var n=$("") +n.attr("href","#"+e),n.text(t) +var i=$("
  • ") +return i.append(n),i},generateNavItem:function(e,t,r){var a=this.generateAnchor(e),n=$(e),i=n.data("toc-text")||n.text() +return this.generateNavEl(a,i,t,r)},getTopLevel:function(e){for(var t=1;6>=t;t++){var r=this.findOrFilter(e,"h"+t) +if(r.length>1)return t}return 1},getHeadings:function(e,t,r){if(void 0===r){var a="h"+t,n=t+1,i="h"+n +return this.findOrFilter(e,a+","+i)}return this.findOrFilter(e,r)},getNavLevel:function(e){return parseInt(e.tagName.charAt(1),10)},populateNav:function(e,t,r,a){var n,i=e,s=this +r.each(function(r,o){var c=s.getNavLevel(o),v=s.generateNavItem(o,c,a) +t>=c?i=e:n&&i===e&&(i=s.createChildNavList(n)),i.append(v),n=v})},parseOps:function(e){var t +return t=e.jquery?{$nav:e}:e,t.$scope=t.$scope||$(document.body),t}},init:function(e,t){e=this.helpers.parseOps(e) +var r=void 0===t?void 0:t.headings,a=void 0===t||void 0===t["class"]||""==t["class"]?"toc-nav-h":t["class"] +e.$nav.attr("data-toggle","toc") +var n=this.helpers.createChildNavList(e.$nav),i=this.helpers.getTopLevel(e.$scope),s=this.helpers.getHeadings(e.$scope,i,r) +this.helpers.populateNav(n,i,s,a)}},$(function(){$('nav[data-toggle="toc"]').each(function(e,t){var r=$(t) +Toc.init(r)})})}() \ No newline at end of file diff --git a/index.md b/index.md index 453025d..5d44598 100644 --- a/index.md +++ b/index.md @@ -154,6 +154,72 @@ nav[data-toggle='toc'] { } ``` +## Additional options + +By default, the plugin finds the first heading level (`

    `, then `

    `, etc.) that has more than one element and defaults to 1 (for `

    `). The identified level becomes the top heading and the plugin supports a single nesting level associated to it, including the subsequent heading only. E.g., if the identified top level is `

    `, the nested level will be `

    `, which is the next below it; if the top level is `

    `, the nested one will be `

    `. No additional level to the nested one and no previous level to the top one will be shown. + +The plugin allows options to customize this behavior: + +* `headings` (which can be a string): if set to a list of headers (in the form *hN,hM,...* where N, M, ... are levels, e.g., `h1,h2,h3`), all of them are searched instead of the first declared one and of its subsequent heading. Example: `headings: 'h1,h2,h3,h4,h5,h6'` (in this case, all of them are searched and not only `

    ` and `

    ` in case `

    ` is the top level). +* `class`: (which can be a string): if set to a string, its value is used to customize the CSS class that the plugin sets for each description, concatenating it with the related header level. If not set, the default class heading will be `toc-nav-h`. Example: by default, a top level description (`

    `) has class`toc-nav-h1`, a second level description (`

    `) has class `toc-nav-h2`, etc. If the option `class` is set to e.g. `my-class`, a top level description (`

    `) will have class `my-class-h1`, a second level description (`

    `) will have class `my-class-h2`, etc. This feature allows adding CSS attributes to customize the descriptions according its header level. + +Example of usage: + +```javascript +Toc.init($myNav, { + headings: 'h1,h2,h3,h4,h5,h6', + class: 'my-class' +}); +``` + +Example of CSS to customize the behavior of the plugin where the target documentation is supposed to mostly exploit `

    ` as top level and `

    ` as neighboring one (supposing to set `headings: 'h1,h2,h3,h4,h5,h6'` and not to change the default `class` option): + +```css +/* + * Customizations of Bootstrap Table of Contents v0.4.2 + */ +nav[data-toggle='toc'] .nav .nav > li > a { + padding-bottom: 3px !important; +} +.toc-nav-h1 { + text-decoration: navy dotted underline; + font-size: 15px !important; + padding-left: 15px !important; +} +.toc-nav-h4 { + font-size: 11px !important; + padding-left: 40px !important; +} +.toc-nav-h5 { + font-size: 11px !important; + padding-left: 46px !important; +} +.toc-nav-h6 { + font-size: 11px !important; + padding-left: 52px !important; +} +``` + +The following example includes an additional setting for scrollspy (both `target` and `offset` options are used: + +```html + +``` + ## See also This plugin was heavily inspired by: diff --git a/package.json b/package.json index 3316c06..e9524a1 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "bootstrap-toc", - "version": "0.4.1", + "version": "0.4.2", "private": true, "scripts": { "test": "gulp test"