org.xwiki.rendering.listener
Interface Listener

All Superinterfaces:

ImageListener, LinkListener

All Known Subinterfaces:

ChainingListener, ContentHandlerStreamRenderer, PrintRenderer, Renderer, StackableChainingListener

All Known Implementing Classes:

AbstractChainingListener, AbstractChainingPrintRenderer, BlockStateChainingListener, CompositeListener, ConsecutiveNewLineStateChainingListener, EmptyBlockChainingListener, GroupStateChainingListener, InlineFilterListener, LookaheadChainingListener, MetaDataStateChainingListener, QueueListener, VoidListener, WrappingListener

public interface Listener
extends LinkListener, ImageListener

Contains callback events called when a document has been parsed and when it needs to be modified or rendered. More specifically when a document is parsed it generates an XDOM object. That object has a AbstractBlock.traverse(Listener) method that accepts a Listener object. For each Block element found in the document its Block.traverse(org.xwiki.rendering.listener.Listener) method is called leading to the generation of events from this interface.

Here's an example of usage:

 <code>
   XDOM dom = parser.parse(source);
   MyListener listener = new MyListener(...);
   dom.traverse(listener);
   // At this stage all events have been sent to MyListener. 
 </code>
 

Since:

1.5M2

Version:

$Id: 7a1c95e295d63a73af1679900a19c9ea1148d7d3 $

Field Summary

static Map<String,String>

EMPTY_PARAMETERS To use when there is no parameters.

Method Summary

void	beginDefinitionDescription() Start of a definition list description.
void	beginDefinitionList(Map<String,String> parameters) Start of a definition list.
void	beginDefinitionTerm() Start of a definition list term.
void	beginDocument(MetaData metaData) Start of the document.
void	beginFormat(Format format, Map<String,String> parameters) End of a text formatting block.
void	beginGroup(Map<String,String> parameters) Start a group of elements.
void	beginHeader(HeaderLevel level, String id, Map<String,String> parameters) Start of a header.
void	beginList(ListType listType, Map<String,String> parameters) Start of a list.
void	beginListItem() Start of a list item.
void	beginMacroMarker(String name, Map<String,String> macroParameters, String content, boolean isInline) Start of marker containing a macro definition.
void	beginMetaData(MetaData metadata) Start of MetaData (eg saving source from where the content is coming from).
void	beginParagraph(Map<String,String> parameters) Start of a paragraph.
void	beginQuotation(Map<String,String> parameters) Start of a quotation.
void	beginQuotationLine() Start of a quotation line.
void	beginSection(Map<String,String> parameters) Start of a section.
void	beginTable(Map<String,String> parameters) Start of a table.
void	beginTableCell(Map<String,String> parameters) Start of a table cell.
void	beginTableHeadCell(Map<String,String> parameters) Start of a table head cell.
void	beginTableRow(Map<String,String> parameters) Start of a table row.
void	endDefinitionDescription() End of a definition list description.
void	endDefinitionList(Map<String,String> parameters) End of a definition list.
void	endDefinitionTerm() End of a definition list term.
void	endDocument(MetaData metaData) End of the document.
void	endFormat(Format format, Map<String,String> parameters) End of a text formatting block.
void	endGroup(Map<String,String> parameters) End of the group.
void	endHeader(HeaderLevel level, String id, Map<String,String> parameters) End of a header.
void	endList(ListType listType, Map<String,String> parameters) End of a list.
void	endListItem() End of a list item.
void	endMacroMarker(String name, Map<String,String> macroParameters, String content, boolean isInline) End of marker containing a macro definition.
void	endMetaData(MetaData metadata) End of MetaData.
void	endParagraph(Map<String,String> parameters) End of a paragraph.
void	endQuotation(Map<String,String> parameters) End of a quotation.
void	endQuotationLine() End of a quotation line.
void	endSection(Map<String,String> parameters) End of a section.
void	endTable(Map<String,String> parameters) End of a table.
void	endTableCell(Map<String,String> parameters) End of a table cell.
void	endTableHeadCell(Map<String,String> parameters) End of a table head cell.
void	endTableRow(Map<String,String> parameters) End of a table row.
void	onEmptyLines(int count) Represents an empty line between 2 standalone Blocks.
void	onHorizontalLine(Map<String,String> parameters) Represents an horizontal line.
void	onId(String name) A reference/location in a page.
void	onMacro(String id, Map<String,String> macroParameters, String content, boolean isInline) A Macro.
void	onNewLine() A new line or line break (it's up to the renderers to decide if it should be outputted as a new line or as a line break in the given syntax).
void	onRawText(String rawContent, Syntax syntax) Some text to inject directly into the listener output without parsing it.
void	onSpace() A space.
void	onSpecialSymbol(char symbol) A special symbol ("*", "<", ">", "=", quote, etc).
void	onVerbatim(String protectedString, boolean isInline, Map<String,String> parameters) A portion of text.
void	onWord(String word) A word.

Methods inherited from interface org.xwiki.rendering.listener.LinkListener

beginLink, endLink

Methods inherited from interface org.xwiki.rendering.listener.ImageListener

onImage

Field Detail

EMPTY_PARAMETERS

static final Map<String,String> EMPTY_PARAMETERS

To use when there is no parameters.

Method Detail

beginDocument

void beginDocument(@Name(value="metadata")
                   MetaData metaData)

Start of the document.

Parameters:

metaData - the meta data to associate to the following events, see MetaData

Since:

3.0M2

endDocument

void endDocument(@Name(value="metadata")
                 MetaData metaData)

End of the document.

Parameters:

metaData - the meta data associated with the previous events, see MetaData

Since:

3.0M2

beginMetaData

void beginMetaData(@Name(value="metadata")
                   MetaData metadata)

Start of MetaData (eg saving source from where the content is coming from).

Parameters:

metadata - the metadata

Since:

3.0M2

endMetaData

void endMetaData(@Name(value="metadata")
                 MetaData metadata)

End of MetaData.

Parameters:

metadata - the metadata

Since:

3.0M2

beginGroup

void beginGroup(@Default(value="")@Name(value="parameters")
                Map<String,String> parameters)

Start a group of elements. Groups are used to allow using standalone elements in list items, table cells, etc. They can also be used to set parameters on a group of standalone elements.

Parameters:

parameters - a generic list of parameters. Example: style="background-color: blue"

Since:

1.8.3

endGroup

void endGroup(@Default(value="")@Name(value="parameters")
              Map<String,String> parameters)

End of the group.

Parameters:

parameters - a generic list of parameters. Example: style="background-color: blue"

Since:

1.8.3

beginFormat

void beginFormat(@Default(value="NONE")@Name(value="format")
                 Format format,
                 @Default(value="")@Name(value="parameters")
                 Map<String,String> parameters)

End of a text formatting block.

Parameters:

format - the formatting type (bold, italic, etc)

parameters - a generic list of parameters. Example: style="background-color: blue"

See Also:

Format

endFormat

void endFormat(@Default(value="NONE")@Name(value="format")
               Format format,
               @Default(value="")@Name(value="parameters")
               Map<String,String> parameters)

End of a text formatting block.

Parameters:

format - the formatting type (bold, italic, etc)

parameters - a generic list of parameters. Example: style="background-color: blue"

See Also:

Format

beginParagraph

void beginParagraph(@Default(value="")@Name(value="parameters")
                    Map<String,String> parameters)

Start of a paragraph.

Parameters:

parameters - a generic list of parameters. Example: style="background-color: blue"

endParagraph

void endParagraph(@Default(value="")@Name(value="parameters")
                  Map<String,String> parameters)

End of a paragraph.

Parameters:

parameters - a generic list of parameters. Example: style="background-color: blue"

beginList

void beginList(@Default(value="BULLETED")@Name(value="type")
               ListType listType,
               @Default(value="")@Name(value="parameters")
               Map<String,String> parameters)

Start of a list.

Parameters:

listType - the type of list (bulleted, numbered, etc)

parameters - a generic list of parameters for the list. Example: "style"/"background-color: blue"

See Also:

ListType

beginDefinitionList

void beginDefinitionList(@Default(value="")@Name(value="parameters")
                         Map<String,String> parameters)

Start of a definition list. For example in HTML this is the equivalent of <dl>.

Parameters:

parameters - a generic list of parameters for the list. Example: "style"/"background-color: blue"

Since:

2.0RC1

endList

void endList(@Default(value="BULLETED")@Name(value="type")
             ListType listType,
             @Name(value="parameters")
             Map<String,String> parameters)

End of a list.

Parameters:

listType - the type of list (bulleted, numbered, etc)

parameters - a generic list of parameters for the list. Example: "style"/"background-color: blue"

See Also:

ListType

endDefinitionList

void endDefinitionList(@Default(value="")@Name(value="parameters")
                       Map<String,String> parameters)

End of a definition list. For example in HTML this is the equivalent of </dl>.

Parameters:

parameters - a generic list of parameters for the list. Example: "style"/"background-color: blue"

Since:

2.0RC1

beginListItem

void beginListItem()

Start of a list item.

beginDefinitionTerm

void beginDefinitionTerm()

Start of a definition list term. For example in HTML this is the equivalent of <dt>.

Since:

1.6M2

beginDefinitionDescription

void beginDefinitionDescription()

Start of a definition list description. For example in HTML this is the equivalent of <dd>.

Since:

1.6M2

endListItem

void endListItem()

End of a list item.

endDefinitionTerm

void endDefinitionTerm()

End of a definition list term. For example in HTML this is the equivalent of </dt>.

Since:

1.6M2

endDefinitionDescription

void endDefinitionDescription()

End of a definition list description. For example in HTML this is the equivalent of </dd>.

Since:

1.6M2

beginTable

void beginTable(@Default(value="")@Name(value="parameters")
                Map<String,String> parameters)

Start of a table.

Parameters:

parameters - a generic list of parameters for the table.

Since:

1.6M2

beginTableRow

void beginTableRow(@Default(value="")@Name(value="parameters")
                   Map<String,String> parameters)

Start of a table row.

Parameters:

parameters - a generic list of parameters for the table row.

Since:

1.6M2

beginTableCell

void beginTableCell(@Default(value="")@Name(value="parameters")
                    Map<String,String> parameters)

Start of a table cell.

Parameters:

parameters - a generic list of parameters for the table cell.

Since:

1.6M2

beginTableHeadCell

void beginTableHeadCell(@Default(value="")@Name(value="parameters")
                        Map<String,String> parameters)

Start of a table head cell.

Parameters:

parameters - a generic list of parameters for the table head cell.

Since:

1.6M2

endTable

void endTable(@Default(value="")@Name(value="parameters")
              Map<String,String> parameters)

End of a table.

Parameters:

parameters - a generic list of parameters for the table.

Since:

1.6M2

endTableRow

void endTableRow(@Default(value="")@Name(value="parameters")
                 Map<String,String> parameters)

End of a table row.

Parameters:

parameters - a generic list of parameters for the table row.

Since:

1.6M2

endTableCell

void endTableCell(@Default(value="")@Name(value="parameters")
                  Map<String,String> parameters)

End of a table cell.

Parameters:

parameters - a generic list of parameters for the table cell.

Since:

1.6M2

endTableHeadCell

void endTableHeadCell(@Default(value="")@Name(value="parameters")
                      Map<String,String> parameters)

End of a table head cell.

Parameters:

parameters - a generic list of parameters for the table head cell.

Since:

1.6M2

beginSection

void beginSection(@Default(value="")@Name(value="parameters")
                  Map<String,String> parameters)

Start of a section.

Parameters:

parameters - a generic list of parameters. Example: style="background-color: blue"

See Also:

HeaderLevel

endSection

void endSection(@Default(value="")@Name(value="parameters")
                Map<String,String> parameters)

End of a section.

Parameters:

parameters - a generic list of parameters. Example: style="background-color: blue"

See Also:

HeaderLevel

beginHeader

void beginHeader(@Default(value="1")@Name(value="level")
                 HeaderLevel level,
                 @Name(value="id")
                 String id,
                 @Default(value="")@Name(value="parameters")
                 Map<String,String> parameters)

Start of a header.

Parameters:

level - the header level (1, 2, 3, etc)

id - the header unique identifier

parameters - a generic list of parameters. Example: style="background-color: blue"

Since:

1.9M1

See Also:

HeaderLevel

endHeader

void endHeader(@Default(value="1")@Name(value="level")
               HeaderLevel level,
               @Name(value="id")
               String id,
               @Default(value="")@Name(value="parameters")
               Map<String,String> parameters)

End of a header.

Parameters:

level - the header level (1, 2, 3, etc)

id - the header unique identifier

parameters - a generic list of parameters. Example: style="background-color: blue"

Since:

1.9M1

See Also:

HeaderLevel

beginMacroMarker

void beginMacroMarker(@Name(value="name")
                      String name,
                      @Default(value="")@Name(value="parameters")
                      Map<String,String> macroParameters,
                      @Name(value="content")
                      String content,
                      @Name(value="inline")
                      boolean isInline)

Start of marker containing a macro definition. This is a special that Macro Blocks emits when they are executed so that it's possible to reconstruct the initial macro syntax even after Macros have been executed. This is used for exemple by the WYSIWYG editor to let use see the result of executing a macro and still let them modify the macro definition.

Parameters:

name - the macro name

macroParameters - the macro parameters

content - the macro content

isInline - if true the macro is located in a inline content (like paragraph, etc.)

See Also:

onMacro(String, java.util.Map, String, boolean)

endMacroMarker

void endMacroMarker(@Name(value="name")
                    String name,
                    @Default(value="")@Name(value="parameters")
                    Map<String,String> macroParameters,
                    @Name(value="content")
                    String content,
                    @Name(value="inline")
                    boolean isInline)

End of marker containing a macro definition.

Parameters:

name - the macro name

macroParameters - the macro parameters

content - the macro content

isInline - if true the macro is located in a inline content (like paragraph, etc.)

See Also:

beginMacroMarker(String, java.util.Map, String, boolean)

beginQuotation

void beginQuotation(@Default(value="")@Name(value="parameters")
                    Map<String,String> parameters)

Start of a quotation. There are one or several quotation lines inside a quotation block.

Parameters:

parameters - a generic list of parameters for the quotation. Example: "style"/"background-color: blue"

endQuotation

void endQuotation(@Default(value="")@Name(value="parameters")
                  Map<String,String> parameters)

End of a quotation.

Parameters:

parameters - a generic list of parameters for the quotation. Example: "style"/"background-color: blue"

beginQuotationLine

void beginQuotationLine()

Start of a quotation line. There can be several quotation lines in a quotation block.

endQuotationLine

void endQuotationLine()

End of a quotation line.

onNewLine

void onNewLine()

A new line or line break (it's up to the renderers to decide if it should be outputted as a new line or as a line break in the given syntax).

onMacro

void onMacro(@Name(value="id")
             String id,
             @Default(value="")@Name(value="parameters")
             Map<String,String> macroParameters,
             @Name(value="content")
             String content,
             @Name(value="inline")
             boolean isInline)

A Macro.

Parameters:

id - the macro id (eg "toc" for the TOC macro)

macroParameters - the macro parameters

content - the macro content

isInline - if true the macro is located in a inline content (like paragraph, etc.)

Since:

1.6M2

onWord

void onWord(@Name(value="word")
            String word)

A word. Note that sentences ar broken into different events: word events, special symbols events, space events, etc. This allows fine-grained actions for listeners.

Parameters:

word - the word encountered

onSpace

void onSpace()

A space.

onSpecialSymbol

void onSpecialSymbol(@Name(value="symbol")
                     char symbol)

A special symbol ("*", "<", ">", "=", quote, etc). Any non alpha numeric character is a special symbol.

Parameters:

symbol - the symbol encountered

onId

void onId(@Name(value="name")
          String name)

A reference/location in a page. In HTML for example this is called an Anchor. It allows pointing to that location, for example in links. Note that there is no wiki syntax for this in general and it's often generated by Macros (such as the TOC Macro).

Parameters:

name - the location name.

Since:

1.6M1

onHorizontalLine

void onHorizontalLine(@Default(value="")@Name(value="parameters")
                      Map<String,String> parameters)

Represents an horizontal line.

Parameters:

parameters - a generic list of parameters. Example: style="background-color: blue"

Since:

1.6M1

onEmptyLines

void onEmptyLines(@Default(value="1")@Name(value="count")
                  int count)

Represents an empty line between 2 standalone Blocks. A standalone block is block that is not included in another block. Standalone blocks are Paragraph, Standalone Macro, Lists, Table, etc.

Parameters:

count - the number of empty lines between 2 standalone Blocks

onVerbatim

void onVerbatim(@Name(value="content")
                String protectedString,
                @Name(value="inline")
                boolean isInline,
                @Default(value="")@Name(value="parameters")
                Map<String,String> parameters)

A portion of text.

Parameters:

protectedString - the string to protected from rendering

isInline - if true the text content is located in a inline content (like paragraph, etc.)

parameters - a generic list of parameters. Example: style="background-color: blue"

onRawText

void onRawText(@Name(value="content")
               String rawContent,
               @Name(value="syntax")
               Syntax syntax)

Some text to inject directly into the listener output without parsing it. For example a HTML macro could inject directly some HTML entered by the user into the rendered HTML output. Note that it's not recommended to use this event in most cases since it can lead to invalid content being generated and in addition most listener implementations will not understand the injected text and will just ignore it.

Parameters:

rawContent - the text to inject

syntax - the syntax in which the text is written. This is useful so that listener implementations can decide whether they can handle direct inject for that syntax