Table of Contents for Knowledge base using pages

[Roboko]

I was hoping to set up a sort of Knowledge base using the Pages plugin, each page has the potential to contain a lot of information.

What I was hoping is to have some way that a table of contents is automatically displayed at the top of the page that people can use to jump to the relevant section. Something like this possible? How would you go about doing it?

[Meddysong]

Yes, that's possible: Invision do it on their Help Guides section, which is built with Pages:

They do so using JavaScript, and then mark then place an anchor and title like this in the page:

<a id="generalterms" rel=""></a>

	<h2 class="cDocs_mainTitle" data-role="title">
		General Terms
	</h2>

The script then looks for anything marked 'data-role="title"', and uses the relevant text to generate the menu, creating links to the preceding <a> tags.

[Roboko]

Interesting. I take it the Javascript is added to the Templates system somehow. I'll have to have a mess around

[Roboko]

@Meddysong I didn't quite figure out how that ips.controller.... stuff works, could not find what it is supposed to be hooking into or where. Documentation on this somewhere?

I got creative and came up with my own solution though, in case anyone else wants it. First here's what it looks like 🙂

It shows up on the top right of the page.

What I did:

1. Created a new JS File
   Admin CP > Pages > Templates > JS > New JavaScript File kb-nav

   (function($){
    $('article').each(function(index) {
       let article = $(this);
       let nav     = $('<ul class="kb-nav"></ul>');
    	$(this).find('h2,h3').each(function(index) {
         let anchor = "<a class='kb-anchor' name='" + index + "'></a>";
         $(this).before(anchor);
         nav.append('<li><a href="#' + index + '">' + $(this).text() + '</a></li>');
      	});
       article.prepend(nav);
    });
   }(jQuery));

   Explanation:
   I use jQuery to loop through all <article> elements on the page, and inside each one, I look for <h2> and <h3> tags.
   For each tag, I add an <a> anchor tag which can be used as a jump point on the page. I also add it to an unordered list <ul> which I prepend to the top of the article.

2. Created some CSS to style it
   Admin CP > Pages > Templates > CSS > New CSS File kb-css

   ul.kb-nav {
     background: #f5f5f5;
     float: right;
     width: 20em;
     padding: 2em;
     font-size: small;
   }
   
   ul.kb-nav::before {
       content: "Jump to"; 
       font-size: small;
       font-weight: bold;
   }

3. Included my JS/CSS in my Page
   Pages > Pages > Edit my KB Articles Page > Page Includes > Checked my JS and CSS files and clicked Save 🙂

Things I didn't do that would be nice improvements, maybe another day

• Indent h3 items in the list
• Get the article content to wrap rather than appear under
• Prettier layout/bullet points
• Maybe give the anchor tags names rather than use numbers

[Sonya*]

This database includes TOC as well 

You can install it and just apply JS and CSS to your database.  

Here is an example https://invisionify.com/fxdocs_demo/introduction/create-toc-on-the-fly-r2/

Edited October 24, 2021 by Sonya*

[Roboko]

3 hours ago, Sonya* said:

This database includes TOC as well 

You can install it and just apply JS and CSS to your database.  

Here is an example https://invisionify.com/fxdocs_demo/introduction/create-toc-on-the-fly-r2/

Funny, I had searched for something like this before, I searched for 'wiki', 'knowledgebase' but this plugin didn't come up. I will try it. Thanks

[Meddysong]

10 hours ago, Roboko said:

I didn't quite figure out how that ips.controller.... stuff works, could not find what it is supposed to be hooking into or where. Documentation on this somewhere?

Here's an example of adding JS and CSS into a project: 

 

You'd do the same thing, assigning the JS template you've created to the relevant page. 

The next step is to adjust your Database template so that it applies that new JS. In the case of IPS, they added it in a <section> tag using the data-contoller attribute.

<section class="ipsType_richText ipsType_normal" data-controller='core.front.core.lightboxedImages,guides.menu'>

 

Edited October 24, 2021 by Meddysong

[Roboko]

@Sonya* I installed that addon on my site. Pages was already installed, but somehow it totally broke my front-end which is largely default.

 

The page loads with no CSS and is therefor not usable, a bit of a disaster. Going to have to roll back my site somehow. Any ideas what went wrong?

I removed the plugin, went through and deleted everything beginning FX from templates, database, page, and then went to System > Get Support > Clear System Cache and that got my site back, in case it happens to someone else in the future...

[Sonya*]

@Roboko I am sorry to see this. Unfortunately, I cannot reproduce the error on my side. I will see that I add a simple XML-Templates import to the FX Documentation. This way, you can import Templates (IPS default feature) and then apply them manually to your database and database page (CSS and JS).

[Claudia999]

@Sonya* I try to use your TOC in another database template. Your database is installed and in my Pages page I included the 3 JS and one CSS files. But the TOC doesn't appear.

Could you explain please where I have to place which things or code?

[Sonya*]

@Claudia999

1. You can use it with any database.
2. You have to include JS/Fxdocs Toc.js in the page that the database assigned to.
3. In the record template of your database find:

   <section class="ipsType_richText ipsContained ipsType_normal" data-controller='core.front.core.lightboxedImages'>{$record->_content|raw}</section>

   and add an JS controller like this:

   <section class="ipsType_richText ipsContained ipsType_normal" data-controller='core.front.core.lightboxedImages,fxdocs.images,fxdocs.toc'>{$record->_content|raw}</section>

4. You have to use headings h2-h4 in order the TOC be displayed, e. g. with format plugin https://ckeditor.com/cke4/addon/format

[Claudia999]

On 12/24/2021 at 3:23 PM, Sonya* said:

@Claudia999

1. You can use it with any database.
2. You have to include JS/Fxdocs Toc.js in the page that the database assigned to.
3. In the record template of your database find:

   <section class="ipsType_richText ipsContained ipsType_normal" data-controller='core.front.core.lightboxedImages'>{$record->_content|raw}</section>

   and add an JS controller like this:

   <section class="ipsType_richText ipsContained ipsType_normal" data-controller='core.front.core.lightboxedImages,fxdocs.images,fxdocs.toc'>{$record->_content|raw}</section>

4. You have to use headings h2-h4 in order the TOC be displayed, e. g. with format plugin https://ckeditor.com/cke4/addon/format

It works great! Many thanks!