Merge pull request #14 from bit-docs/headings-container

Allow setting the headings container selector

Author: Manuel Mujica

readme.md

@@ -31,8 +31,20 @@ Where `$VERSION` is the latest version on npm.
 
 In your template add a class **on-this-page-container**:
 
-```js
+```html
 <div class="on-this-page-container"></div>
 ```
 
+By default, all heading tags children of the first `article` tag on the page will 
+be collected to create the table of contents; if you want to use a different element
+just do:
+
+```html
+<div 
+  class="on-this-page-container"
+  data-heading-container-selector="#my-custom-selector"
+>
+</div>
+```
+
 The table of contents will be injected into this element at run time.

test/test.js

@@ -1,2 +1,4 @@
 require("./make-tree-test");
 require("./toc-control-test");
+require("./toc-container-control-test");
+

test/toc-container-control-test.js

@@ -0,0 +1,85 @@
+var $ = require("jquery");
+var assert = require("chai/chai").assert;
+var TOCContainer = require("../toc-container-control");
+
+require("steal-mocha");
+
+describe("TOCContainer", function() {
+	var $el, $testArea;
+
+	beforeEach(function() {
+		$("body").append('<div id="toc-container"></div>');
+
+		$el = $("#toc-container");
+		$testArea = $("#test-area");
+	});
+
+	afterEach(function() {
+		$el.remove();
+		$testArea.empty();
+	});
+
+	it("by default gets headings from 'article' children", function() {
+		var headings = [
+			'<article>',
+				"<h2>Usage</h2>",
+				"<h2>Install</h2>",
+				"<h2>Configure</h2>",
+			"</article>"
+		];
+
+		// append the headings to the DOM and then instantiate the control
+		$("body").append(headings.join(""));
+		new TOCContainer($el.get(0));
+
+		var $items = $("#toc-container ul");
+		assert.equal(
+			$items.html(),
+			[
+				'<li><a href="#usage">Usage</a></li>',
+				'<li><a href="#install">Install</a></li>',
+				'<li><a href="#configure">Configure</a></li>',
+			].join(""),
+			"should create table of contents from the headings inside container"
+		);
+
+		// remove headings container from the DOM
+		$("article").remove();
+	});
+
+	it("reads the headings container selector from the element", function() {
+		// set the container selector as a data-* attribute
+		$el.attr(
+			"data-headings-container-selector",
+			".my-custom-container"
+		);
+
+		var headings = [
+			'<div class="my-custom-container">',
+				"<h2>Usage</h2>",
+				"<h2>Install</h2>",
+				"<h2>Configure</h2>",
+				"<h2>Configure</h2>",
+			"</div>"
+		];
+
+		// append the headings to the DOM and then instantiate the control
+		$("body").append(headings.join(""));
+		new TOCContainer($el.get(0));
+
+		var $items = $("#toc-container ul");
+		assert.equal(
+			$items.html(),
+			[
+				'<li><a href="#usage">Usage</a></li>',
+				'<li><a href="#install">Install</a></li>',
+				'<li><a href="#configure">Configure</a></li>',
+				'<li><a href="#configure-1">Configure</a></li>'
+			].join(""),
+			"should create table of contents from the headings inside container"
+		);
+
+		// remove headings container from the DOM
+		$(".my-custom-container").remove();
+	});
+});

toc-container-control.js

@@ -0,0 +1,46 @@
+var Control = require("can-control");
+var TableOfContents = require("./toc-control");
+
+module.exports =  Control.extend({
+	init: function(el) {
+		el.style.display = "none";
+
+		var depth = this.getOutlineDepth();
+		var tagName = this.getOutlineTagName();
+		var selector = this.getHeadingsContainerSelector(el);
+
+		var toc = document.createElement(tagName);
+		toc.className = "on-this-page";
+		el.appendChild(toc);
+
+		new TableOfContents(toc, {
+			depth: depth,
+			tagName: tagName,
+			headingsContainerSelector: selector
+		});
+	},
+
+	getDocObject() {
+		return window.docObject || {};
+	},
+
+	getOutlineTagName: function() {
+		var docObject = this.getDocObject();
+		var outline = docObject.outline || {};
+
+		return (outline.tag === "ol") ? "ol" : "ul";
+	},
+
+	getOutlineDepth: function() {
+		var docObject = this.getDocObject();
+		var depth = docObject.outline && docObject.outline.depth;
+
+		return (typeof depth === "number" ? Math.min(depth, 6) : 1);
+	},
+
+	getHeadingsContainerSelector(el) {
+		var selector = el.dataset.headingsContainerSelector;
+
+		return selector ? selector : "article";
+	}
+});

toc.js

@@ -1,35 +1,9 @@
-var Control = require("can-control");
-var TableOfContents = require("./toc-control");
+var TOCContainer =  require("./toc-container-control");
 
-var TOCContainer = Control.extend({
-	init: function(el) {
-		el.style.display = "none";
+var el = document.getElementsByClassName("on-this-page-container");
 
-		var depth = this.getOutlineDepth();
-		var tagName = this.getOutlineTagName();
-		var toc = document.createElement(tagName);
-
-		toc.className = "on-this-page";
-		el.appendChild(toc);
-
-		new TableOfContents(toc, {
-			depth: depth,
-			tagName: tagName,
-			headingsContainerSelector: "article"
-		});
-	},
-
-	getOutlineTagName: function() {
-		var outline = window.docObject.outline || {};
-		return (outline.tag === "ol") ? "ol" : "ul";
-	},
-
-	getOutlineDepth: function() {
-		var depth = window.docObject.outline && window.docObject.outline.depth;
-		return (typeof depth === "number" ? Math.min(depth, 6) : 1);
-	}
-});
-
-new TOCContainer(
-	document.getElementsByClassName("on-this-page-container")[0]
-);
+if (el.length) {
+	new TOCContainer(el);
+} else {
+	console.log("An element with class 'on-this-page-container' is required");
+}