Adding a TOC to Component pages that have multiple elements. (Closes #434)

docs/_assets/components.css

@@ -41,6 +41,15 @@
   min-height: 1000px;
 }
 
+.mdl-components .docs-toc {
+  margin-bottom: 60px;
+}
+
+.mdl-components .component-title {
+  margin-bottom: 60px;
+  margin-top: 30px;
+}
+
 .mdl-components .mdl-components__page.is-active {
   display: block;
 }

docs/_assets/components.js

@@ -14,10 +14,11 @@
  * limitations under the License.
  */
 
-function MaterialComponents() {
+function MaterialComponentsNav() {
   'use strict';
 
   this.element_ = document.querySelector('.mdl-js-components');
+  if (this.element_) {
     this.componentLinks = this.element_.querySelectorAll('.mdl-components__link');
 
     this.activeLink = null;
@@ -25,6 +26,7 @@ function MaterialComponents() {
 
     this.init();
   }
+}
 
 /**
  * Stores a Map of the components links using their corresponding hashFragment
@@ -32,7 +34,7 @@ function MaterialComponents() {
  * @type {Object.<string, HTMLElement>}
  * @private
  */
-MaterialComponents.prototype.linksMap_ = {};
+MaterialComponentsNav.prototype.linksMap_ = {};
 
 /**
  * Store strings for class names defined by this component that are used in
@@ -41,14 +43,14 @@ MaterialComponents.prototype.linksMap_ = {};
  * @enum {string}
  * @private
  */
-MaterialComponents.prototype.CssClasses_ = {
+MaterialComponentsNav.prototype.CssClasses_ = {
   ACTIVE: 'is-active'
 };
 
 /**
- * Initializes the MaterialComponents component.
+ * Initializes the MaterialComponentsNav component.
  */
-MaterialComponents.prototype.init = function() {
+MaterialComponentsNav.prototype.init = function() {
   'use strict';
 
   this.activeLink = this.componentLinks[0];
@@ -58,20 +60,20 @@ MaterialComponents.prototype.init = function() {
     this.componentLinks[i].addEventListener('click',
         this.clickHandler(this.componentLinks[i]));
     // Mapping the list of links using their hash fragment.
-    this.linksMap_["#" + this.componentLinks[i].href.split("#")[1]]
-        = this.componentLinks[i];
+    this.linksMap_['#' + this.componentLinks[i].href.split('#')[1]] =
+        this.componentLinks[i];
   }
 
   // If a Hash fragment is available on the page then display the section.
-  this.displaySectionForFragment(window.location.hash);
+  this.displaySectionForFragment(window.location.hash.split('/')[0]);
 
   // If the hash fragment changes we display the corresponding section.
   // We won't support older browser as it's not efficient.
-  if ("onhashchange" in window) {
+  if ('onhashchange' in window) {
     var this_ = this;
     window.onhashchange = function () {
-      this_.displaySectionForFragment(window.location.hash);
-    }
+      this_.displaySectionForFragment(window.location.hash.split('/')[0]);
+    };
   }
 };
 
@@ -79,13 +81,15 @@ MaterialComponents.prototype.init = function() {
  * Displays the section for the given hash fragment.
  * @param  {String} fragment The hash fragment used in the link to the section
  */
-MaterialComponents.prototype.displaySectionForFragment = function(fragment) {
-  if (fragment
-      && this.linksMap_[fragment]
-      && this.linksMap_[fragment].click) {
+MaterialComponentsNav.prototype.displaySectionForFragment = function(fragment) {
+  'use strict';
+
+  if (fragment &&
+      this.linksMap_[fragment] &&
+      this.linksMap_[fragment].click) {
     this.linksMap_[fragment].click();
   } else {
-    document.getElementsByClassName("mdl-components__link")[0].click();
+    document.getElementsByClassName('mdl-components__link')[0].click();
   }
 };
 
@@ -94,7 +98,7 @@ MaterialComponents.prototype.displaySectionForFragment = function(fragment) {
  * @param  {HTMLElement} link the navigation link
  * @return {function} the click handler
  */
-MaterialComponents.prototype.clickHandler = function(link) {
+MaterialComponentsNav.prototype.clickHandler = function(link) {
   'use strict';
 
   var ctx = this;
@@ -112,11 +116,12 @@ MaterialComponents.prototype.clickHandler = function(link) {
     page.classList.add(ctx.CssClasses_.ACTIVE);
 
     // Add an history entry and display the hash fragment in the URL.
-    if (window.location.hash != "#"+link.href.split("#")[1]) {
-      if (link != document.getElementsByClassName("mdl-components__link")[0]) {
-        history.pushState(null, "Material Design Lite", link);
-      } else if (ctx.linksMap_[window.location.hash] != null) {
-        history.pushState(null, "Material Design Lite", "./");
+    var section = window.location.hash.split('/')[0];
+    if (section !== '#' + link.href.split('#')[1]) {
+      if (link !== document.getElementsByClassName('mdl-components__link')[0]) {
+        history.pushState(null, 'Material Design Lite', link);
+      } else if (ctx.linksMap_[section] !== null) {
+        history.pushState(null, 'Material Design Lite', './');
       }
     }
   };
@@ -127,7 +132,7 @@ MaterialComponents.prototype.clickHandler = function(link) {
  * @param  {HTMLElement} link the navigation link
  * @return {HTMLElement} the corresponding page
  */
-MaterialComponents.prototype.findPage = function(link) {
+MaterialComponentsNav.prototype.findPage = function(link) {
   'use strict';
 
   var href = link.href.split('#')[1];
@@ -137,5 +142,5 @@ MaterialComponents.prototype.findPage = function(link) {
 window.addEventListener('load', function() {
   'use strict';
 
-  new MaterialComponents();
+  new MaterialComponentsNav();
 });

docs/_pages/components.md

@@ -27,20 +27,26 @@ categories:
     description: Building blocks for constructing a page layout.
     components:
       - name: footer
+        caption: Footer
         class: mdl-mega-footer / mdl-mini-footer
       - name: grid
+        caption: Grid
         class: mdl-grid
       - name: layout
+        caption: Layout
         class: mdl-layout
       - name: tabs
+        caption: Tabs
         class: mdl-tabs
   - name: loading
     title: Loading
     description: Indicate loading and progress states.
     components:
       - name: progress
+        caption: Progress bar
         class: mdl-progress
       - name: spinner
+        caption: Spinner
         class: mdl-spinner
   - name: menus
     title: Menus
@@ -59,12 +65,16 @@ categories:
     description: Choose between states.
     components:
       - name: checkbox
+        caption: Checkbox
         class: mdl-checkbox
       - name: icon-toggle
+        caption: Icon toggle
         class: mdl-icon-toggle
       - name: radio
+        caption: Radio button
         class: mdl-radio
       - name: switch
+        caption: Switch
         class: mdl-switch
   - name: tables
     title: Tables

docs/_templates/components.html

@@ -28,12 +28,30 @@
     {% for category in page.categories -%}
     <section id="{{ category.name }}-section" class="mdl-components__page mdl-grid">
       <div class="mdl-cell mdl-cell--12-col">
-        <span class="docs-text-styling">
-          <div class="mdl-typography--display-3">{{ category.title }}</div>
+        <div class="docs-text-styling component-title">
+          <div class="mdl-typography--display-2">{{ category.title }}</div>
           <p>{{ category.description }}</p>
-          <br><br>
-        </span>
+        </div>
+
+        {% if category.components.length > 1 %}
+          <section class="docs-toc docs-text-styling">
+            <h3>Elements</h3>
+            <nav class="section-content">
+              <ul>
                 {% for component in category.components %}
+                  <li><a href="#{{ category.name }}-section/{{ component.name }}">{{ component.caption }}</a></li>
+                {%- endfor %}
+              </ul>
+            </nav>
+          </section>
+        {%- endif %}
+
+        {% for component in category.components %}
+          {% if component.caption %}
+            <span class="docs-text-styling">
+              <h1 class="mdl-components__classname" id="{{ category.name }}-section/{{ component.name }}">{{ component.caption }}</h1>
+            </span>
+          {%- endif %}
         {% set demo_css = "../../dist/components/" + component.name + "/demo.css" %}
           <style>
             {% include demo_css ignore missing %}
@@ -42,9 +60,6 @@
           <script>
             {% include demo_js ignore missing %}
           </script>
-          <span class="docs-text-styling">
-            <h1 class="mdl-components__classname">{{ component.class }}</h1>
-          </span>
           {% set demo = "../../src/" + component.name + "/demo.html" %}
           {% include demo ignore missing %}
           <span class="docs-text-styling">