Rendering Module
Last modified by Manuel Leduc on 2024/07/05 14:20
 | Provides API to convert textual inputs in a given syntax into some rendered output |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Description
XWiki Rendering is a a generic library on its own that can be used without using XWiki Platform.
XWiki Platform adds some features, for example it adds a Script Service to make it easy to access Rendering APIs from script.
Rendering Script Service
/**
* @return the list of syntaxes for which a Parser is available
*/
public List<Syntax> getAvailableParserSyntaxes()
/**
* @return the list of syntaxes for which a Renderer is available
*/
public List<Syntax> getAvailableRendererSyntaxes()
/**
* @return the names of Transformations that are configured in the Rendering Configuration and which are used by
* the Transformation Manager when running all transformations
*/
public List<String> getDefaultTransformationNames()
/**
* Parses a text written in the passed syntax.
*
* @param text the text to parse
* @param syntaxId the id of the syntax in which the text is written in
* @return the XDOM representing the AST of the parsed text or null if an error occurred
* @since 3.2M3
*/
public XDOM parse(String text, String syntaxId)
/**
* Render a list of Blocks into the passed syntax.
*
* @param block the block to render
* @param outputSyntaxId the syntax in which to render the blocks
* @return the string representing the passed blocks in the passed syntax or null if an error occurred
* @since 3.2M3
*/
public String render(Block block, String outputSyntaxId)
/**
* Converts a Syntax specified as a String into a proper Syntax object.
*
* @param syntaxId the syntax as a string (eg "xwiki/2.0", "html/4.01", etc)
* @return the proper Syntax object representing the passed syntax
*/
public Syntax resolveSyntax(String syntaxId)
/**
* Escapes a give text using the escaping method specific to the given syntax.
* <p/>
* One example of escaping method is using escape characters like {@code ~} for the {@link Syntax#XWIKI_2_1} syntax
* on all or just some characters of the given text.
* <p/>
* The current implementation only escapes XWiki 1.0, 2.0 and 2.1 syntaxes.
*
* @param content the text to escape
* @param syntax the syntax to escape the content in (e.g. {@link Syntax#XWIKI_1_0}, {@link Syntax#XWIKI_2_0},
* {@link Syntax#XWIKI_2_1}, etc.). This is the syntax where the output will be used and not necessarily
* the same syntax of the input content
* @return the escaped text or {@code null} if the given content or the given syntax are {@code null}, or if the
* syntax is not supported
* @since 7.1M1
*/
public String escape(String content, Syntax syntax)
/**
* @param syntax the syntax for which to return the list of Macro descriptors
* @return the macro descriptors for the macros registered and available to the passed syntax
* @throws MacroLookupException if a macro component descriptor cannot be loaded
* @since 9.7RC1
*/
public List<MacroDescriptor> getMacroDescriptors(Syntax syntax) throws MacroLookupException
/**
* @param macroIdAsString a string representing a macro id
* @return the resolved macro id or {@code null} if resolving the given string fails
* @since 10.10RC1
*/
public MacroId resolveMacroId(String macroIdAsString)
/**
* @param macroId the macro id
* @return the descriptor of the specified macro if it exists, {@code null} otherwise
* @since 10.10RC1
*/
public MacroDescriptor getMacroDescriptor(MacroId macroId)
/**
* Return the list of categories of a given macro.
*
* @param macroId the macro id
* @return the list of categories of the macro
* @since 14.6RC1
*/
public Set<String> getMacroCategories(MacroId macroId)
}
* @return the list of syntaxes for which a Parser is available
*/
public List<Syntax> getAvailableParserSyntaxes()
/**
* @return the list of syntaxes for which a Renderer is available
*/
public List<Syntax> getAvailableRendererSyntaxes()
/**
* @return the names of Transformations that are configured in the Rendering Configuration and which are used by
* the Transformation Manager when running all transformations
*/
public List<String> getDefaultTransformationNames()
/**
* Parses a text written in the passed syntax.
*
* @param text the text to parse
* @param syntaxId the id of the syntax in which the text is written in
* @return the XDOM representing the AST of the parsed text or null if an error occurred
* @since 3.2M3
*/
public XDOM parse(String text, String syntaxId)
/**
* Render a list of Blocks into the passed syntax.
*
* @param block the block to render
* @param outputSyntaxId the syntax in which to render the blocks
* @return the string representing the passed blocks in the passed syntax or null if an error occurred
* @since 3.2M3
*/
public String render(Block block, String outputSyntaxId)
/**
* Converts a Syntax specified as a String into a proper Syntax object.
*
* @param syntaxId the syntax as a string (eg "xwiki/2.0", "html/4.01", etc)
* @return the proper Syntax object representing the passed syntax
*/
public Syntax resolveSyntax(String syntaxId)
/**
* Escapes a give text using the escaping method specific to the given syntax.
* <p/>
* One example of escaping method is using escape characters like {@code ~} for the {@link Syntax#XWIKI_2_1} syntax
* on all or just some characters of the given text.
* <p/>
* The current implementation only escapes XWiki 1.0, 2.0 and 2.1 syntaxes.
*
* @param content the text to escape
* @param syntax the syntax to escape the content in (e.g. {@link Syntax#XWIKI_1_0}, {@link Syntax#XWIKI_2_0},
* {@link Syntax#XWIKI_2_1}, etc.). This is the syntax where the output will be used and not necessarily
* the same syntax of the input content
* @return the escaped text or {@code null} if the given content or the given syntax are {@code null}, or if the
* syntax is not supported
* @since 7.1M1
*/
public String escape(String content, Syntax syntax)
/**
* @param syntax the syntax for which to return the list of Macro descriptors
* @return the macro descriptors for the macros registered and available to the passed syntax
* @throws MacroLookupException if a macro component descriptor cannot be loaded
* @since 9.7RC1
*/
public List<MacroDescriptor> getMacroDescriptors(Syntax syntax) throws MacroLookupException
/**
* @param macroIdAsString a string representing a macro id
* @return the resolved macro id or {@code null} if resolving the given string fails
* @since 10.10RC1
*/
public MacroId resolveMacroId(String macroIdAsString)
/**
* @param macroId the macro id
* @return the descriptor of the specified macro if it exists, {@code null} otherwise
* @since 10.10RC1
*/
public MacroDescriptor getMacroDescriptor(MacroId macroId)
/**
* Return the list of categories of a given macro.
*
* @param macroId the macro id
* @return the list of categories of the macro
* @since 14.6RC1
*/
public Set<String> getMacroCategories(MacroId macroId)
}
XWiki <14.6
XWiki 13.10.8+, 14.4.3+
/**
* Return the category of the macro, possibly overridden.
*
* @param macroId the macro id
* @return the category
* @since 13.10.8
* @since 14.4.3
*/
public String getMacroCategory(MacroId macroId)
* Return the category of the macro, possibly overridden.
*
* @param macroId the macro id
* @return the category
* @since 13.10.8
* @since 14.4.3
*/
public String getMacroCategory(MacroId macroId)
For example to parse some content in HTML and then render it in XWiki Syntax 2.1 from Velocity you would write:
{{velocity}}
#set ($xdom = $services.rendering.parse("<p>some <b>bold</b></p>", "xhtml/1.0"))
#set ($xwikiSyntax = $services.rendering.render($xdom, "xwiki/2.1"))
{{{$xwikiSyntax}}}
{{/velocity}}
#set ($xdom = $services.rendering.parse("<p>some <b>bold</b></p>", "xhtml/1.0"))
#set ($xwikiSyntax = $services.rendering.render($xdom, "xwiki/2.1"))
{{{$xwikiSyntax}}}
{{/velocity}}
Asynchronous rendering
See Async.
Rendering APIs
XWiki 15.3+
Listeners
It is possible to dynamically provide a listener from an extension by defining a ListenerProvider components.
The listener are currently injected at the beginning of the chain in an undetermined order.
@Role
@Unstable
public interface ListenerProvider
{
/**
* Parse action identifier.
*/
String PARSE_ACTION = "parse";
/**
* Render action identifier.
*/
String RENDER_ACTION = "render";
/**
* @param action the action performed by the listener ("render" or "parse")
* @param syntax the hint of the syntax using for the action
* @return {@code true} when the listener provider can return a listener for the given action and syntaxHint
*/
boolean accept(String action, Syntax syntax);
/**
* @param listenerChain the listener chain in which the listener will be included
* @return the listener to add to the listener chain
*/
ChainingListener getListener(ListenerChain listenerChain);
}
@Unstable
public interface ListenerProvider
{
/**
* Parse action identifier.
*/
String PARSE_ACTION = "parse";
/**
* Render action identifier.
*/
String RENDER_ACTION = "render";
/**
* @param action the action performed by the listener ("render" or "parse")
* @param syntax the hint of the syntax using for the action
* @return {@code true} when the listener provider can return a listener for the given action and syntaxHint
*/
boolean accept(String action, Syntax syntax);
/**
* @param listenerChain the listener chain in which the listener will be included
* @return the listener to add to the listener chain
*/
ChainingListener getListener(ListenerChain listenerChain);
}
