Rendering Module

Version 78.1 by Manuel Leduc on 2023/04/17 10:58
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

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

XWiki Development Team

Rating
0 Votes
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 Unknown macro: ListenerProvider. Click on this message for details.

Get Connected