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

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager


Starting with XWiki Platform 3.0 the Rendering module has been extracted out of XWiki Platform and is now 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 (requires XWiki 2.3M1+) 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)

For example to parse some content in HTML and then render it in XWiki Syntax 2.1 from Velocity you would write:

#set ($xdom = $services.rendering.parse("<p>some <b>bold</b></p>", "xhtml/1.0"))
#set ($xwikiSyntax = $services.rendering.render($xdom, "xwiki/2.1"))

Asynchronous rendering

See Async.

Tags: development
Created by Thomas Mortagne on 2018/12/17 15:19

Get Connected