org.xwiki.rendering.internal.macro.toc.TocTreeBuilder Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of xwiki-rendering-macro-toc Show documentation
Show all versions of xwiki-rendering-macro-toc Show documentation
Generates a Table Of Content for titles (headings)
/*
* 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.macro.toc;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import org.apache.commons.lang3.StringUtils;
import org.xwiki.rendering.block.Block;
import org.xwiki.rendering.block.BulletedListBlock;
import org.xwiki.rendering.block.HeaderBlock;
import org.xwiki.rendering.block.LinkBlock;
import org.xwiki.rendering.block.ListBLock;
import org.xwiki.rendering.block.ListItemBlock;
import org.xwiki.rendering.block.NumberedListBlock;
import org.xwiki.rendering.block.SectionBlock;
import org.xwiki.rendering.listener.reference.DocumentResourceReference;
import org.xwiki.rendering.macro.toc.TocEntriesResolver;
import org.xwiki.rendering.macro.toc.TocEntryExtension;
/**
* Generates a TOc Tree of {@link Block} from input input parameters.
*
* @version $Id: 859a096170ec716fbd6a2688aeeedb4700a2c6a7 $
* @since 9.6RC1
*/
public class TocTreeBuilder
{
private static final String CLASS_PARAMETER = "class";
private TocBlockFilter tocBlockFilter;
private TocEntriesResolver tocEntriesResolver;
private List extensions;
/**
* Initialize a table of content tree builder.
*
* @param tocBlockFilter the filter to use to generate the toc anchors
* @param tocEntriesResolver the resolver to use to find the entries in a given {@link Block}
* @param extensions the decorators that will be called on each toc entry, allowing to add additional
* information on the toc entries
*/
public TocTreeBuilder(TocBlockFilter tocBlockFilter, TocEntriesResolver tocEntriesResolver,
List extensions)
{
this.tocBlockFilter = tocBlockFilter;
this.tocEntriesResolver = tocEntriesResolver;
this.extensions = extensions;
}
/**
* @param parameters the input parameters to generate the tree of {@link Block}s.
* @return the list of {@link Block}s representing the TOC
*/
public List build(TreeParameters parameters)
{
List result;
// Example:
// 1 Section1
// 1 Section2
// 1.1 Section3
// 1 Section4
// 1.1.1 Section5
// Generates:
// ListBlock
// |_ ListItemBlock (TextBlock: Section1)
// |_ ListItemBlock (TextBlock: Section2)
// ...|_ ListBlock
// ......|_ ListItemBlock (TextBlock: Section3)
// |_ ListItemBlock (TextBlock: Section4)
// ...|_ ListBlock
// ......|_ ListBlock
// .........|_ ListItemBlock (TextBlock: Section5)
// Get the list of sections in the scope
List headers = this.tocEntriesResolver.getBlocks(parameters.rootBlock);
// If the root block is a section, remove its header block for the list of header blocks
if (parameters.rootBlock instanceof SectionBlock) {
Block block = parameters.rootBlock.getChildren().get(0);
if (block instanceof HeaderBlock) {
headers.remove(block);
}
}
// Construct table of content from sections list
Block tocBlock = generateTree(headers, parameters);
if (tocBlock != null) {
result = Arrays.asList(tocBlock);
} else {
result = Collections.emptyList();
}
return result;
}
/**
* Convert headers into list block tree.
*
* @param headers the headers to convert.
* @param parameters the tree parameters
* @return the root block of generated block tree or null if no header was matching the specified parameters
*/
private Block generateTree(List headers, TreeParameters parameters)
{
Block tocBlock = null;
int start = parameters.start;
int depth = parameters.depth;
boolean numbered = parameters.isNumbered;
int currentLevel = start - 1;
Block currentBlock = null;
for (HeaderBlock headerBlock : headers) {
int headerLevel = headerBlock.getLevel().getAsInt();
if (headerLevel >= start && headerLevel <= depth) {
// Move to next header in toc tree
if (currentLevel < headerLevel) {
while (currentLevel < headerLevel) {
if (currentBlock instanceof ListBLock) {
currentBlock = addItemBlock(currentBlock, null, parameters);
}
currentBlock = createChildListBlock(numbered, currentBlock);
++currentLevel;
}
} else {
while (currentLevel > headerLevel) {
currentBlock = currentBlock.getParent().getParent();
--currentLevel;
}
currentBlock = currentBlock.getParent();
}
currentBlock = addItemBlock(currentBlock, headerBlock, parameters);
}
}
if (currentBlock != null) {
tocBlock = currentBlock.getRoot();
// Add CSS class to ease styling.
tocBlock.setParameter(CLASS_PARAMETER, "wikitoc");
}
if (tocBlock != null) {
flagEntriesWithNoDirectChild(tocBlock);
}
return tocBlock;
}
/**
* Add a {@link ListItemBlock} in the current toc tree block and return the new {@link ListItemBlock}.
*
* @param currentBlock the current block in the toc tree.
* @param headerBlock the {@link HeaderBlock} to use to generate toc anchor label.
* @param parameters the tree parameters
* @return the new {@link ListItemBlock}.
*/
private Block addItemBlock(Block currentBlock, HeaderBlock headerBlock, TreeParameters parameters)
{
ListItemBlock itemBlock = headerBlock == null ? createEmptyTocEntry() : createTocEntry(headerBlock, parameters);
currentBlock.addChild(itemBlock);
return itemBlock;
}
/**
* @return a new empty list item.
* @since 1.8RC2
*/
private ListItemBlock createEmptyTocEntry()
{
return new ListItemBlock(Collections.emptyList());
}
/**
* Create a new toc list item based on section title.
*
* @param headerBlock the {@link HeaderBlock}.
* @param parameters the tree parameters
* @return the new list item block.
*/
protected ListItemBlock createTocEntry(HeaderBlock headerBlock, TreeParameters parameters)
{
// Create the link to target the header anchor
DocumentResourceReference reference = new DocumentResourceReference(parameters.documentReference);
String idParameter = headerBlock.getParameter("id");
if (idParameter != null) {
reference.setAnchor(idParameter);
} else {
reference.setAnchor(headerBlock.getId());
}
List blocks = this.tocBlockFilter.generateLabel(headerBlock);
for (TocEntryExtension extension : this.extensions) {
blocks = extension.decorate(headerBlock, blocks, parameters.rootBlock, this.tocEntriesResolver);
}
LinkBlock linkBlock = new LinkBlock(blocks, reference, false);
return new ListItemBlock(Collections.singletonList(linkBlock));
}
/**
* Create a new ListBlock and add it in the provided parent block.
*
* @param numbered indicate if the list has to be numbered or with bullets
* @param parentBlock the block where to add the new list block.
* @return the new list block.
*/
private ListBLock createChildListBlock(boolean numbered, Block parentBlock)
{
ListBLock childListBlock =
numbered ? new NumberedListBlock(Collections.emptyList()) : new BulletedListBlock(Collections.emptyList());
if (parentBlock != null) {
parentBlock.addChild(childListBlock);
}
return childListBlock;
}
/**
* Add a {@code nodirectchild} class to each entry that has no direct child. This happens when two successive items
* have a level difference greater than one. For instance, when a level 1 heading is followed by a level 3 heading.
*
* @param tocBlock the toc block to analyse for entries with not direct child
*/
private void flagEntriesWithNoDirectChild(Block tocBlock)
{
tocBlock.getBlocks(block ->
block instanceof ListItemBlock
&& block.getChildren().size() == 1
&& !(block.getChildren().get(0) instanceof LinkBlock),
Block.Axes.DESCENDANT)
.forEach(listBlock -> listBlock.setParameter(CLASS_PARAMETER,
(StringUtils.defaultIfEmpty(listBlock.getParameter(CLASS_PARAMETER), "")
+ " nodirectchild").trim()));
}
}