Rendering Module

Last modified by Vincent Massol on 2017/07/22 10:44

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

XWiki Development Team

Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager

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 or XWiki Enterprise.

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

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</bold></p>", "html/4.01"))
#set ($xwikiSyntax = $services.rendering.render($xdom, "xwiki/2.1"))
{{{$xwikiSyntax}}}
{{/velocity}}
Tags: development
Created by VincentMassol on 2009/04/03 08:36
    

Get Connected