Rendering Module

Last modified by Manuel Leduc on 2024/07/05 14:20

cogProvides API to convert textual inputs in a given syntax into some rendered output
TypeJAR
Category
Developed by

XWiki Development Team

Rating
LicenseGNU 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)
}

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)

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

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

Get Connected