I was trying to clean some jira issues and we have several related to the concept of having some kind of auto toc in XWiki (ie an automatically-generated TOC somewhere, for each page, without needing to manually insert the TOC macro).
This thread is basically a respawn of Auto TOC in XWiki? (first try) but asked a bit differently.
Decisions
I’d like us to decide what we’d like to do and close the jira issues we don’t want to implement. I’ve listed several points below and am interested in your opinion for each line.
Do we need this feature in XWiki or is the manual TOC enough? ie should we close Loading... as won’t fix or not.
Assuming we want an auto toc in XWiki:
Should we provide it as a rendering transformation (with some configuration option similar to heading numbering to turn on/off), ie should we close Loading... as won’t fix or not.
Should we provide it as tree nodes inside the Document Tree macro (for perf reason, it would always be folded and when the user clicks an arrow to open it, leaf entries are generated for each heading. Note: we would need to render the document to have perfect results. Since the Navigation tree panel is visible on all pages, it would provide a way to quickly navigate to headings in documents.
Should we provide it as a TOC Panel, ie should we close Loading... as won’t fix or not?
Should we provide a UIXP somewhere (example in the following screenshot), folded by default and when clicked, it would display the TOC for the page:
I don’t remember being asked recently about such a feature so I’m tempted to say that we don’t want it in XWiki. Ofc everyone is free to do it in a contrib extension and we could even provide some new UIXP if one is missing. This means that I’d be in favor of closing all 3 jira issues referenced above as won’t fix.
No
Maybe, but I have a preference for 5 (which is located inside the page content and doesn’t require a new rendering)
I’m not a fan of ToC even if a page will have 5-6 headings 2nd level with subheadings. As long as the section text contains only a few meaningful paragraphs, I do not have difficulty navigating or searching for content. That’s why my personal preferences do not add (or even generate) ToC.
The use cases are quite obvious and they’re valid IMO. They’re listed in Loading... (consistency between location of TOCs in pages, not having to manually add a TOC macro on all pages).
The question I was asking was more whether we want to provide this feature or not by default in XS. Because each feature has a cost: implementation, documentation, maintenance, more complex software and thus reduced usability. For me the cons outweight the pros, to have it in XWiki/XS.
Said differently, this thread is about adding an ADR to decide that we don’t want to implement Auto TOC (ofc we can always change our mind in the future by creating a superseding ADR ;)).
Then when someone asks for it, we can point to this thread or the ADR (if we record it). Ofc anyone could implement it as a contrib extension, the ADR is just about having it in XWiki.
In my opinion an implementation with a Panel would have fairly low maintenance cost given that we already bundle the ToC macro AND a bunch of panels (most of which are less useful than a prospective ToC panel IMO). From what I know, maintenance cost of a panel is not that high.
customizable “easily” by admins (ease is relative, but I think it’s more straightforward than if we implement it with a rendering transformation)
Leaves space for the content of the page, easy for users to dismiss/overlook the content of the ToC if they don’t need it.
I can take responsibility of proposing this new panel in the next roadmap if we decide it’s worth it .
No opinion on my part, I’m not sure what part of the user base would use the ToC if it was included by default on every page (probably would depend on the design we use too )
No. I think it’s a too high level of abstraction for it to make sense in xwiki-rendering. At least heading numbering has an impact at the level of the heading itself. IMO the ToC is not content and handling it does not fall under the responsibility of xwiki-rendering.
No, those items are not documents so I don’t think they should be inside the document tree. (however an improvement to use an xwiki tree to display the ToC could be something, no strong opinion about it though)
IMO it’s one of the best options (see above)
I think we could achieve a very similar user experience with lower costs and tech debt by using a panel.
Thanks for bringing this discussion forward!
Lucas C.
Coming from DokuWiki, I like how it automatically displays a table of contents. The table of contents is not always present but only if there are at least a configurable number of headings in the page, by default this is 3.
Doing this as part of a transformation would have the advantage that it would be quite easy to also check if there is already a TOC in the page, and if yes, omit it. With the panel the problem is that you’ll have an additional TOC if there was already one in the page. Further, with the panel there is another problem: you’ll need to re-execute the macro transformations on the page to get a correct TOC. If the page contains any scripts that perform an action based on some URL parameter, this could be dangerous as the action would be performed twice.
So from my side:
+1, I think having a TOC automatically is nice.
+1, with global configuration options similar to DokuWiki, with overrides on the space/page level.
-0, I think this would clutter the tree too much. However, +1 to provide pickers for headings, e.g., for selecting a section in a link anchor or an include macro.
-0, I’m not totally against providing such a panel, but I think it could have important problems (see above).
-0, this has the same problems as the panel regarding executing transformations again.
The idea would be to modify the content vm to execute some optional
I don’t think it has the same problems as the idea here would be to modify the contentview.vm to execute some new uixp (right now there’s already the execution of the org.xwiki.platform.template.content.header.after uixp there). And since $renderedContent is available in that vm, it could be passed to the new uixp to extract HTML headings. If need be, we could even imagine passing the XDOM object (with macros executed) by modifying contentvars.vm to allow retrieving the final XDOM before its rendering to the target syntax.
PS: I agree with the issue for the Panel though, it’s mentioned in the jira for it and there were tries to implement it already.
I just created my first TOC in a panel in XWiki. I like this because it gives me a good overview of what exactly is on the page and where. I combined it with making the panel sticky so going through the different subjects on the page works really zippy.
I want to be absolutely forthright with you fellows, just so you know where I am coming from. See my experience as a fresh user input. My motto here: Honesty saves everyone a lot of time.
The thing that was challenging at first was: How do I create my own panel? I know I already did such a thing but that was a long time ago and I simply forgot how. So I looked around on the Global Admin Panels page but I could not find any word about “creating a panel.” After a quick internet search I saw that there was simply a page called ‘Panels’ and I could do my business there. A bit frustrated (and mumbling to myself why I could not find any reference to creating a panel) I searched for any reference to this page on the Global Admin Panels page and ultimately there it was, a link beside the bottom buttoms that said “Go to Panels.”
Having found how to create a new panel, I immediately created one and with some advice I found on this forum (Table of Contents in a Right Panel) I had my TOC panel ready to go. So I went to the page I wanted to add the TOC panel to and then I was stopped again because I did not know what the reference to the panel should be. So I went back to the panel I created but there was no reference to the name I had to use to include it. A few tries later (first on the name, later on the name in lowercase) I remembered that the former panels (which I already handily deleted) were in the form of a short XWiki reference. So I tried the reference “Panels.TOC” and there it was.
Sorry for the long story (which is a bit off-topic) but I wanted to make a point here. We (you) are discussing the automatic generation of a TOC and one of the best proposals IMO is the addition through Panels. I think it gives a lot of control. The auto generation is a nice and shiny feature but an admin can make XWiki nice and shiny. That is one of the main reasons I use XWiki, it is so hugely versatile and customizable, for me it’s hard not to love it. But this is the point here, I think one of the biggest ‘selling points’ of XWiki is it’s customizability, it’s depth and versatility (and way more than that). Besides that, it’s Java based instead of (the perhaps soon to be buried?) PHP. But here I am, bumbling my way through the versatility of XWiki (which IMO should totally not be neccessary) and we (you) are talking about adding something nice and shiny.
But to get back on topic
No thank you, I make it shiny myself and if neccessary will add my own short info page on how to add a TOC (and footnotes, links, images etc. etc.) for the users.
No, same as above.
No, I think it is more wise to keep the tree node for pages/spaces only.
No, the reason: “Stop driving my car” This is a display/design feature which I can easily add myself if I wanted to.
To be short, XWiki is so customizable, everything is possible. But the ‘directions’ on some important functionalities have room for improvement. Just some text and a link I think is not too much to ask for.
PS
Oh, and why the popup info on the Global Admin Panels page (Panel List tab) on the text at the top? Why not just plain text added to the text already there? Just asking.
I created a couple issues so that we can improve the points where you got stuck.1 and 2. Feel free to report improvements and bugs directly on our ticket tracking platform yourself whenever you find more
I’m not sure why, but the popup system here is a fairly dated and custom piece of code that’d need some updating From an accessibility PoV, it’s really bad, but it’s not a priority since there’s a way around this UI.
You’re welcome to open a proposal on the forum with your idea for an alternative, or a jira ticket about this
Note that having a TOC Panel is not that good as explained by @MichaelHamann above and also in the jira issue for it at Loading... (basically executing the macro transformation is dangerous). If it’s just about a “static” TOC then it could work but a solution that would work for all cases is preferable anyway and thus IMO the TOC panel would always remain something optional and not recommended.
However this is panel config since it’s in the Admin.
The other place you could have looked at is the Application Index in your wiki (located in the drawer), and you’d have found the “Panels” app.
For me this shows that it’s not too hard to find but if we wanted it to be even easier, let’s see what we could do:
I think we could link to the App index from “More Applications” in the app panel in addition to “create your own” and “install new extension”. WDYT?
Allow searching for help in the search and display help topics under a Help category. This sounds nice but a) it’s hard to implement and b) IMO it’ll always be less good than a google search
Hi Lucas, that is precisely what I mean with the remarks I made. Words are magical and when the precise word is not found a user has a bit of frustration.
Thank you for making the Jira entries for this. I should have done this myself instead of leaving it to you. Sometimes a good improvement is found in the most tiniest of things
I read through the comments at the jira link and I understand now why the TOC panel has been removed. What @MichaelHamann said is also true. And I agree with you all (VM, TM, MH) that the auto TOC is a nice feature to have (and to portray in the ‘shop-window’, so to speak). But TBH, the question was, and I am paraphrasing, “Do we need this feature?” I do not.
So is it good for XWiki to add auto TOC, most probably yes. Then it is about the implementaton and here I would like to add my take on it.
I think it is logical to be able to switch the auto TOC on and off in the admin page.
I think it would be great if there was an option in the admin page to choose where the TOC will be shown. This with the options of a) in the content block or b) in a predefined panel. For option b) a panel exists (let’s call it ‘auto TOC’) which the admin can place where he/she wants.
If the admin chooses to have the auto TOC in the content I think it would be great if he/she could have the choice where it would be. It can be ‘hidden’ behind the control element you stated in point 5 (the UIXP thingy) or ‘floating’ left or right at the top in the contents.
I think it would also be great to have a bit of control on when to generate this auto TOC, with 3 headers, 5 headers, 1 header, etc. Every use case should be covered. If an admin wants to mess it up by setting 1 header, let him do so. He/she can always un-mess it up.
I think it would also be nice for an admin to be able to define a translatable title for the auto TOC.
The HTML structure of the current TOC is proper and does not have to be changed.
Just to add a small point regarding the panel, thinking about this again, it is also possible to generate and save the toc when rendering the document and to then display it in a panel. As the content should be rendered before the panels are rendered, this should work.
I did that search too but on Duckduckgo, with the same result. But the point I tried to make in my babbling was that this should not be needed. Lucas said it exactly right, it’s just about the choice of words, no other solution is needed.
There is also a bit of a usability fallacy in the term “Go to Panels” when I am located in the Global admin > Look and feel > Panels page.
What I tried to get across is the ‘first-time user experience’ which is so easily lost when developers are neck deep in the project they are involved in. Personally I think that XWiki needs more developers that can build more plugins and create more out of the box XWiki sites. I also think that the setup (a decent standard setup of Linux-tomcat) is a bit scary or ‘left-field’ for a lot of people compared to the standard PHP hosting for a nickle.
I have bought myself a physical server, got me the best internet connection money could buy and went building it up myself. It’s cheap and fast (Dutch people eh, ). It’s only that it is a bit noisy in my 18m2 studio. I am seriously pondering on leaving Netherlands alltogether so I can have a proper house like a normal human would have.
Thanks for the help anyway and have a nice and tasty evening,
JP
.
This is a display/design feature which I can easily add myself if I wanted to.