(Quick Reference)

XWiki Rendering Plugin - Reference Documentation

Authors: Masatoshi Hayashi

Version: 1.0-RC2

1Introduction

1.1Migrating from version 0.1

2Configuration

2.1Supporeted Syntaxes

2.2Macros

3XWiki Macro

3.1Adding XWiki macro libraries

3.2Adding XWiki macro codes

4XWiki Transformation

1 Introduction

This Grails plugin allows you to convert texts using XWiki Rendering Framework.

class SomeController {    def xwikiRenderer
    def someAction = {
        String testString = """
        =level1=
        **bold**
        """
        String result = xwikiRenderer.render(textString)
        // <h1>level1</h1>
        // <p><b>bold</b></p>
        …
    }
}

See also XWiki Rendering Framework for the details about the framework.

1.1 Migrating from version 0.1

Removal of TagLib "xwikiRender"

Use xwiki:render tag instead.

Removal of Service "RenderingService"

Use xwikiRenderer service instead.

2 Configuration

XWiki Plugin's Configuration

2.1 Supporeted Syntaxes

XWiki has multiple Wiki Syntaxes Support.

Supported Syntaxes

If some syntaxes other than "XWiki 2.1" are needed, add a configuration as below in BuildConfig.groovy file.

// BuildConfig.groovy
grails.xwiki.rendering.syntaxes = "mediawiki, jspwiki" // XWiki Syntax Configurationgrails.project.dependency.resolution = {
    // …
}

Syntax	Configuration
Confluence	confluence
Creole	creole
DocBook	docbook
Doxia	doxia
JSPWiki	jspwiki
Markdown	markdown
Plain Text	plain
tex	tex
TWiki	twiki

2.2 Macros

XWiki macros is enabled in the plugin by default. To change this set the grails.xwiki.rendering.macros.enabled to true or false.

// Config.groovy
grails.xwiki.rendering.macros.enabled = false // default true
// ...

Available Macros

XWiki provides some macros officially.

If these macros are needed, add a configuration as below in BuildConfig.groovy file.

// BuildConfig.groovy
grails.xwiki.rendering.macros = "comment, box, toc, footnotes, html, id, message"grails.project.dependency.resolution = {
    // …
}

Macro	Configuration
Box	box
Comment	comment
Footnote	footnotes
HTML	html
Id	id
Info Message, Warning Message, Error Message	message
TOC	toc

3 XWiki Macro

You can use some XWiki macros to extend the wiki syntax.

<xwiki:render>
= Comment Macro DEMO =
{{comment}}
comment here...(not be rendered)
{{/comment}}
</xwiki:render>

There are some ways to add a XWiki Macro in your grails project.

Adding a configuration in BuildConfig.groovy in order to use XWiki official macros. See Configuration for the details.
Adding a library jar file of the XWiki Macro to your application (that is, edit "BuildConfig.groovy" or add a jar file to lib directory).
Adding a macro code to grails-app/xwiki directory in your application.

When you create your own macro, ExtendingMacro would be useful.

3.1 Adding XWiki macro libraries

Edit "BuildConfig.groovy" or add a jar file to lib directory to add a dependency to the macro.

grails-app/conf/BuildConfig.groovy

dependencies {
    …
    compile("com.example:xwiki-macro-xxx:xxx") // a macro jar
}

You can also add the macro library jar file into YOUR-GRAILS-PROJECT/lib directory.

3.2 Adding XWiki macro codes

Add a groovy class that extends DefaultXWikiMacro or DefaultXWikiNoParameterMacro to grails-app/xwiki directory in the grails project.

You need to create the class with a nullary constructor.

Check out the sample macro code for more details.

If you add the codes to grails-app/xwiki in your project, the macros can be used in this way:

<xwiki:render>
= Date Macro DEMO =
{{date /}}
</xwiki:render>

<xwiki:render>
= Code Macro DEMO =
{{code mode="java"}}
class TestClass {}
{{/code}}
</xwiki:render>

4 XWiki Transformation

XWiki Transfromation modefies some XDOM(AST representing the input) to generate modified XDOM.

See also XWiki Rendering Architecture for more details about XWiki Transformation.

In this Grails XWiki Rendering Plugin, xwikiRenderer and xwikiStreamRenderer services can take some XWiki Transformations.

Example

class TestTransformation extends AbstractTransformation {    def parameter
    public TestTransformation(parameter){
        this.parameter = parameter
    }
    public void transform(
            Block block, TransformationContext transformationContext) throws TransformationException {
        block.addChild(new RawBlock(parameter, Syntax.XHTML_1_0));
    }
}

and:

def transformation = new TestTransformation("test parameter")
def output = xwikiRenderer.render("** Source Text **", transformation)