jquery.tocify.js

/* jquery Tocify - v1.9.1 - 2013-10-22
 * http://www.gregfranko.com/jquery.tocify.js/
 * Copyright (c) 2013 Greg Franko; Licensed MIT */

// Immediately-Invoked Function Expression (IIFE) [Ben Alman Blog Post](http://benalman.com/news/2010/11/immediately-invoked-function-expression/) that calls another IIFE that contains all of the plugin logic.  I used this pattern so that anyone viewing this code would not have to scroll to the bottom of the page to view the local parameters that were passed to the main IIFE.
(function(tocify) {

    // ECMAScript 5 Strict Mode: [John Resig Blog Post](http://ejohn.org/blog/ecmascript-5-strict-mode-json-and-more/)
    "use strict";

    // Calls the second IIFE and locally passes in the global jQuery, window, and document objects
    tocify(window.jQuery, window, document);

  }

  // Locally passes in `jQuery`, the `window` object, the `document` object, and an `undefined` variable.  The `jQuery`, `window` and `document` objects are passed in locally, to improve performance, since javascript first searches for a variable match within the local variables set before searching the global variables set.  All of the global variables are also passed in locally to be minifier friendly. `undefined` can be passed in locally, because it is not a reserved word in JavaScript.
  (function($, window, document, undefined) {

    // ECMAScript 5 Strict Mode: [John Resig Blog Post](http://ejohn.org/blog/ecmascript-5-strict-mode-json-and-more/)
    "use strict";

    var tocClassName = "tocify",
      tocClass = "." + tocClassName,
      tocFocusClassName = "tocify-focus",
      tocHoverClassName = "tocify-hover",
      hideTocClassName = "tocify-hide",
      hideTocClass = "." + hideTocClassName,
      headerClassName = "tocify-header",
      headerClass = "." + headerClassName,
      subheaderClassName = "tocify-subheader",
      subheaderClass = "." + subheaderClassName,
      itemClassName = "tocify-item",
      itemClass = "." + itemClassName,
      extendPageClassName = "tocify-extend-page",
      extendPageClass = "." + extendPageClassName;

    // Calling the jQueryUI Widget Factory Method
    $.widget("toc.tocify", {

      //Plugin version
      version: "1.9.1",

      // These options will be used as defaults
      options: {

        // **context**: Accepts String: Any jQuery selector
        // The container element that holds all of the elements used to generate the table of contents
        context: "body",

        // **ignoreSelector**: Accepts String: Any jQuery selector
        // A selector to any element that would be matched by selectors that you wish to be ignored
        ignoreSelector: null,

        // **selectors**: Accepts an Array of Strings: Any jQuery selectors
        // The element's used to generate the table of contents.  The order is very important since it will determine the table of content's nesting structure
        selectors: "h1, h2, h3",

        // **showAndHide**: Accepts a boolean: true or false
        // Used to determine if elements should be shown and hidden
        showAndHide: true,

        // **showEffect**: Accepts String: "none", "fadeIn", "show", or "slideDown"
        // Used to display any of the table of contents nested items
        showEffect: "slideDown",

        // **showEffectSpeed**: Accepts Number (milliseconds) or String: "slow", "medium", or "fast"
        // The time duration of the show animation
        showEffectSpeed: "medium",

        // **hideEffect**: Accepts String: "none", "fadeOut", "hide", or "slideUp"
        // Used to hide any of the table of contents nested items
        hideEffect: "slideUp",

        // **hideEffectSpeed**: Accepts Number (milliseconds) or String: "slow", "medium", or "fast"
        // The time duration of the hide animation
        hideEffectSpeed: "medium",

        // **smoothScroll**: Accepts a boolean: true or false
        // Determines if a jQuery animation should be used to scroll to specific table of contents items on the page
        smoothScroll: true,

        // **smoothScrollSpeed**: Accepts Number (milliseconds) or String: "slow", "medium", or "fast"
        // The time duration of the smoothScroll animation
        smoothScrollSpeed: "medium",

        // **scrollTo**: Accepts Number (pixels)
        // The amount of space between the top of page and the selected table of contents item after the page has been scrolled
        scrollTo: 0,

        // **showAndHideOnScroll**: Accepts a boolean: true or false
        // Determines if table of contents nested items should be shown and hidden while scrolling
        showAndHideOnScroll: true,

        // **highlightOnScroll**: Accepts a boolean: true or false
        // Determines if table of contents nested items should be highlighted (set to a different color) while scrolling
        highlightOnScroll: true,

        // **highlightOffset**: Accepts a number
        // The offset distance in pixels to trigger the next active table of contents item
        highlightOffset: 40,

        // **theme**: Accepts a string: "bootstrap", "jqueryui", or "none"
        // Determines if Twitter Bootstrap, jQueryUI, or Tocify classes should be added to the table of contents
        theme: "bootstrap",

        // **extendPage**: Accepts a boolean: true or false
        // If a user scrolls to the bottom of the page and the page is not tall enough to scroll to the last table of contents item, then the page height is increased
        extendPage: true,

        // **extendPageOffset**: Accepts a number: pixels
        // How close to the bottom of the page a user must scroll before the page is extended
        extendPageOffset: 100,

        // **history**: Accepts a boolean: true or false
        // Adds a hash to the page url to maintain history
        history: true,

        // **scrollHistory**: Accepts a boolean: true or false
        // Adds a hash to the page url, to maintain history, when scrolling to a TOC item
        scrollHistory: false,

        // **hashGenerator**: How the hash value (the anchor segment of the URL, following the
        // # character) will be generated.
        //
        // "compact" (default) - #CompressesEverythingTogether
        // "pretty" - #looks-like-a-nice-url-and-is-easily-readable
        // function(text, element){} - Your own hash generation function that accepts the text as an
        // argument, and returns the hash value.
        hashGenerator: "compact",

        // **highlightDefault**: Accepts a boolean: true or false
        // Set's the first TOC item as active if no other TOC item is active.
        highlightDefault: true

      },

      // _Create
      // -------
      //      Constructs the plugin.  Only called once.
      _create: function() {

        var self = this;

        self.extendPageScroll = true;

        // Internal array that keeps track of all TOC items (Helps to recognize if there are duplicate TOC item strings)
        self.items = [];

        // Generates the HTML for the dynamic table of contents
        self._generateToc();

        // Adds CSS classes to the newly generated table of contents HTML
        self._addCSSClasses();

        self.webkit = (function() {

          for (var prop in window) {

            if (prop) {

              if (prop.toLowerCase().indexOf("webkit") !== -1) {

                return true;

              }

            }

          }

          return false;

        }());

        // Adds jQuery event handlers to the newly generated table of contents
        self._setEventHandlers();

        // Binding to the Window load event to make sure the correct scrollTop is calculated
        $(window).on("load", function() {

          // Sets the active TOC item
          self._setActiveElement(true);

          // Once all animations on the page are complete, this callback function will be called
          $("html, body").promise().done(function() {

            setTimeout(function() {

              self.extendPageScroll = false;

            }, 0);

          });

        });

      },

      // _generateToc
      // ------------