Javascript Table of Contents

/*
   Create a Table of Contents
   --------------------------
   Author: Robert Mark Bram
      robertmarkbram@gmail.com
   Created: Sunday, 5th of July 2015, 11:05:22 PM

   How to use
   --------------------------
   1. Write HTML!
      Documents should only ever have one H1, but as many H2, H3, H4 etc as you need.
         <h1>Heading 1 - there should only be one</h1>
         <h2>Give me fish sniff tail flick stuck</h2>
         <p>Text.</p>
         <h3>Judging you toss the mousie run</h3>
         <p>Text.</p>
         <h4>Stumptown sartorial vinyl four dollar toast</h4>
         <p>Text.</p>

   2. Import jQuery and this API.
         <script type="text/javascript" src="/js/jquery-1.11.3.min.js"></script>
         <script type="text/javascript" src="/js/tableOfContents.js"></script>

   3. Create a script to create the TOC.
         <script type="text/javascript">
            $(function() {
               new TableOfContents().create();
            });
         </script>

   4. Style the "to the top" links [optional].
         <style>
            .toTop{
               background-color: #CAFFCA;
               text-align: right;
            }
            .toTopSub{
               background-color: #FFAAAA;
               text-align: right;
            }
         </style>

   Options you can control
   --------------------------
   Options can can be specified by including an object overriding selected
   properties. For example:
         new TableOfContents({
            style2: 'A',
            style3: 'I',
            style4: '1',
         }).create();

   List of all options is below.
         containerId = "main";
            Only look for headers contained within the element with this ID.

         style2: '1',  // h2
         style3: 'a',  // h3
         style4: 'i',  // h4
            Control what kind of marker to use in the numbered list for the
            corresponding header level. In the example above, all H2 elements
            will be a in a list numbered 1, 2, 3 etc. and H3 elements will be in
            a list of a, b, c etc. Example:
               1 first header for h2
                  a first header for h3
                  b first header for h3
                  c first header for h3
               2 second header for h2
               3 third header for h2
            Styles for H1 are not included, because the H1 is a header for the
            whole page and will not be included in the TOC. To see more about
            what types you can use, see:
               http://www.w3schools.com/tags/att_ol_type.asp
            You can keep adding style2, style3 etc to cover whatever headings
            you need.

         outputTopLink: true,
            True/false: whether or not to output "to top" links above each
            heading and add "top" ID to H1.

         topId: "top",
            ID of the element that all "to top" links should go to. By default,
            this will be added to the first H1 (there should only be one).

         bottomId: "bottom",
            ID of the element that the final "to top" link should be added
            BEFORE.

         toTopClass2: "toTop",
         toTopClass3: "toTopSub",
            Class that will be added to the P element that contains a "to top"
            link under the menu and each heading. Styles correspond to the
            heading level so that we can have sub-headings. Empty or null means
            not to output "to top" links at this level.

   Examples
   --------------------------
   1. Example showing how to override all of the options.
         http://jsfiddle.net/robertmarkbram/29wb1v3p/
         http://www.chihuahuarescuevictoria.org/tech-examples/toc/toc_1.html

   2. Simplest example not overriding any options.
         http://jsfiddle.net/robertmarkbram/gjxrvbjy/
         http://www.chihuahuarescuevictoria.org/tech-examples/toc/toc_2.html

*/
function TableOfContents(properties) {

   // Reference to this in current scope.
   var self = this;

   // Only look for headers contained in this ID.
   this.containerId = "";

   // Styles for ordered lists corresponding to header level.
   // Should only be one H1, and not included in TOC.
   this.style2 = '1';  // 2
   this.style3 = 'a';  // 3
   this.style4 = 'i';  // 4

   // True/false: output "to top" link and add "top" ID to H1.
   this.outputTopLink = true;

   // ID of the element that all "to top" links should go to.
   this.topId = "top";

   // ID of the element that the final "to top" link should go BEFORE.
   this.bottomId = "bottom";

   // Class of the P element that contains a "to top" link under the menu.
   // Styles correspond to the heading level so that we can have sub-headings.
   // Empty or null means not to output "to top" links at this level.
   this.toTopClass2 = "toTop";
   this.toTopClass3 = "toTopSub";

   /* Create table of contents. */
   this.create = function() {
      // Work out container of all headings.
      var $container = null;
      if (self.containerId) {
         $container = $("#" + self.containerId);
      } else {
         $container = $("body");
      }

      // Add id to first H1 and put menu after it (or after menuPre if present).
      var $pageTitle = $($container.find("h1")[0]);
      var $menuPre = $("#menuPre");
      var $menu = $('<ol id="menu" type="' + self.style2 + '"></ol>');
      if ($menuPre.length > 0) {
         $menuPre.after($menu);
      } else if ($pageTitle.length > 0) {
         $pageTitle.after($menu);
      } else {
         $container.prepend($menu);
      }

      // Add top ID and links to it.
      if (self.outputTopLink) {
         // Add "top" ID to H1.
         $pageTitle.attr('id', self.topId);
      }

      // We need to track set of sub-menus by heading level.
      var menus = new Array();
      menus[2] = $menu;
      var $subMenu = $menu;
      var headingLevel = 2;
      var headingLevelPrevious = 2;

      // Populate menu with all header elements. But skip first.
      $container.find("h2, h3, h4, h5").each(function( index ) {
         var $heading = $(this);
         headingLevelPrevious = headingLevel;
         headingLevel = $heading.prop("tagName").substring(1);

         // If the heading doesn't have an ID, give it one.
         if (!$heading.attr('id')) {
            $heading.attr('id', $heading.text().replace(/[^0-9a-zA-Z]/g, ""));
         }
         // Create and store new sub-menu if current header is deeper than previous.
         var listType = null;
         if (headingLevel > headingLevelPrevious) {
            $subMenu = $('<ol type="'
                  + $(self).prop("style" + headingLevel) + '"></ol>');
            menus[headingLevel] = $subMenu;
            menus[headingLevelPrevious].append($subMenu);
         }
         // But if we are going back up the chain, get the correct submenu.
         if (headingLevel < headingLevelPrevious) {
            $subMenu = menus[headingLevel];
         }

         // And menu element pointing to the heading.
         $subMenu.append('<li><a href="#' + $(this).attr('id') + '">'
               + $(this).text() + '</a></li>');

         // If we output to top links and if class is set for that level.
         if (self.outputTopLink) {
            var className = $(self).prop("toTopClass" + headingLevel);

            // Add "to top" link above every heading.
            if (className) {
               $heading.before('<p class="' + className + '"><a href="#'
                     + self.topId + '">Top</a></p>');
            }
         }
      });
      // If we output to top links and if class is set for that level.
      if (self.outputTopLink) {
         var className = $(self).prop("toTopClass2");

         // Add final "to top" link.
         if (className) {
            var $bottom = $("#" + self.bottomId);
            if ($bottom.length > 0) {
               $("#" + self.bottomId).before('<p class="' + className + '"><a href="#'
                        + self.topId + '">Top</a></p>');
            } else {
               $("body").append('<p class="' + className + '"><a href="#'
                        + self.topId + '">Top</a></p>');
            }
         }
      }

   };

   // Override properties of this object with supplied properties.
   $.extend(this, properties);

}