Tocify by Greg Franko

# Tocify

## Description

The project is hosted on Github, and the annotated source code is available. Tocify is available for use under the MIT software license. You can report bugs and discuss features on the GitHub issues page, or send tweets to @gregfranko.

Fork on Github »

## Requirements

jQuery 1.7.2+ (It is always recommended to use the latest version of jQuery)
jQueryUI Widget Factory 1.8.21+ (It is always recommended to use the latest version of the jQueryUI Widget Factory)

## Optional Dependencies

Twitter Bootstrap or jQueryUI CSS Theme
Note: A Twitter Bootstrap or jQueryUI theme is only required if you want to use either framework to style your table of contents.

## Notable Features

Supports forward and back button support
Supports styling with Twitter Bootstrap or jQueryUI Themeroller
Supports show/hide animations with jQuery effects
Supports smooth scrolling animations
Supports dynamic scroll highlighting
Supports dynamic scroll show/hide effects
Supports page extender option to make sure a page is big enough to scroll to all table of content items

## Browser Support

Tested in IE7+, Firefox 4+, Chrome, Safari 4+, and Opera 11+

## Getting Started

### Downloads

Download the latest versions of...

1. jQuery
2. jQueryUI Widget Factory (You only need the Widget component underneath the UI Core dependency)
3. Tocify (You only need jquery.tocify.js and jquery.tocify.css)
4. Twitter Bootstrap or jQueryUI CSS Theme (Only required if you want to use either framework to style your table of contents)

### Include CSS and JavaScript files

CSS

                    <link type="text/css" rel="stylesheet" href="jquery.tocify.css" />
                    <link type="text/css" rel="stylesheet" href="bootstrap.css" />

JavaScript

                    <script src="jquery-1.7.2.min.js"></script>
                    <script src="jquery-ui-1.9.1.custom.min.js"></script>
                    <script src="jquery.tocify.min.js""></script>

Note: This assumes that you have downloaded the CSS and JavaScript files to the same folder as your HTML page. Modify the href and src attributes if you have a different folder structure.
Also, if you are using jQueryUI to style your table of contents list, then add all of the jQueryUI images to your images folder. Keep in mind that depending on your folder structure, you may need to update the image paths inside of the jQueryUI CSS file.

### HTML

Create a div element with a unique id or class (eg. "toc")

                    <div id="toc"></div>

### CSS

Note: Modify the Tocify CSS file to fit your custom needs

### JavaScript

Call the plugin: In your JavaScript code, call the tocify() method on your HTML div.

                  //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
                  $(function() {
                      //Calls the tocify method on your HTML div.
                      $("#toc").tocify();
                  });

## Options API

### Options

Name | Type | Default | Options
--- | --- | --- | ---
context | String | "body" | Any valid jQuery selector
selectors | String | "h1,h2,h3" | Each comma separated selector must be a header element.
showAndHide | Boolean | true | true or false
showEffect | String | "slideDown" | "none", "fadeIn", "show", or "slideDown", or any of the other jQuery show effects
showEffectSpeed | String or Number | "medium" | "slow", "medium", "fast", or any numeric number (milliseconds)
hideEffect | String | "none" | "none", "fadeOut", "hide", "slideUp", or any of the jQuery hide effects
hideEffectSpeed | String or Number | "medium" | "slow", "medium", "fast", or any numeric number (milliseconds)
smoothScroll | Boolean | true | true or false
smoothScrollSpeed | Number or String | "medium" | Accepts Number (milliseconds) or String: "slow", "medium", or "fast"
scrollTo | Number | 0 | Accepts any number (pixels)
showAndHideOnScroll | Boolean | true | true or false
highlightOnScroll | Boolean | true | true or false
highlightOffset | Number | 40 | Accepts any number (pixels)
theme | String | "twitterBootstrap" | "twitterBootstrap", "jqueryUI", or "none"
extendPage | Boolean | true | true or false
extendPageOffset | Number | 100 | Any number (pixels)
history | Boolean | true | true or false
hashGenerator | String or Function | "compact" | "compact", "pretty", function(text, element){}. Compact - #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.
highlightDefault | Boolean | true | true or false

### Setting Options

All options can be set when the plugin is called. Certain options can also be set after the plugin is called using the setOption() or setOptions() methods.

Here is an example of setting a single option when the plugin is first invoked:

                  //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
                  $(function() {
                      // Calls the selectBoxIt method on your HTML select box and updates the showEffect option
                      var toc = $("#toc").tocify({ showEffect: "fadeIn" });
                  });

Here is an example of setting a single option after the plugin is first invoked using the setOption method:

                  //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
                  $(function() {
                      // Calls the selectBoxIt method on your HTML select box
                      var toc = $("#toc").tocify().data("toc-tocify");

                      // Sets the smoothScroll option to false
                      toc.setOption("showEffect", "fadeIn");

                  });

Here is an example of setting a multiple options after the plugin is first invoked using the setOptions method:

                  //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
                  $(function() {
                      // Calls the selectBoxIt method on your HTML select box and updates the showEffect option
                      var toc = $("#toc").tocify().data("toc-tocify");

                      // Sets the showEffect, scrollTo, and smoothScroll options
                      toc.setOptions({ showEffect: "fadeIn", scrollTo: 50, smoothScroll: false });

                  });

### Getting Options

A single option can be retrieved by using the option() method. All of the current options can be retrieved by referencing the options property.

Here is an example of retrieving a single option after the plugin is called using the option() method:

                  //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
                  $(function() {
                      //Calls the tocify method on your HTML div
                      var toc = $("#toc").tocify().data("toc-tocify");

                      // Writes the showEffect option to the console
                      console.log(toc.option("showEffect"));
                  });

Here is an example of retrieving all current options after the plugin is called using the options property:

                  //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
                  $(function() {
                      //Calls the selectBoxIt method on your HTML select box
                      var toc = $("#toc").tocify().data("toc-tocify");

                      // Writes all of the current plugin options to the console
                      console.log(toc.options);
                  });

## Inspired By

### Can.js

### JavaScript Garden

## Donation

If you would like to support the Tocify project, please consider sending a donation to Greg Franko (the project maintainer). All donations (small or large) are appreciated and help the continued development of the project.