Package 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, SectionGeneratorListener, 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: a18ac6cb453fc36f33223cd64cad4f8c514f5474 $

  • Field Details

    • EMPTY_PARAMETERS

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

  • Method Details

    • beginDocument

      void beginDocument(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(MetaData metadata)
      End of the document.
      Parameters:
      metadata - the meta data associated with the previous events, see MetaData
      Since:
      3.0M2

    • beginMetaData

      void beginMetaData(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(MetaData metadata)
      End of MetaData.
      Parameters:
      metadata - the metadata
      Since:
      3.0M2

    • beginGroup

      void beginGroup(@Default("") 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("") 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("NONE") Format format, @Default("") 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:

    • endFormat

      void endFormat(@Default("NONE") Format format, @Default("") 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:

    • beginParagraph

      void beginParagraph(@Default("") Map<String,String> parameters)
      Start of a paragraph.
      Parameters:
      parameters - a generic list of parameters. Example: style="background-color: blue"

    • endParagraph

      void endParagraph(@Default("") Map<String,String> parameters)
      End of a paragraph.
      Parameters:
      parameters - a generic list of parameters. Example: style="background-color: blue"

    • beginList

      void beginList(@Default("BULLETED") ListType type, @Default("") Map<String,String> parameters)
      Start of a list.
      Parameters:
      type - the type of list (bulleted, numbered, etc)
      parameters - a generic list of parameters for the list. Example: "style"/"background-color: blue"
      See Also:

    • beginDefinitionList

      void beginDefinitionList(@Default("") 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("BULLETED") ListType type, @Default("") Map<String,String> parameters)
      End of a list.
      Parameters:
      type - the type of list (bulleted, numbered, etc)
      parameters - a generic list of parameters for the list. Example: "style"/"background-color: blue"
      See Also:

    • endDefinitionList

      void endDefinitionList(@Default("") 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.

    • beginListItem

      default void beginListItem(@Default("") Map<String,String> parameters)
      Start of a list item.
      Parameters:
      parameters - a generic list of parameters for the list item. Example: "style"/"background-color: blue"
      Since:
      10.0

    • 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.

    • endListItem

      default void endListItem(@Default("") Map<String,String> parameters)
      End of a list item.
      Parameters:
      parameters - a generic list of parameters for the list item. Example: "style"/"background-color: blue"
      Since:
      10.0

    • 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("") 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("") 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("") 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("") 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("") 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("") 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("") 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("") 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("") Map<String,String> parameters)
      Start of a section.
      Parameters:
      parameters - a generic list of parameters. Example: style="background-color: blue"
      See Also:

    • endSection

      void endSection(@Default("") Map<String,String> parameters)
      End of a section.
      Parameters:
      parameters - a generic list of parameters. Example: style="background-color: blue"
      See Also:

    • beginHeader

      void beginHeader(@Default("1") HeaderLevel level, String id, @Default("") 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:

    • endHeader

      void endHeader(@Default("1") HeaderLevel level, String id, @Default("") 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:

    • beginMacroMarker

      void beginMacroMarker(String name, @Default("") Map<String,String> parameters, String content, boolean inline)
      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
      parameters - the macro parameters
      content - the macro content
      inline - if true the macro is located in a inline content (like paragraph, etc.)
      See Also:

    • endMacroMarker

      void endMacroMarker(String name, @Default("") Map<String,String> parameters, String content, boolean inline)
      End of marker containing a macro definition.
      Parameters:
      name - the macro name
      parameters - the macro parameters
      content - the macro content
      inline - if true the macro is located in a inline content (like paragraph, etc.)
      See Also:

    • beginQuotation

      void beginQuotation(@Default("") 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("") 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.

    • beginFigure

      default void beginFigure(Map<String,String> parameters)
      Start of a figure.
      Parameters:
      parameters - a generic list of parameters for the figure
      Since:
      10.2

    • endFigure

      default void endFigure(Map<String,String> parameters)
      End of a figure.
      Parameters:
      parameters - a generic list of parameters for the figure
      Since:
      10.2

    • beginFigureCaption

      default void beginFigureCaption(Map<String,String> parameters)
      Start of a figure caption.
      Parameters:
      parameters - a generic list of parameters for the figure
      Since:
      10.2

    • endFigureCaption

      default void endFigureCaption(Map<String,String> parameters)
      End of a figure caption.
      Parameters:
      parameters - a generic list of parameters for the figure
      Since:
      10.2

    • 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(String id, @Default("") Map<String,String> parameters, String content, @Name("inline") boolean inline)
      A Macro.
      Parameters:
      id - the macro id (eg "toc" for the TOC macro)
      parameters - the macro parameters
      content - the macro content
      inline - if true the macro is located in a inline content (like paragraph, etc.)
      Since:
      1.6M2

    • onWord

      void onWord(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(char symbol)
      A special symbol (*, <, >, =, quote, etc). Any non alpha numeric character is a special symbol.
      Parameters:
      symbol - the symbol encountered

    • onId

      void onId(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("") 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("1") 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("content") String content, boolean inline, @Default("") Map<String,String> parameters)
      A portion of text.
      Parameters:
      content - the string to protected from rendering
      inline - 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("content") String content, 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:
      content - 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