GithubHelp home page GithubHelp logo

gfranko / jquery.tocify.js Goto Github PK

View Code? Open in Web Editor NEW
928.0 928.0 217.0 759 KB

A jQuery Table of Contents plugin that can be themed with Twitter Bootstrap or jQueryUI.

Home Page: http://gregfranko.com/jquery.tocify.js/

License: MIT License

JavaScript 91.71% CSS 2.66% HTML 5.63%

jquery.tocify.js's Introduction

jquery.tocify.js - jQuery Table of Contents

Note: I haven't had time to maintain this repository for the last few years, so if anyone would like a particular fix just send me a tip via Paypal ([email protected]) and I'll look into it

A jQuery plugin that dynamically generates a table of contents. Tocify can be optionally styled with Twitter Bootstrap or jQueryUI Themeroller, and optionally animated with jQuery show/hide effects. Tocify also optionally provides support for smooth scrolling, scroll highlighting, scroll page extending, and forward and back button support.

Homepage

Annotated Source Code

Notable Features

  • Themeable with Twitter Bootstrap or jQueryUI Themeroller

  • Supports dynamic scroll and click jQuery show/hide effects

  • Supports forward and back button support

  • Supports smooth scrolling animations

  • Supports dynamic scroll highlighting

  • Supports a page extender option to make sure a page is big enough to scroll to all table of content items

  • Passes jsHint with no errors

##Requirements jQuery 1.7.2+

jQueryUI Widget Factory 1.8.21+

##Browser Support IE7+, Firefox 4+, Chrome, Safari 4+, and Opera 11+

##Unit Tests All unit tests are written using the Jasmine Framework (Work in Progress)

##Contributing Take care to maintain the existing coding style. Add Jasmine unit tests for any new or changed functionality. Lint and test your code using grunt.

If you plan to contribute to Tocify in the future, keep in mind that you should make sure your code passes the Grunt checks. If you are on Windows (like me) remember you need to run the grunt command using grunt.cmd. Also, if you have trouble getting the Jasmine Unit Tests to work with PhantomJS 1.5 (the current release), install PhantomJS 1.3.

After you have verified your code, send a pull request to the Tocify dev branch. After you send a pull request, you will hear back from me shortly after I review your code.

You'll find source code in the "src" subdirectory!

##Forking If you find that you need a feature that Tocify does not currently support, either let me know via the Tocify issue tracker, or fork Tocify on Github and easily extend it to create your own widget!

###Contributors

##Change Log

1.9.0 - October 1, 2013

  • Fixed hash/history bug that threw a JavaScript error when the hash did not match an element on the page
  • Fixed bug that affected TOC items which contained special characters #45
  • Only register scroll event handlers if necessary #44
  • Improved the scrollHistory option #42

1.8.0 - September 16, 2013

  • Added the scrollHistory option #41
  • Fixed a non-linear nesting bug #40

1.7.0 - August 13, 2013

  • Improved the CSS class naming convention and implementation
  • Improved the CSS handling if no TOC items are found

1.6.0 - July 24, 2013

  • Updated the scrollTo option to accept a function #33
  • Improved scroll highlighting accuracy #33 #34 Special thanks to Andre Kampert for this improvement

1.5.0 - July 5, 2013

  • Added ignoreSelector option#27
  • Removed the bootstrap docs.css class names #30
  • Fixed a bug when there is only one selector #31

1.4.0 - April 6, 2013

**Special thanks to Joaquin Casares for helping with this release

  • Fixed colon-spaced hashes #22
  • Created solution for long menu's on smaller screens #19
  • Fixed scroll jump bug with extendPage option #20
  • Added the highlightDefault option #21
  • Fixed a TOC item nesting bug #23

1.3.0 - February 23, 2013

**Special thanks to Mat Ryer for helping with this release

  • Added the hashGenerator option
  • Fixed the pageload scroll bug #15

1.2.0 - December 31, 2012

1.1.0 - November 19, 2012

  • BREAKING CHANGE : Removed the History.js logic. All history logic is now using a hash bang instead of the HTML5 pushstate API.

  • Added the history option

1.0.0 - October 7, 2012

0.9.0 - October 3, 2012

  • Fixed another nested element show/hide bug

0.8.0 - September 26, 2012

0.7.0 - September 24, 2012

  • Fixed a nested element show/hide bug

0.6.0 - August 22, 2012

  • Nested subheader element bug fixes

  • Greatly improved showing/hiding deeply nested subheader elements

0.5.0 - August 21, 2012

  • Added support for Twitter Bootstrap Theming
  • Added the theme and extendPageOffset options.
  • Removed the jqueryUI option BREAKING CHANGE
  • Updated demo page to show off new Twitter Bootstrap theming

0.4.0 - August 19, 2012

  • Added the setOption and setOptions methods
  • Upgraded the CSS file
  • Updated demo page

0.3.0 - August 15, 2012

  • Added the showAndHide option.
  • Bug fixes for when the jQuery history.js plugin is not used
  • Upgraded the CSS file (removed unneccessary styles, etc.)
  • Upgraded to jQueryUI 1.8.23.
  • Upgraded to jQuery 1.8.0.
  • Upgraded demo page

0.2.0 - July 16, 2012

  • Added the scrollTo option. Upgraded to jQueryUI 1.8.21.
  • Multiple bug fixes.
  • Upgraded the project page (included in the demos folder) to use Twitter Bootstrap.
  • I will soon move the demo page into it's own separate project to create a boilerplate for documenting open source projects.

0.1.0 - July 12, 2012

  • Initial Tocify release. Added annotated source code and documentation

License

Copyright (c) 2012 Greg Franko
Licensed under the MIT license.

jquery.tocify.js's People

Contributors

fefrei avatar frohoff avatar gfranko avatar joaquincasares avatar kevinoconnor7 avatar linuxonrails avatar lord avatar nickl- avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

jquery.tocify.js's Issues

Go Back To Top link

Hello there. Would it be possible to have the option to add a link to the bottom of the contents list which navigates to the top of the webpage.

I know the user can click on the top contents item, but this doesn't take them to the very top of the web page, and also visitors are very used to seeing, and using, "Go back to top" links?

Thanks very much!

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Content Outlining Algorithm

This is related to issue number #36

I figured I'd start a new issue since the other one is "Old" and my comments there might be missed.

I was going to do a write up on what type of structure tocify expects and it turns out there's already an official spec for the algorithm that determines the document outline. The mozilla article sort of hints at it, but this makes it a lot more clear:

http://coding.smashingmagazine.com/2011/08/16/html5-and-the-document-outlining-algorithm/
http://developers.whatwg.org/sections.html#headings-and-sections

Do you think it's good enough to just reference this material?

Highlighting fails of highlights wrong item

There are two symptoms of a problem with highlighting:

Highlighting not updated

When scrolling larger pages really fast, sometimes the highlighting is not updated due to events being skipped. This is because for some reason we never get a position within the offset, so the update is skipped entirely (line 622)

javascript
if ((Math.abs($(this).offset().top - winScrollTop) < self.options.highlightOffset))

#### Highlight wrong item after clicking in toc

Sometimes, based on the structure of the page, another item is highlighted in the TOC, because after scrolling tocify consider an item on top within the highlightOffset. However, the item below is closer, so should be highlighted instead of the first item within the highlightOffset.
#### Proposed solution

Instead of the first element within the highlightOffset, use the one closest to the current position. I've made this improvement in a fork and will create a pull request.

JS-error when scrolling to the last header.

Hi, thank you for a nice plugin!

I'm getting this error:
"Uncaught Error: Syntax error, unrecognized expression: div[data-unique=B.5CodeTable(TEST_MEDIUM)]"

This happens in http://localhost/scripts/jquery-1.8.3.js on line 4680.
(But I'm assuming tocify attached the failing event or?)

When I scroll to the bottom of the page. (my last h1 is "B.5CodeTable(TEST_MEDIUM)")

Tried to reproduce on jsbin, but didn't manage, sorry.
Let me know if this isn't enough and I'll give reproducing it online another shot.

Edit: If I comment out this line(634), everything works fine:
self._scrollTo($("div[data-unique=" + currentElem.attr("data-unique") + "]"));

Maintain behavior if the toc is not visible

Hey!

I just updated the theme of a project which uses your lib & it seems the nested toc elements are not hidden properly if the toc is not visible.

My theme hides by default the toc & allows to show it by clicking on a button.

I have created a jsbin to reproduce the issue.

tocify uses classes from the bootstrap docs.css

Hi,

Thanks you for brilliant piece of work that the tocify plugin is. Also very impressed by the annotated source code.

The generated markup includes classes from the bootstrap docs.css file. Specifically bs-docs-side-bar for the "toc" container and bs-docs-side-nav for each toc item.

When the table of contents is rendered with these classes included, it looks very different from the original demo.

Thanks again,

  • Ole

Trouble using selectors option

Hi,

I have some documents I want to use tocify on. I'm having trouble to get tocify to use the elements I want. The document looks as follows:

div.section
    h1.title This is a chapter
    div.section
        h2.title This is a section
        div.activity
            h1.title This is an activity title
        div.section
            h3.title This is a subsection
    div.section
        h2.title This is another section

In which case the toc should look like:

1. This is a chapter
    1.1 This is a section
        1.1.1 This is a subsection
    1.2 This is another section

and the div.activity > h1 should be ignored.

I've tried to use the selectors option in various ways e.g.

selectors : "div.section>h1.title, div.section>h2.title, div.section>h3.title"

and

selectors : "h1#toc-id-0,h2#toc-id-1,h3#toc-id-2,h3#toc-id-3,h2#toc-id-4,h3#toc-id-5,h2#toc-id-6"

but it won't give the correct ToC. Can tocify do what I want? If not can you give me some pointers as to what I can do to add this functionality and send a pull request?

Subheader hiding

I had another issue in that this

self.hide($(".sub-header").not(elem.closest(".header").find(".sub-header")));

didn't work, as the subquery elem.closest(".header").find(".sub-header") again returned all elements in the TOC wherefore nothing was hidden.

When I changed it to

self.hide($(".sub-header").not(elem));

it worked.

Show/Hide with scroll & nested selectors

Hey!

It seems the show/hide behaviors fails with nested selectors & scroll. If I use this structure:

level 1
  level 1.1
    level 1.1.1
    level 1.1.2
  level 1.2
    level 1.2.1
    level 1.2.2
  level 1.3
    level 1.3.1
    level 1.3.2

When I scroll to the level 1, the lib works fine but when I scroll to the level 1.1, the level 1.2 and 1.3 show. It is the same if I scroll to level 1.2 or 1.3.

If I scroll to the level 1.1.1 the level 1.2 and 1.3 hide.

Thanks for reading :)

History not working with showAndHide to false

If showAndHide is set to false and one use a link with an anchor (for example http://gregfranko.com/jquery.tocify.js/#OptionsAPI ) the scrolling won't happen.

There is a specific test about it in the code:
https://github.com/gfranko/jquery.tocify.js/blob/master/src/javascripts/jquery.tocify.js#L322-L327
However I can't think of any case where this test is necessary.

Removing the condition fixes the problem.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Support for Twitter Bootstrap 3

Bootstrap 3 has some marvelous features that makes it the Bootstrap version to use for our web projects. Your Tocify plugin is marvelous as well, but it is not working on Bootstrap 3.

It would be wonderful if your plugin could be updated to the new Bootstrap version.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Enhancement request: Ensure URLs are still readable

Currently Tocify removes whitespace from headings in order to generate the hash values (i.e. the bookmark after the # in the URL), which is sensible. So "Tell me About It" becomes #TellmeAboutIt.

What if it replaced the spaces with hyphens - and made it all lowercase, so you would end up with #tell-me-about-it.

Pros:

  • Human readable and clearer
  • Prettier

Cons:

  • Existing links might be broken

Indentation break

Hi,

another bug :) I noticed that when having a structure like

<h1>
       <h3>
   <h2>
   <h2>

the indentation is broken. Here's the according JSBin sample.

Question: HashGenerator id instead of text

I'm trying to generate hash with hastags like "#feature-id-456".

<h2 id='feature-id-456'>Text 456</h2>

I've tried this

$(function() {
  $("#toc").tocify({
    hashGenerator: function(element) {
      return element.getAttribute('id');
    }
  });
});

But it throws an error: Uncaught TypeError: Object Тесты проекта billing has no method 'getAttribute'

Also I've tried element.id, but get error Uncaught TypeError: Cannot read property 'top' of undefined

How can I do this?

Wordpress page title causes error in tocify

I'm using tocify with Wordpress, and noticed that the page title that Wordpress renders is causing a bug with the TOC.

In order for the other headings to get rendered and displayed properly, I need to add another H1 to the top of the page...which isn't really ideal. If I don't add a second h1 tag, only the page title will display in the table of contents.

Has anyone else encountered this and/or have a workaround?

For what it's worth I'm using the Roots theme.

ToC incorrect nesting

3rd level nesting appears to be broken with the latest update.

Given the validating HTML that exists here: http://microcosm-cc.github.io/

And using Chrome v26 stable and Firefox v20 stable.

When one expands the Conventions ToC entry: http://microcosm-cc.github.io/#Conventions

The Conventions menu contains entries to /microcosms, /conversations, /events, etc... all of which exist in the API Reference section.

When one expands the API Reference ToC entry: http://microcosm-cc.github.io/#APIReference

All of the menu items render correctly.

However, when you click on /conversations http://microcosm-cc.github.io/#/conversations

The /site and /microcosms menu entries in the ToC below API Reference are removed. This is also true of each subsequent child menu in the ToC below API Reference, i.e. clicking /events removes the menu items preceding it.

The HTML shows that all of the /item links exist in the API Reference section only.

This updated version feels more broken than the prior version. Am happy to make a PayPal donation of £50 to sponsor a fix that allows the 4 level menu to work as expected (let me know your PayPal).

Tocify and Bootstrap

Why doesn't Tocify stay its assigned div? When I do the following it floats instead of staying in the div.

<div class="container">
  <div class="row">
    <div class="span3">
      <div id="toc"></div>
    </div>
    <div class="span9">
    </div>
  </div>
</div>

Not detecting headings in a-tags

I've got some html code from another system I have to render.

The html code has a certain structure which tocify can apparently not correctly analyse. Only the first heading is rendered in the toc. In the case I want tocify h1,h2,h3 I only see "Section 1 - H1" in the toc.
The problem seems to be that the headings are inside of a-tags.

<article>
            <section>
                <a name="section1_h1">
                <h1>Section 1 - H1</h1>
                </a>
                <section>
                    <a name="section11_h2">
                    <h2>Section 1.1 - H2</h2>
                    </a>
                    <section>
                        <a name="secton1_h3">
                        <h3>Section 1.1.1 - H3</h3>
                        </a>
                    </section>
                </section>
                </section>
        </article>

If I put the a-tags inside the headings everything's fine. But changing the html is out of my scope :-(

Is there a fix or workaround for this issue?

Thanks!

Feature request: Setting the page's fragment identifier automatically

Right now, when you scroll, the stuff after the # in the page's header doesn't change. It only changes when you click on a link in the ToC.

The option to set that automatically as you scroll would be a really nice feature — that way, on a long document, users can just copy the URL for that exact part of the page without worrying about clicking on the ToC first.

Awesome plugin by the way! Loving it!

Google Analytics Tracking on a Tocify item click

Hi,

I've been trying to get each click in the Tocify TOC to register as an event in Google Analytics but to no avail.

I've tried adding:

_gaq.push(['_setAllowAnchor', true]);

to the GA script block but it doesn't seem to make any difference.

I wonder if anybody knows how to do this.

Many thanks, Pete.

Responsive menu

Your plugin is very useful, but I have a suggestion for a feature.

When we make a responsive navbar, the navbar menu turns into a button on small devices, like shown in this video, for instance.
http://www.youtube.com/watch?v=qpWlaOeGZ_4

It would be cool if the data-target attribute for the button could refer to the generated tocify ul navlist (and equivalent for the Bootstrap 3 version).
Then we could use default Tocify menu for large screens and the button for small devices. That would be marvelous.

I guess this is a challenge, but I hope you like that!

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Highest level selector must be present

Thanks for your work on Tocify, it's been as extremely helpful tool.

I've noticed when I add selectors (ex. h2,h3,h4,h5) that the highest level must be present for Tocify to create the list. When I create a page, I obviously prefer for the headings to be organized properly....however when I turn the project over to the end user, they may (incorrectly) start the page off with h4. Currently if that happens Tocify will hide completely when I have h2 set as the first selector. Is there anything I can do on my end to prevent that, or is this unexpected behavior?

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Show/Hide with scroll to the top & nested selectors

Hey! There is a small issue with the show/hide behaviors. Take this structure:

level 1
  level 1.1
    level 1.1.1
    level 1.1.2
  level 1.2
    level 1.2.1
    level 1.2.2
  level 1.3
    level 1.3.1
    level 1.3.2
level 2

When I am on the level 2 and then, scroll to top, the level 1.1, 1.2 & 1.3 show.

Multiple sub menu items with the same string values results in undesirable URLs

Hello,

You can observe this error in the wild by going to the following URL and observing - http://dev.mendeley.com/slate/

  1. Scroll to Documents and observe the sub header entry of 'Retrieve a document' and observe the URL 'http://dev.mendeley.com/slate/#retrieving-documents'
  2. Scroll to Catalog and observe the same sub header entry of 'Retrieve a document' and observe the URL 'http://dev.mendeley.com/slate/#retrieving-documents16'

It seems having the same text more than once on the same page will result in undesirable URLs.

It would be desirable to be able to provide a desired URL or at least include the main resource and sub resource together in the final URL.

Tocify generates invalid HTML

The HTML generated by this plugin is not W3C compliant.

There are 2 issues:

  • Nested 'ul' tags when there are sub-menus. They could be replaced by 'div' or the sub-menu 'ul' be included in the parent 'li'
  • 'div' elements are added with a 'name' attribute inside the page

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Scrolling large TOC

Hello!

I'm testing the default.html included in 'demos' folder in this zip download.
I modified that file adding some "h2".

I found that the scroll doesn't work with the TOC when it is larger than the page height.

I don't know if I'm doing something wrong or if I have to change some option. I'm having 'extendPage: true' and 'extendPageOffset: true'.

Can you help me?

Thank you so much!

Nested selectors

Hey! First, thanks for your jQuery plugin! :)

I'm currently trying to integrate your lib into a build-in Sphinx documentation. All works fine except for nested selectors.

The context use by the plugin follow this structure:

<div id="context">
    <h1>First level title</h1>
    <div>
        <h2>Second level title</h2>
        <div>
            <h3>Third level title</h3>
        </div>
        <h2>Second level title</h2>
        <div>
            <h3>Third level title</h3>
        </div>
    </div>
    <h1>First level title</h1>
    <div>
        <h2>Second level title</h2>
        <div>
            <h3>Third level title</h3>
        </div>
    </div>
</div>

The javascript use in order to tocify the context is:

$(selector).tocify({
    "context":    "#context",
    "selectors":  "h1,h2,h3"
});

The TOC only shows h1.

It seems selectors are defined on the same level in the demo. I don't know if it is the reason of the issue. Anyway, is there a solution?

ToC incorrectly nested when 4 header selectors are used and headers jump a level

For the given HTML:

<h1>Depth 1</h1>
<h2>Depth 2</h2>
<h3>Depth 3</h3>
<h4>Depth 4</h4>
<h5>Depth 5</h5>
<h3>Depth 3</h3>
<h2>Depth 2</h2>

And ToCify configured thus:

var toc = $("#toc").tocify({ selectors: "h2, h3, h4, h5" }).data("toc-tocify");

The generated menu will incorrectly nest the second Depth 3 as a sibling to Depth 4, rather than as a sibling to Depth 3.

I believe in the unminised code the bug is on line 411, but I don't know how to fix it.

Feature Request: "Scooting" of ToC as Page Scrolls

It seems that if the table of contents is longer than the height of the page, it will have a scrollbar, so that works! But sometimes you'll scroll down on the main page, and the currently selected ToC item will be outside of the visible part of the ToC...it's still there, it's just hidden because the ToC div is scrolled above it. This means that sometimes you'll scroll down a ways and suddenly there will be no visibly selected ToC item, which can be confusing.

Dropbox has a solution: with Dropbox's API docs on a smallish browser window, if you scroll way down you can see that the scrolling table of contents on the left scrolls so that the currently active item is always visible when it is scrolled to.

If you'd like, I can make a small example that demonstrates the issue.

So yea, an option that automatically scrolls the table of contents (when necessary) so that a newly activated ToC item is always visible would be awesome!

Thanks again for the awesome plugin!

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

tocify reset the active class in navbar

When you have bootstrap with a navbar list and one element in this navbar is active (has 'active' class) tocify reset (remove) this class at init.

<nav class="navbar">
  <div class="navbar-inner">
    <div class="container">
      <ul class="nav">
      <li><a href="/alatriste/1">One</a></li>
      <li class="active"><a href="/alatriste/2">Two</li>
      <li><a href="/alatriste/3">Three</li>
      </ul>
    </div>
  </div>
</nav>

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.