12 Replies Latest reply on Feb 6, 2008 5:11 PM by dawn

    Adding a TOC to document pages

      I am used to MediaWiki and the ability to have a TOC at the start of a longer document with headers automatically leading to a Table of Contents section that can be used for navigation.

       

      Atlassian Confluence provides a toc macro for this purpose.

       

      How/can I do a TOC section for a clearspace document?

       

      Jim

        • Re: Adding a TOC to document pages

          Hey Jim,

           

          This is a great idea! If you're inclined, you could write a macro that looks for heading styles inside the document that contains it, then builds a hierarchy based on the heading levels. Hm... actually, it's more involved than that because the Clearspace wiki documents don't yet include an anchor for each heading.

           

          I made a brief run at this a while back before I was waylayed by documentation needs. I'll still do it (unless you do), but perhaps not soon. If you're interested, you might start by looking at the EmbedContent Macro macro, which includes code that inspects the contents of a document to look for macro markup. That code is in an action plugin, but you might be able to use it in a macro class instead.

           

          Steve

            • Re: Adding a TOC to document pages

              I was trying to do something like this as well, but maybe I was going about it wrong.  I was thinking that I would look through the contents of the document for headers (say, for example, h1, h2, etc), and then extract the content of those headers to build a toc list.  The problem I had was whenever I tried to get the body of the doc (whether with macroContext.getContentObject().getBody() or macroContext.getJiveContext().getDocumentManager(). getDocument(macroContext.getContentObject().getID()) ), I would always see a stack overflow error because it seems to be recursively pulling in the body.  Is there another way I should be trying to access this information?  Related, all the examples seem to be using the plugin.xsd v. 1_1, but one appeared to use 1_4, which seems to extend BaseMacro instead of implementing Macro.  While this newer way seems to make more sense, and provide richer functionality, I could not get it working, and the documentation was spotty at best.

                • Re: Adding a TOC to document pages

                  Thanks for the comment. Can you tell me a bit more about what was missing from the documentation? It would be great to have specifics to go on as I add content.

                   

                  I'm not sure what's going on with your stack overflow. Did you try using the EmbedContent macro as an example for pulling in document content? Its plugin.xml is based on the 1_4 schema and its macro class implements Macro. Note that code for examining the document's contents is in the EmbeddedDocAction class that's also part of that sample.

                   

                  Steve

                    • Re: Adding a TOC to document pages

                       

                      Steve, wow, thanks for replying on a sunday!  To answer your last question first, yes I did attempt to use the same way as you did in the EmbedContent macro to pull in the body.  However, the problem seems to pop up because I am trying to get the body for the document I am in.  The embedder is not a problem because it references a different document than you are calling it from (at least that is how is appears to me).  My theory is that because I am trying to pull in the same document, somehow the macro's render method is being called multiple times (I can tell becuase when I put a breakpoint on my call to 'getBody', it happens many times, which is what triggers the stackoverflow. 

                       

                       

                      As far as what is confusing about the documentation, here is an example or two.  While this is not strictly speaking documentation, it is confusing that in EmbedContent, while the plugin.xml uses the 1_4 schema, the Macro class itself implements Macro rather than extending BaseMacro as the schema (here: http://www.jivesoftware.com/schemas/clearspace/1_4/plugin.xsd) says is required for a class in the macro element.  Is the published schema incorrect, or am I misreading something?  Also, in the clearspacedevkit.zip (not 1.5 or 1.6, just regular), the helloworld macro uses the 1_1 schema and the macro extends BaseMacro.  All of the actual example docs I have found implement Macro instead, and I see no docs showing how to use BaseMacro or BaseFilter (other than the API itelf). 

                       

                       

                      Anyway, these are minor points, the main the is driving me crazy is the recursing happening when I try to get the body of my current doc.  I can clean it up and attach the code if you would find that more helpful, but really all I am doing is calling getBody, then trying to return it (or a small part of it) with the render method so I can see that I got it succefully so I can start deciding how I want to parse info out of it.

                       

                       

                       

                       

                       

                      -j

                       

                       

                        • Re: Adding a TOC to document pages

                          Thanks for the feedback, J. I think you've found a bug in our schema documentation. I'll look at fixing that for the next release.

                           

                          As for the code, I'd definitely like to see it. As I've mentioned, getting a working TOC macro is something I'd very much like to see personally. Please attach the code if you like. I can't guarantee anything, but sometimes another pair of eyes can be handy.

                           

                          Steve

                  • Re: Adding a TOC to document pages

                    hi Jim,

                     

                    TOC is coming in 1.8, which is a little more than 3 weeks away. It's being developed as a plugin, so there's a chance it may even land here before 1.8 lands.

                     

                    Cheers,

                     

                    AJ

                    • Re: Adding a TOC to document pages

                      One way that we worked around this was to do manual anchor tags href/name for some of our most popular documents that were very long.  The option to create a TOC in a document via a plugin will be a great way to get MediaWiki people to convert.