XRENDERING-345: Add an Auto TOC transformation to automatically add a TOC when pages are rendered

xwiki-rendering-transformations/pom.xml

@@ -58,9 +58,11 @@
     </dependency>
   </dependencies>
   <modules>
-    <module>xwiki-rendering-transformation-macro</module>
+    <!-- Sorted Alphabetically -->
+    <module>xwiki-rendering-transformation-autotoc</module>
     <module>xwiki-rendering-transformation-icon</module>
-    <module>xwiki-rendering-transformation-wikiword</module>
     <module>xwiki-rendering-transformation-linkchecker</module>
+    <module>xwiki-rendering-transformation-macro</module>
+    <module>xwiki-rendering-transformation-wikiword</module>
   </modules>
 </project>

xwiki-rendering-transformations/xwiki-rendering-transformation-autotoc/pom.xml

+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.xwiki.rendering</groupId>
+    <artifactId>xwiki-rendering-transformations</artifactId>
+    <version>6.1-SNAPSHOT</version>
+  </parent>
+  <artifactId>xwiki-rendering-transformation-autotoc</artifactId>
+  <name>XWiki Rendering - Transformation - Auto TOC</name>
+  <description>Automatically adds a TOC at the top of content</description>
+  <properties>
+    <xwiki.jacoco.instructionRatio>0.94</xwiki.jacoco.instructionRatio>
+  </properties>
+</project>

xwiki-rendering-transformations/xwiki-rendering-transformation-autotoc/src/main/java/org/xwiki/rendering/internal/transformation/autotoc/AutoTOCTransformation.java

+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.rendering.internal.transformation.autotoc;
+
+import java.util.Collections;
+import java.util.List;
+
+import javax.inject.Named;
+import javax.inject.Singleton;
+
+import org.xwiki.component.annotation.Component;
+import org.xwiki.rendering.block.Block;
+import org.xwiki.rendering.block.MacroBlock;
+import org.xwiki.rendering.block.SectionBlock;
+import org.xwiki.rendering.block.match.ClassBlockMatcher;
+import org.xwiki.rendering.transformation.AbstractTransformation;
+import org.xwiki.rendering.transformation.TransformationContext;
+import org.xwiki.rendering.transformation.TransformationException;
+
+/**
+ * Automatically adds a TOC Macro at the top of the content.
+ *
+ * @version $Id$
+ * @since 6.1M2
+ */
+@Component
+@Named("autotoc")
+@Singleton
+public class AutoTOCTransformation extends AbstractTransformation
+{
+    @Override
+    public int getPriority()
+    {
+        // High priority transformation that must execute before the Macro Transformation since it's injecting a macro!
+        return 50;
+    }
+
+    @Override
+    public void transform(Block block, TransformationContext transformationContext) throws TransformationException
+    {
+        // Insert the TOC as the first block
+        List<Block> childrenBlocks = block.getChildren();
+        if (!childrenBlocks.isEmpty()) {
+            SectionBlock sectionBlocks = block.getFirstBlock(
+                new ClassBlockMatcher(SectionBlock.class), Block.Axes.DESCENDANT_OR_SELF);
+            if (sectionBlocks != null) {
+                Block blockToInsertAfter = childrenBlocks.get(0);
+                MacroBlock tocBlock = new MacroBlock("toc", Collections.EMPTY_MAP, false);
+                block.insertChildBefore(tocBlock, blockToInsertAfter);
+            }
+        }
+    }
+}

xwiki-rendering-transformations/xwiki-rendering-transformation-autotoc/src/main/resources/META-INF/components.txt

+org.xwiki.rendering.internal.transformation.autotoc.AutoTOCTransformation
\ No newline at end of file

xwiki-rendering-transformations/xwiki-rendering-transformation-autotoc/src/test/java/org/xwiki/rendering/internal/transformation/autotoc/AutoTOCTransformationTest.java

+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.rendering.internal.transformation.autotoc;
+
+import java.io.StringReader;
+
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import org.xwiki.rendering.block.XDOM;
+import org.xwiki.rendering.parser.Parser;
+import org.xwiki.rendering.renderer.BlockRenderer;
+import org.xwiki.rendering.renderer.printer.DefaultWikiPrinter;
+import org.xwiki.rendering.renderer.printer.WikiPrinter;
+import org.xwiki.rendering.transformation.Transformation;
+import org.xwiki.rendering.transformation.TransformationContext;
+import org.xwiki.test.ComponentManagerRule;
+import org.xwiki.test.annotation.AllComponents;
+import org.junit.Assert;
+
+/**
+ * Unit tests for {@link org.xwiki.rendering.internal.transformation.autotoc.AutoTOCTransformation}.
+ *
+ * @version $Id$
+ * @since 6.1M2
+ */
+@AllComponents
+public class AutoTOCTransformationTest
+{
+    @Rule
+    public ComponentManagerRule componentManager = new ComponentManagerRule();
+
+    private Transformation autoTOCTransformation;
+
+    @Before
+    public void setUp() throws Exception
+    {
+        this.autoTOCTransformation = this.componentManager.getInstance(Transformation.class, "autotoc");
+    }
+
+    @Test
+    public void testTransformation() throws Exception
+    {
+        String content = "Some content without toc\n= heading 1=\nother content";
+
+        Parser parser = this.componentManager.getInstance(Parser.class, "xwiki/2.1");
+        XDOM xdom = parser.parse(new StringReader(content));
+        this.autoTOCTransformation.transform(xdom, new TransformationContext());
+        WikiPrinter printer = new DefaultWikiPrinter();
+        BlockRenderer xwiki21BlockRenderer = this.componentManager.getInstance(BlockRenderer.class, "xwiki/2.1");
+        xwiki21BlockRenderer.render(xdom, printer);
+        Assert.assertEquals("{{toc/}}\n\nSome content without toc\n\n= heading 1 =\n\nother content",
+            printer.toString());
+    }
+}