Creating neat automatic scroll-spying table of contents with tocify

Hi!

Today I want to write about my experience with jquery.tocify.js. If you have seen my projects page, you will have noticed that on the left side of the page, there is a table of contents or menu that allows you to jump to a specific section. Additionally, the currently selected section changes as you scroll down. I accomplished this effect with tocify, and today I will show you how!

Download tocify and extract it somewhere. The files you need are in src/javascripts and src/stylesheets. Personally, I moved these files to assets/css and assets/js accordingly, but it’s up to you to place them wherever you want.
You also need to download jquery and jquery UI. You can optionally use twitter bootstrap to style the table of contents.

Now that you have all the files you need, it’s time to do the work! Put the stylesheet files in the

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

I am using bootstrap here, although it’s optional, to enhance the page design.

And put the scripts at the end of your page, right before </body> (again replace the path):

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

Now we can finally create our page and it’s table of contents. Tocify needs a div with a unique id or classname, which itself needs to have a parent (other than our page body). What I did was make a <div class="row"> and use a <div class="span3"> for my table of contents and a <div class="span9"> for my page content. Have a look at my bootstrap blog post or the bootstrap documentation about what these things mean.

<div class="row">
    <div class="span3" >
         <!-- Our table of contents will be here !-->
         <div id="nav"></div>
    </div>
    <div class="span9">
         <!-- Your page content as normal, using headings.
              Tocify will automatically create 
              the table of contents from your headings
         !--->
         <h1>Students</h1>
                
         <h1>First year</h1>
         <h2>Computing and Engineering</h2>
         <p>
             <ul>
                 <li>Robert Tables Jr.</li>
                 <li>John Doe</li>
                 <li>Cynthia Mendez</li>
             </ul>
         </p>
    </div> <!-- .span9 !-->
</div> <!-- .row !-->

To make tocify work all you need is a bit of:

<script>
    $("#nav").tocify();
</script>

(You would place this code right before </body>, after you have loaded all the needed javascript files)

Of course, tocify only makes sense if you have quite a bit of content, so ideally you would replace the code i gave for my .span9 with your own, longer content.

If you did it right, You should see something like this (click to enlarge):

As you scroll down, or click on one of the headings, you will see that they expand to show sub-headings:

However, you probably want your table of contents to stick when people scroll down. To do this, you need to write a bit of your own CSS.
Let’s add a new CSS file to the head of the page:

<link type="text/css" rel="stylesheet"
href="assets/css/style.css" />

Create that file, and do something like this:

#nav {
     position: fixed;
}

That’s all it takes! The table of contents will now follow you as you scroll!

Of course, the $(element).tocify() function can take an optional parameter, a javascript object with options. The options API is documented over at the tocify website.

The option that I have used in my projects page was showAndHide: false. What this does is show all the headers from the beginning, rather than expand and collapse them. I personally prefer this as it makes it easier for the user to know what’s going on and to be able to jump to a section, but it’s up to you and your specific needs.

If you want to do this, just change

<script>
    $("#nav").tocify();
</script>

to this:

<script>
$("#nav").tocify({
    showAndHide: false
});
</script>

And your table of contents will always be expanded!

The one caveat of tocify is that it requires javascript to work. You may want to replace tocify with another table of contents if javascript is disabled. I recommend something like this (twitter bootstrap is required).
(You would put this under your #nav, inside your .span3)

<noscript>
<ul class='affix'>
    <li class="nav-header">Jump to a section</li>
    <li class="active">
        <a href="#uni">University work</a>
        <ul class="nav nav-list" >
            <li>
                <a href="#webprog">Web programming</a>
            </li>
            <li>
                <a href="#flash">Flash</a>
            </li>
            <li>
                <a href="#db">Database</a>
            </li>
            <li>
                <a href="#group">Group Project</a>
            </li>
            <li>
                <a href="#design">Visual Design</a>
            </li>
        </ul>
    </li>
</ul>
</noscript>

Which is what I did on my projects page. Not as cool, but still looks good. And it needs adjusting to your content, of course!

Well, that’s all for now. I hope this was helpful! Once again, head over to tocify website for the docs or my website for a live demo!