XWiki-specific Rendering API
Last modified by Admin on 2024/03/25 16:34
 | Adds XWiki-specific concepts to XWiki Rendering |
| Type | JAR |
| Category | API |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Description
Integration module for the XWiki Rendering framework inside XWiki Platform (i.e. adding concepts that don't exist in XWiki Rendering and that only concerns the XWiki wiki).
Script Service
@Component
@Named("rendering")
@Singleton
public class RenderingScriptService implements ScriptService
{
/**
* @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)
{
// ...
}
/**
* @return the list of Rendering Syntaxes that are configured for the current wiki (i.e. that are proposed to the
* user when editing wiki pages). These are input Syntaxes only (i.e. Syntaxes having a Parser for them).
* @since 8.2M1
*/
public List<Syntax> getConfiguredSyntaxes()
{
// ...
}
/**
* @return the list of Rendering Syntaxes that are disabled for the current wiki (i.e. that should not be proposed
* to the user when editing wiki pages)
* @since 8.2M1
*/
public List<Syntax> getDisabledSyntaxes()
{
// ...
}
/**
* @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
*/
@Unstable
public Set<String> getMacroCategories(MacroId macroId)
{
// ...
}
}
@Named("rendering")
@Singleton
public class RenderingScriptService implements ScriptService
{
/**
* @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)
{
// ...
}
/**
* @return the list of Rendering Syntaxes that are configured for the current wiki (i.e. that are proposed to the
* user when editing wiki pages). These are input Syntaxes only (i.e. Syntaxes having a Parser for them).
* @since 8.2M1
*/
public List<Syntax> getConfiguredSyntaxes()
{
// ...
}
/**
* @return the list of Rendering Syntaxes that are disabled for the current wiki (i.e. that should not be proposed
* to the user when editing wiki pages)
* @since 8.2M1
*/
public List<Syntax> getDisabledSyntaxes()
{
// ...
}
/**
* @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
*/
@Unstable
public Set<String> getMacroCategories(MacroId macroId)
{
// ...
}
}
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-rendering-xwiki 16.2.0):
- org.xwiki.platform:xwiki-platform-rendering-configuration-api 16.2.0
- org.xwiki.platform:xwiki-platform-template-api 16.2.0
- org.xwiki.platform:xwiki-platform-bridge 16.2.0
- org.xwiki.platform:xwiki-platform-security-requiredrights-macro 16.2.0
- org.xwiki.commons:xwiki-commons-script 16.2.0
- net.sourceforge.cssparser:cssparser 0.9.30
- org.apache.httpcomponents:httpclient 4.5.14
- org.xwiki.rendering:xwiki-rendering-api 16.2.0
- org.xwiki.rendering:xwiki-rendering-transformation-macro 16.2.0
