Activate and customize “Table of contents” macro in IBM Connections Wiki

7 Aug, 2013 · by Christoph Stoettner · Read in about 3 min · (440 words)

I read of a new function in IBM Connections Wiki i missed the last time on twitter today. A new macro to create a table of contents within a wiki page.

The activation of this macro is documented here: Wikis configuration properties

wikimacros.enabled
Specifies whether macros are enabled in Wikis. You can use macros to automate common tasks, such as generating a table of contents in a wiki page. The default value of this parameter is false. To enable macros, set the value to true. When enabled, macros are available from the Macros menu in the editor toolbar.

I’m a little bit confused, because i have to change the wording in wikis-config.xml:

 <editor>
      <wikitexttab enabled="true" />
      <wikimacros enabled="true" /> <!-- add this line -->
 </editor>

After checking in the configuration file and restart connections i got a new button in my wikis editor:

Macro for Table of Contents

Quite cool, but the macro only generates headings with format h2, h3 and h4 to the TOC. The richtext editor provides headings h1-h4. I want to change this behavior, that h1 will be added to TOC too.

I found a great article on adding templates to ckeditor from Rob Novak, there he describes how you can customize the ckeditor of wikis. I used the paths mentioned in this article to customize the toc behavior.

Extract toc.js

You can find the needed file com.ibm.lconn.wikis.web.resources_3.5.0.20130627-1601.jar in folder /opt/IBM/Connections/data/shared/provision/webresources. I extracted it to /tmp:

unzip -d /tmp/ckeditor /opt/IBM/Connections/data/shared/provision/webresources/com.ibm.lconn.wikis.web.resources_3.5.0.20130627-1601.jar

Create customization path and copy toc.js

mkdir -p /opt/IBM/Connections/data/shared/customization/javascript/lconn/wikis/macros
cp /tmp/ckeditor/resources/macros/toc.js /opt/IBM/Connections/data/shared/customization/javascript/lconn/wikis/macros

Change toc.js

vim /opt/IBM/Connections/data/shared/customization/javascript/lconn/wikis/macros/toc.js

You find the following part:

lconn.wikis.macros.toc = {
//node id sequence for TOC link.
    fragmentSeqn: 1,
    topLevel: 2,
    bottomLevel: 4,
    template: 'Table of Contents:<INSERT-BODY>',

You have to change topLevel and bottomLevel to following:

lconn.wikis.macros.toc = {
//node id sequence for TOC link.
    fragmentSeqn: 1,
    topLevel: 1,
    bottomLevel: 5,
    template: 'Table of Contents:<INSERT-BODY>',

After a new Connections restart my toc got updated with h1 – h5.

Update

Change Styles

If you want to change the default style of your tocs, you can do this in the toc.js file too! I prefer my TOC on the right screen side and with a light grey not yellow background.

I changed:

 style: 'border-radius: 6px; margin: 8px; padding: 4px; display: block; width: 50%;background-color: #ffc;',

To:

 style: 'border-radius: 6px; margin: 8px; padding: 4px; display: block; width: 30%;background-color: #E0E0E0;float:right;padding:10px;margin-left:20px;margin-bottom:20px;',

Now i have a little bit smaller toc with additional space to the content:

Changing the style of your toc

It would be better to define the styles through a CSS file in customization folder, but i only want to test it. When you want to change through css file, then you should remove most of the styles from style:.