Loading...
 
Features / Usability

Features / Usability


Automatic Table of Contents Generation for All Wiki Pages (Maketoc on WYSIWYG pages Alternative)

posts: 19

Hey all,

Not sure if this is the best place to put this, but I figured I'd dump it for the world.

I wrote some javascript which automatically generates a table of contents for the headers on wiki pages (works tiki 9-11, should continue to work) and adds them to all wiki pages. Its generated via javascript, so you don't call it in your pages, but it will just add itself when the page loads (unless you tell it not to for a specific page).

It creates two table of contents, one which sits at the top of the page, and another which scrolls down with you and you can expand via mouseover.

Works well for both WYSIWYG and Tiki Editor pages, so you don't have to worry about maketoc not working for WYSIWYG. Designed to work for my environment, but should work well for others.

You can disable on a page by page basis if you want.

Lots of notes on how to implement and use in the script itself, but it involves adding a few lines of CSS to your theme.css and adding an entry to tiki-setup.php. Really easy to get running.

I hope someone finds it useful! (my first js :)

keywords: maketoc wysiwyg, tiki wiki table of contents, wysiwyg table of contents

EDIT: Updated Script so toc doesn't show up when printing a page though tiki-print.php (meaning you have print enabled for pages, and you click the print icon at the top of page to get to the print view). Grab autoToc_081513.js for this functionality.

EDIT: Fixed IE bug. New version is autoToc_092413.js

posts: 19

Here is my jsfiddle of it if you want to check out the functionality, though it does not look very good, as its a testing environment.

I'd grab the js file attached above if you want to try to test it out, as the one in the fiddle may get fiddled with and the comments in the attached one are for general application and not specific to my environment.


posts: 26 United States

Hey jcarter;

Sounds pretty cool. I'll give it a try. Thx.

RobertR


posts: 222 Norway

Hi,

I gave it a try and this is really nice functionality.

It has the same problem as the regular Tiki TOC when it comes to tags (e.g. underlined text) inside headers. Such headers are not parsed in the regular TOC. Here the autoTOC seems to completely disappear if such headers are present.

I suggest that you add this to trunk.

posts: 19

Hmm, that is strange. I either don't understand you correctly or I can't replicate the issue.

You mean that if the HTML for the header has embedded tags the toc does not load? So headers that are bold, underlined, etc, would fail because you get those multiple levels of embedded HTML?

I've attached a screenshot of header that has been underlined, and the toc generated for it (even keeps the formatting on the text for the anchor).

At the bottom of the screenshot, you can see the header (underlined in editor, red bc of css), and above it the toc is generating just fine.

Could be weirdness with tiki version? I haven't tried in IE, but mine works for formatted headers in Safari, Chrome, and FF.

posts: 222 Norway

I have integrated the code into Tiki trunk (i.e. the future Tiki 12). See: http://sourceforge.net/p/tikiwiki/code/47185

Thank's for your approval to this integration on email.

To activate the feature, go to Admin / Wiki / Features.
At the bottom, activate "Wiki Auto-TOC".

Thank's again for this very nice functionality.

Arild


posts: 1550 Canada

Congrats!

  1. Makes sense to do it client-side.
  2. Makes sense that same code and output can be for wiki & WYSIWYG


Please check out the other existing libraries such as the ones list at Maketoc to check which one makes most sense in the long term.

FYI, Tiki 13 is moving to Bootstrap so jquery.tocify.js may be of value:

jquery.tocify.js: A jQuery Table of Contents plugin that can be themed with Twitter Bootstrap or jQueryUI.
https://github.com/gfranko/jquery.tocify.js

And you are warmly welcomed to commit directly to trunk : How to get commit access

Best regards,

M ;-)


posts: 1550 Canada

Some feedback:

I see this can solve some issues of PluginMakeToc like we have here: http://dev.tiki.org/Articles

1- Can it made to be good enough to replace PluginMakeToc rendering?

2- There is text snippet "Table of Contents". I suggest to remove that as it just pollutes the search index, and visually, it should be clear it's a toc.

Thanks!

posts: 19

1- I think for it to be made uber beautiful, it would have to somehow be able to be enabled/disabled on a per-page basis via the page properties tab when editing a page. Currently, you have to insert a "toc-off" module (containing a div with id="toc-off"), or use the html plugin to add the toc-off div.

That is at least, what I think would be the most user friendly solution, though I wouldn't know how to approach implementing it. (Can js resources be turned on and off on a per page basis via page property? If so, we could have a more elegant solution than having the script search for a toc-off div, and it can simply be called when needed.)

Other than that, I have been using a variant of this script on a wiki for the last year+, and this script on a different wiki for the last month or so (this one is much better and easier to implement) to overcome the limitation of maketoc being restricted to the tiki editor.

Because I have non-technical users using the wiki, they are not required to use the tiki editor, and most favor WYSIWYG. As such, we don't use maketoc at all, and this script is necessary for the toc functionality. Therefore, for our purposes the autoToc is "better" than maketoc. This would not necessarily be the case for a technical community however, where maketoc works just fine, as people use the tiki editor.

I am not aware of any limitations of this script, though I'm not sure how efficient it is resource wise, as it is really the first piece of js that I have written from scratch. I don't think its too bad though.

The only possible performance issue comes from the following. Currently, the WYWIWYG does not write ids for the headers it generates like the tiki editor does. If this problem was remedied, then this script could be much more efficient, as it could use the preset ids of the header elements for the anchors it generates. As it is, it walks over the header elements and sets ids for them to compensate for the WYWIWYG's failure/inability to set them, so that anchors can point to them.

However, I'm not really sure if setting Ids this way is really a problem, though working with DOM is a bit slow. In any case, it is a necessary evil to get any toc working with WYWIWYG headers. Also, I'm not sure if the WYWIWYG editor will ever set its own Ids, as this may not be something the CK Editor people even see this as a necessary functionality.

2- Regarding the "Table of Contents" snippet, thats a good suggestion, and I think it looks nice (I implemented that on my local version). It also helps disambiguate this autoToc vs the structure toc. I'm going to see if I can get commit access soon, and I can make the change.

As for the pollution of the search index, if I understand you correctly, then you are saying that the text would show up when searching for a page? The div containing that text is inserted along with the toc when the page loads, so unless the index is generated from loaded pages, and not page content in DB, then I doubt we'd have that problem, but the point is moot as I think its a good idea just to get rid of it :-)

posts: 222 Norway

Hi again,

I added a couple of new features to autoToc, when integrating it into Tiki.

  • AutoTOC is an option, and has some sub-options
    • Displaying the static, inline TOC
    • Static, inline TOC placement: top, left or right

  • AutoTOC can be turned off on a per page basis (in page properties)


See http://dev.tiki.org/auto%20toc

I have not found any bugs in AutoTOC, and it handles many cases where maetoc fails. The ease of use is another.

I hope you will like the additions made during the integration.

Thanks again

Arild

posts: 19

I just checked it out, and it looks great! You definitely took it where it needed to go!

edit: Any objections to removing the "Table of Contents" string in the inline toc?

posts: 222 Norway

I have removed the Table of Contents text in the code.
Better without.

Also a bug fix: Wild /a and p were removed along with the string

posts: 19
Thanks! And thanks for that cleanup as well.
posts: 19

Looking at makeToc it is notable that makeToc is more flexible on a per-toc-instance basis, meaning that each toc you implement can have different parameters, while with autoToc is more sweeping, applying the same type of toc across all pages.

I guess it depends on if people are utilizing this flexibility of maketoc, and if this lack of instance based fexiblity with autoToc would be a blow to functionality that users are used to.

Its hard for me to tell if this should replace makeToc, as makeToc works fine for tiki editor. A better approach might be to make makeToc work with tiki editor?

For my purposes though, the automatic addition of toc to pages, without need to add any syntax, works perfectly, but others may need the flexibility of makeToc.

I assume you all don't like redundant features though, and would want to chose one or the other? Each method of implementation I think would appeal to different types of wiki buids/users, and some people might want to configure tocs on a per page basis, while others might want to just turn em on and go.

posts: 1550 Canada

About "redundant features": if they offer something different, it's OK to keep, but if we can reduce code maintenance and be more future-proof, that's even better.

I like the fact that there is a global setting and override page by page (either via wiki syntax or a property)

So let's start using what we now have and see how it goes in the future.

Congrats to you & Arild for making this better!

M ;-)


posts: 2

I implemented your autotoc in tiki 9. it works fine with mozilla, chrome and i.e. 9.
unfortunatly not with i.e. 10
the autotoc then puts out:

Table of Contents
function item() { native code } function item() { native code } function item() { native code } function item() { native code } function item() { native code } function item() { native code } function item() { native code } function item() { native code }

Java Script is on.

Do you have any idea, what the problem is?

posts: 19
I do actually. Arild let me know that was going on, and I fixed it, but I forgot to update this post--I was working on committing to trunk. Thanks for the poke! I'll update it tomorrow afternoon. If you want to DIY, or are curious about the cause, you just need to change the variable "item" to be called something different (e.g., "itm"). There are 4-5 instances in script? I'm not sure why it happens, but it seems like js in IE has the keyword "item" reserved or something.
posts: 222 Norway
A perfect first commit thing ;-)

posts: 2
great that works. Thanks smile
posts: 19
No problem. I attached an updated script to the main post.
posts: 222 Norway

I took the liberty of integrated the latest version into Tiki.

Changes from posted file

1) Got rid of leading spaces. Should use tabs in Tiki source files

2) Added a couple contenteditable=false, which is required to "play with" inline editing.

Thanks again for this great piece of software.


Page: 1/2  [Next]