org.xwiki.rendering.block
Interface Block

All Superinterfaces:

java.lang.Cloneable

All Known Subinterfaces:

ListBLock

All Known Implementing Classes:

AbstractBlock, BulletedListBlock, DefinitionDescriptionBlock, DefinitionListBlock, DefinitionTermBlock, EmptyLinesBlock, FormatBlock, GroupBlock, HeaderBlock, HorizontalLineBlock, IdBlock, ImageBlock, LinkBlock, ListItemBlock, MacroBlock, MacroMarkerBlock, MetaDataBlock, NewLineBlock, NumberedListBlock, ParagraphBlock, QuotationBlock, QuotationLineBlock, RawBlock, SectionBlock, SpaceBlock, SpecialSymbolBlock, TableBlock, TableCellBlock, TableHeadCellBlock, TableRowBlock, VerbatimBlock, WordBlock, XDOM

public interface Block
extends java.lang.Cloneable

Represents an element of a XWiki Document's content. For example there are Blocks for Paragraphs, Bold parts, Sections, Links, etc. A block has a parent and can have children too for Blocks which are wrapper around other blocks (e.g. Paragraph blocks, List blocks, Bold blocks).

Since:

1.5M2

Version:

$Id: Block.java 34833 2011-02-21 14:16:30Z tmortagne $

Nested Class Summary

static class

Block.Axes Search axes used in searching methods.

Method Summary

void	addChild(Block blockToAdd) Helper method to add a single child block to the end of the children list of the current block.
void	addChildren(java.util.List<? extends Block> blocksToAdd) Adds several children blocks to the end of the children list of the current block.
Block	clone()
Block	clone(BlockFilter blockFilter) Return a copy of the block with filtered children.
java.util.List<Block>	getBlocks(BlockMatcher matcher, Block.Axes axes) Get all blocks following provided BlockMatcher and Block.Axes.
java.util.List<Block>	getChildren() Gets all children blocks.
<T extends Block> java.util.List<T>	getChildrenByType(java.lang.Class<T> blockClass, boolean recurse) Deprecated. since 3.0M3 use getBlocks(BlockMatcher, Axes) instead
Block	getFirstBlock(BlockMatcher matcher, Block.Axes axes) Get the first matched block in the provided Block.Axes.
Block	getNextSibling()
java.lang.String	getParameter(java.lang.String name) A Parameter is a generic key/value which can be used to add metadata to a block.
java.util.Map<java.lang.String,java.lang.String>	getParameters()
Block	getParent() Get the parent block.
<T extends Block> T	getParentBlockByType(java.lang.Class<T> blockClass) Deprecated. since 3.0M3 use getBlocks(BlockMatcher, Axes) instead
<T extends Block> T	getPreviousBlockByType(java.lang.Class<T> blockClass, boolean recurse) Deprecated. since 3.0M3 use getBlocks(BlockMatcher, Axes) instead
Block	getPreviousSibling()
Block	getRoot() Gets the top level Block.
void	insertChildAfter(Block blockToInsert, Block previousBlock) Helper method to add a single child block to the current block after the provided existing child block.
void	insertChildBefore(Block blockToInsert, Block nextBlock) Helper method to add a single child block to the current block before the provided existing child block.
void	removeBlock(Block childBlockToRemove) Removes a Block.
void	replaceChild(Block newBlock, Block oldBlock) Replaces an existing children block with the passed new block.
void	replaceChild(java.util.List<Block> newBlocks, Block oldBlock) Replaces an existing children block with the passed new blocks.
void	setChildren(java.util.List<? extends Block> children) Replace current children by the provided list of Blocks.
void	setNextSiblingBlock(Block nextSiblingBlock)
void	setParameter(java.lang.String name, java.lang.String value) Set a parameter on the current block.
void	setParameters(java.util.Map<java.lang.String,java.lang.String> parameters) Set several parameters at once.
void	setParent(Block parentBlock) Sets the parent block.
void	setPreviousSiblingBlock(Block previousSiblingBlock)
void	traverse(Listener listener) Let the block send Listener events corresponding to its content.

Method Detail

traverse

void traverse(Listener listener)

Let the block send Listener events corresponding to its content. For example a Paragraph block will send the Listener.beginParagraph(java.util.Map) and Listener.endParagraph(java.util.Map) events when this method is called.

Parameters:

listener - the listener to which to send the events to.

addChild

void addChild(Block blockToAdd)

Helper method to add a single child block to the end of the children list of the current block. For adding several blocks at once use addChildren(java.util.List).

Parameters:

blockToAdd - the child block to add

addChildren

void addChildren(java.util.List<? extends Block> blocksToAdd)

Adds several children blocks to the end of the children list of the current block. For example a bold sentence is made up of a Bold block to which the different words making up the text have been added to.

Parameters:

blocksToAdd - the children blocks to add

setChildren

void setChildren(java.util.List<? extends Block> children)

Replace current children by the provided list of Blocks.

Parameters:

children - the new children

insertChildBefore

void insertChildBefore(Block blockToInsert,
                       Block nextBlock)

Helper method to add a single child block to the current block before the provided existing child block. For adding several blocks at once use addChildren(java.util.List).

Parameters:

blockToInsert - the child block to add

nextBlock - the child block that will be just after the added block

Since:

1.6M1

insertChildAfter

void insertChildAfter(Block blockToInsert,
                      Block previousBlock)

Helper method to add a single child block to the current block after the provided existing child block. For adding several blocks at once use addChildren(java.util.List).

Parameters:

blockToInsert - the child block to add

previousBlock - the child block that will be just before the added block

Since:

1.6M1

replaceChild

void replaceChild(Block newBlock,
                  Block oldBlock)

Replaces an existing children block with the passed new block. Also sets the new block's parent to be the current block.

Parameters:

newBlock - the new block to replace the old block with

oldBlock - the block to replace with the new block

replaceChild

void replaceChild(java.util.List<Block> newBlocks,
                  Block oldBlock)

Replaces an existing children block with the passed new blocks. Also sets the new block's parents to be the current block.

Parameters:

newBlocks - the new blocks to replace the old block with

oldBlock - the block to replace with the new blocks

getParent

Block getParent()

Get the parent block. All blocks have a parent and the top level parent is the XDOM object.

Returns:

the parent block

setParent

void setParent(Block parentBlock)

Sets the parent block.

Parameters:

parentBlock - the parent block

getChildren

java.util.List<Block> getChildren()

Gets all children blocks.

Returns:

the children blocks

See Also:

addChildren(java.util.List)

getRoot

Block getRoot()

Gets the top level Block. If the current block is the top level Block, it return itself.

Returns:

the top level Block

removeBlock

void removeBlock(Block childBlockToRemove)

Removes a Block.

Parameters:

childBlockToRemove - the child block to remove

Since:

2.6RC1

getNextSibling

Block getNextSibling()

Returns:

the next sibling block or null if there's no next sibling

Since:

2.6RC1

setNextSiblingBlock

void setNextSiblingBlock(Block nextSiblingBlock)

Parameters:

nextSiblingBlock - see getNextSibling()

Since:

2.6RC1

getPreviousSibling

Block getPreviousSibling()

Returns:

the previous sibling block or null if there's no previous sibling

Since:

2.6RC1

setPreviousSiblingBlock

void setPreviousSiblingBlock(Block previousSiblingBlock)

Parameters:

previousSiblingBlock - see getPreviousSibling() ()}

Since:

2.6RC1

clone

Block clone(BlockFilter blockFilter)

Return a copy of the block with filtered children.

Parameters:

blockFilter - the Block filter.

Returns:

the filtered Block.

Since:

1.8RC2

clone

Block clone()

See Also:

Object.clone()

getParameters

java.util.Map<java.lang.String,java.lang.String> getParameters()

Returns:

all parameters

Since:

3.0M1

getParameter

java.lang.String getParameter(java.lang.String name)

A Parameter is a generic key/value which can be used to add metadata to a block. What is done with the metadata depends on the Renderer's implementations. For example the XHTML Renderer adds them as Element attributes.

Parameters:

name - the name of the parameter to return

Returns:

the parameter or null if the parameter doesn't exist

Since:

3.0M1

setParameter

void setParameter(java.lang.String name,
                  java.lang.String value)

Set a parameter on the current block. See getParameter(String) for more details.

Parameters:

name - the parameter's name

value - the parameter's value

Since:

3.0M1

setParameters

void setParameters(java.util.Map<java.lang.String,java.lang.String> parameters)

Set several parameters at once.

Parameters:

parameters - the parameters to set

Since:

3.0M1

See Also:

getParameter(String)

getBlocks

java.util.List<Block> getBlocks(BlockMatcher matcher,
                                Block.Axes axes)

Get all blocks following provided BlockMatcher and Block.Axes.

Parameters:

matcher - filter the blocks to return

axes - indicate the search axes

Returns:

the matched Blocks, empty list of none was found

Since:

3.0M3

getFirstBlock

Block getFirstBlock(BlockMatcher matcher,
                    Block.Axes axes)

Get the first matched block in the provided Block.Axes.

Parameters:

matcher - indicate which block to stop to

axes - indicate the search axes

Returns:

the matched Block, null if none was found

Since:

3.0M3

getChildrenByType

@Deprecated
<T extends Block> java.util.List<T> getChildrenByType(java.lang.Class<T> blockClass,
                                                                 boolean recurse)

Deprecated. since 3.0M3 use getBlocks(BlockMatcher, Axes) instead

Gets all the Blocks in the tree which are of the passed Block class.

Type Parameters:

T - the class of the Blocks to return

Parameters:

blockClass - the block class to look for

recurse - if true also search recursively children

Returns:

all the matching blocks

Since:

1.6M1

getPreviousBlockByType

@Deprecated
<T extends Block> T getPreviousBlockByType(java.lang.Class<T> blockClass,
                                                      boolean recurse)

Deprecated. since 3.0M3 use getBlocks(BlockMatcher, Axes) instead

Look upward to find a block which inherit or is provided type.

The difference with getParentBlockByType(Class) is that this one look also at previous block in the same parent when getParentBlockByType(Class) only look at parents.

Type Parameters:

T - the class of the Blocks to return

Parameters:

blockClass - the block class to look for

recurse - if true also search in parents levels

Returns:

the found block, null if nothing is found

Since:

1.6M1

getParentBlockByType

@Deprecated
<T extends Block> T getParentBlockByType(java.lang.Class<T> blockClass)

Deprecated. since 3.0M3 use getBlocks(BlockMatcher, Axes) instead

Recursively look at parents to find a block which inherits or is provided type.

The difference with getPreviousBlockByType(Class, boolean) is that this one only look at parent when getPreviousBlockByType(Class, boolean) look at previous block in the same parent.

Type Parameters:

T - the class of the Blocks to return

Parameters:

blockClass - the block class to look for

Returns:

the found block, null if nothing is found

Since:

1.9.1