Listener (XWiki Rendering - Api 8.1-milestone-1 API)

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: a692de2f463d7b780307d5cfee89a1c793ec92f3 $

Field Summary

Fields
Modifier and Type Field and Description

static Map<String,String> EMPTY_PARAMETERS
To use when there is no parameters.

Fields
Modifier and Type	Field and Description
`static Map<String,String>`	`EMPTY_PARAMETERS` To use when there is no parameters.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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,
             @Default(value="") @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

Interface Listener

Field Summary

Method Summary

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

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

Field Detail

EMPTY_PARAMETERS

Method Detail

beginDocument

endDocument

beginMetaData

endMetaData

beginGroup

endGroup

beginFormat

endFormat

beginParagraph

endParagraph

beginList

beginDefinitionList

endList

endDefinitionList

beginListItem

beginDefinitionTerm

beginDefinitionDescription

endListItem

endDefinitionTerm

endDefinitionDescription

beginTable

beginTableRow

beginTableCell

beginTableHeadCell

endTable

endTableRow

endTableCell

endTableHeadCell

beginSection

endSection

beginHeader

endHeader

beginMacroMarker

endMacroMarker

beginQuotation

endQuotation

beginQuotationLine

endQuotationLine

onNewLine

onMacro

onWord

onSpace

onSpecialSymbol

onId

onHorizontalLine

onEmptyLines

onVerbatim

onRawText