Provides API to convert textual inputs in a given syntax into some rendered output

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)

    /**
     * Create a new transformation context.
     *
     * @return a new transformation context
     * @since 18.1.0RC1
     */
    public XWikiTransformationContext createTransformationContext()

    /**
     * Performs transformations on the passed block using the passed transformation context. Requires programming rights.
     * 
     * @param block the block on which to perform the transformations
     * @param transformationContext the context in which to perform the transformations
     * @since 18.1.0RC1
     */
    public void transform(Block block, XWikiTransformationContext transformationContext) throws TransformationException

    /**
     * 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)
}

Script examples

Parse some content in HTML and then render it in XWiki Syntax 2.1

{{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}}

List available renderer syntaxes

{{velocity}}
#foreach ($syntax in $services.rendering.availableRendererSyntaxes)
  * $syntax ($syntax.type.toIdString() / $syntax.version)
#end
{{/velocity}}

Asynchronous rendering

See Async.

Rendering APIs

@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);
}