Rendering Module

Version 73.1 by Vincent Massol on 2021/03/17 20:40

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

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:

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

Tags: development
    

Get Connected