SA Toc / Anchors Plugin

[shawn_a]

SA TOC / Anchors Plugin
Adds Table of Contents menus to pages

Version: 0.2

Compatibility: 3.0+

Plugin Type: Frontend

Description: Automatically adds IDs and titles to all headers and creates a anchor linked table of contents on the fly.


Features
[list=*]
[*]Dynamically inserts a Table of Contents navigation menu where you want it.[/*]
[/list]

Usage
Insert

Code:

(% sa_toc %)

in your page where you want the menu.
Visit website for all available options.

Changes:
Version 0.2
[list=*]
[*]Added compatibility for utf-8 content, multilanguage
[/*]
[/list]

Download from extend

[Oleg06]

in Russian text looks like this

Code:

ффффффффф
        ÃƒÂÃ‚µÃÂµÃÂµÃÂµÃÂµÃÂµÃÂµÃÂµÃÂµÃÂ​Ã‚µÃÂµÃÂµÃÂµÃÂµ
            ÃƒÂ‘€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€ÃÂ​‘€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€

[shawn_a]

Oleg06 wrote:in Russian text looks like this

Code:

ффффффффф
        ÃƒÂÃ‚µÃÂµÃÂµÃÂµÃÂµÃÂµÃÂµÃÂµÃÂµÃÂ​Ã‚µÃÂµÃÂµÃÂµÃÂµ
            ÃƒÂ‘€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€ÃÂ​‘€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€Ñ€

hmm, i was afraid of that. I am using DOMDocument(); which probably isnt utf-8 safe.
Let me see if i can fix it with the proper decode() function.

[shawn_a]

Oleg06 wrote:in Russian text looks like this

Does this look any better ?
http://tablatronix.com/utf-8-test/

Sorry I am using a russian lorem ipsum, not actual text.

[Oleg06]

yeah, looks good

[shawn_a]

Oleg06 wrote:yeah, looks good

Thanks, I will try to post a updated version soon, hopefully that will take care of all utf-8 issues.

[Oleg06]

your plugin is very useful when creating Single-page themes

[shawn_a]

Oleg06 wrote:your plugin is very useful when creating Single-page themes

I create many documentation pages. And always found this a useful feature in all the wikis I have used and ran.

[shawn_a]

Posted version 0.2, with utf-8 support. Let me know if any characters are still corrupting.

[ren!]

Hi Shawn,
I like your TOC PlugIn and wonder if there is a way to tweak it to:
- create a template tag and /or
- add an ID or Class to the top- <ul></ul> Element

With more and more Wiki pages it becomes a pain in the,.. fingers,... to allways add a ID or wrapper for CSS-styling
A template tag like: "get_TOC_anchor('PARAM=ID');" or sth. like that would be killer. as i'd loved to place the TOC somewhere near - and not within the content - without having to bother with css-positioning conflicts.

thx Ren

[shawn_a]

ren! wrote:Hi Shawn,
I like your TOC PlugIn and wonder if there is a way to tweak it to:
- create a template tag and /or
- add an ID or Class to the top- <ul></ul> Element

With more and more Wiki pages it becomes a pain in the,.. fingers,... to allways add a ID or wrapper for CSS-styling
A template tag like: "get_TOC_anchor('PARAM=ID');" or sth. like that would be killer. as i'd loved to place the TOC somewhere near - and not within the content - without having to bother with css-positioning conflicts.

thx Ren

I had a way to do this, let me see if I left it in after I rewrote some stuff.
I had this planned for next version, ability to call it for any slug, and call with no menu.

The problem, is that this plugin does 2 things.

1. It is a content filter, adds ids to all headings without them, so you can link to them, but only does so for pages with a menu. This is for optimization of course, we don't want to have to do this more than once or when its not needed.

2. It creates the menu based on the headings.

So the problem is, if you want to create a menu by function, it has to happen after the content filter runs or you can simply not use that feature of it. If calling by function, I could maybe set a global and do the filter manually, it will occur twice, but cant think of another way at the moment.

I can also add a wrapper or a class to the ul I guess, I don't typically like to do that with plugins, maybe I can make it a user parameter.

Ideas welcome.

[ren!]

Thanx for the explanation,

shawn_a wrote:So the problem is, if you want to create a menu by function, it has to happen after the content filter runs or you can simply not use that feature of it. If calling by function, I could maybe set a global and do the filter manually, it will occur twice, but cant think of another way at the moment.

Hm,.. I feared sth like this.

My complicated Idea would be:

1. Instead of adding the ID's when the page is displayed -
you could add the IDs on page-save and write the IDs into the page-content
2. create a new page-field (<TOCindex>) containing an object/multiarray with the headline IDs
and according h2-6 Tag on page save

This way the content filtered before it is called - the template function would only display the menu (or an array for further processing).

shawn_a wrote:I can also add a wrapper or a class to the ul I guess, I don't typically like to do that with plugins, maybe I can make it a user parameter.

Would be killer, sometimes ul's are used in the content to enumerate something which is not a menu ;-)

[shawn_a]

I have considered that, but I am not a fan of content modification before save, too complex, high risk on failure if something went wrong, corrupt content etc, plus there is no preview in GS, you wouldn't even know something went wrong until after save.

Maybe I can just optionally enable it always on all pages via something you call or declare in your theme before calling gettoc and getcontent functions.

Then you can call a function
sa_toc_useToc() at the earliest possible time.

Then you can call sa_toc_getToc() or getContent() anytime after.
I can also add a nomenu argument so you can trigger the id generation but not include menus in specific pages, say if you want to externally link to the anchors from somewhere else.

I can deal with caching the menu later on to avoid the double scan , but its super fast since I am using dom, so might be negligible.

[ren!]

shawn_a wrote:I have considered that, but I am not a fan of content modification before save, too complex, high risk on failure if something went wrong, corrupt content etc, plus there is no preview in GS, you wouldn't even know something went wrong until after save.

You're right

shawn_a wrote:Maybe I can just optionally enable it always on all pages via something you call or declare in your theme before calling gettoc and getcontent functions.

Then you can call a function
sa_toc_useToc() at the earliest possible time.

Then you can call sa_toc_getToc() or getContent() anytime after.

jep

shawn_a wrote:I can also add a nomenu argument so you can trigger the id generation but not include menus in specific pages, say if you want to externally link to the anchors from somewhere else.

hm,.. after calling "sa_toc_useToc()" the ID generation should allready be triggered
so if you don't want the menu just dont call "sa_toc_getToc()"

shawn_a wrote:I can deal with caching the menu later on to avoid the double scan , but its super fast since I am using dom, so might be negligible.

when you cache the menu in the pages XML - You can display the menu of page X in any page Y,Z - I would love that!

Maybe there is even a way to avoid the initial call for "sa_toc_useToc()" when there is a TOC-menu-cache in the XML.

My php vocabulary and grammar is pretty limited and I dont know if GS-Plugin-API Supports my thoughts

[shawn_a]

Ok well I got a pretty good idea of what your wanting, and I've had the same in mind. Let me see what I can come up with.

[surasshu]

Hey, great job on this plugin, I really like it! However, it seems like the options aren't working for me? I'm afraid I can't really elaborate beyond that, unless I'm really misunderstanding the "depth" option... I have (% sa_toc depth=0 %) in my code, but it's still showing H3 and H4 headers anyway. I also tried depth=1 and depth=2 (and depth=6), but it didn't seem to matter what I put, it always just rendered the whole tree.

Sorry if I'm doing something really obvious wrong, I'm pretty much an amateur. This page isn't public yet, but here's where I'm using it: http://surasshu-sound.com/services-portfolio/. Maybe you can give me a better clue as to what's going on there... Thank you!

[shawn_a]

surasshu wrote:Hey, great job on this plugin, I really like it! However, it seems like the options aren't working for me? I'm afraid I can't really elaborate beyond that, unless I'm really misunderstanding the "depth" option... I have (% sa_toc depth=0 %) in my code, but it's still showing H3 and H4 headers anyway. I also tried depth=1 and depth=2 (and depth=6), but it didn't seem to matter what I put, it always just rendered the whole tree.

Sorry if I'm doing something really obvious wrong, I'm pretty much an amateur. This page isn't public yet, but here's where I'm using it: http://surasshu-sound.com/services-portfolio/. Maybe you can give me a better clue as to what's going on there... Thank you!

Hmm I don't see anything wrong with the syntax.
Let me make sure it's working properly my page and get back.

[surasshu]

Awesome, thanks! Feel free to check out the CSS and everything, or let me know what I need to show you, if anything.

EDIT: For now I've removed the sub-headers from the layout since I wanted to get that page out there. Let me know if you need another test page or anything.

[shawn_a]

surasshu wrote:Awesome, thanks! Feel free to check out the CSS and everything, or let me know what I need to show you, if anything.

EDIT: For now I've removed the sub-headers from the layout since I wanted to get that page out there. Let me know if you need another test page or anything.

Can you give me the entire replacement string you are using. depth=0 is invalid also btw.

[shawn_a]

Works fine for me.
http://tablatronix.com/testing/toc/

[surasshu]

Is this the replacement string? Right now I'm just using (% sa_toc %). Before it was (% sa_toc depth=x %) which somehow didn't seem to change anything. I will try to test it a bit more, thanks for confirming that it works on your end.

[shawn_a]

surasshu wrote:Is this the replacement string? Right now I'm just using (% sa_toc %). Before it was (% sa_toc depth=x %) which somehow didn't seem to change anything. I will try to test it a bit more, thanks for confirming that it works on your end.

Yeah so...
(% sa_toc depth=3 %)
Would cause only h1 h2 and h3 to show in the menu.

[surasshu]

You may have to have a look at my CSS or something, cause I got that exact line and it's not doing it... Really sorry I can't help more, I'm super confused by this turn of events myself. http://surasshu-sound.com/test-page/

The text on this page is just

Code:

(% sa_toc depth=3 %)
<h1>Height1</h1>
<h2>Height2</h2>
<h3>Height3</h3>
<h4>Height4</h4>
<h5>Height5</h5>
<h6>Height6</h6>

[shawn_a]

surasshu wrote:You may have to have a look at my CSS or something, cause I got that exact line and it's not doing it... Really sorry I can't help more, I'm super confused by this turn of events myself. http://surasshu-sound.com/test-page/

The text on this page is just

Code:

(% sa_toc depth=3 %)
<h1>Height1</h1>
<h2>Height2</h2>
<h3>Height3</h3>
<h4>Height4</h4>
<h5>Height5</h5>
<h6>Height6</h6>

And what does the menu look like?

[surasshu]

The top blue-link thing with the #-style links is the toc-menu. As you can see it shows all 6 the titles despite having depth=3 in there.

EDIT: Tested a little more, it seems that none of the arguments I put in do anything. So my current guess is that it's getting filtered out by the theme or CSS somehow?