Play2 XWiki Rendering Module

Introduction

This Play2 module allows you to convert texts written in a certain wiki syntax to some formatted texts using XWiki Rendering Framework.

Example

val result = DefaultXWikiRenderer.render("** Bold ** {{code type="java"}}class Macro{}{{/code}}")
// <p><b>Bold</b><pre class="java">class Macro{}</pre></p>

There is a sample application at the project repository.
And the api documents are here.

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

Installing the module

To use the module, a repository and dependency should be added to your project/Build.scala

Repository: http://repository-monochromeroad.forge.cloudbees.com/release
Dependency: "com.monochromeroad" %% "play-xwiki-rendering" % "1.0"

object ApplicationBuild extends Build {

  val appName         = "Sample application integrated with XWiki Rendering"
  val appVersion      = "1.0"

  val appDependencies = Seq(
    "com.monochromeroad" %% "play-xwiki-rendering" % "1.0"
  )

  val main = PlayProject(appName, appVersion, appDependencies, mainLang = SCALA).settings(
    resolvers += "Monochrmeroad CloudBees Repository" at "http://repository-monochromeroad.forge.cloudbees.com/release"
  )
}

Default XWiki renderer

This moudle provides some XWiki rendereres as a Play plugin.

DefaultXWikiRenderer: XDOM based renderer
DefaultXWikiStreamRenderer: Streaming based renderer
DefaultXWikiStringStreamRenderer: Simplified streaming based renderer

Installing the default renderers

Just add a entry to the "plugins.sbt" in the conf directory.

10000:com.monochromeroad.play.xwiki.rendering.plugin.DefaultXWikiRenderingPlugin

DefaultXWikiRenderer

import com.monochromeroad.play.xwiki.rendering.plugin.{DefaultXWikiRenderer => Renderer}
object Application extends Controller {

  def index = Action {
    val htmlText = Renderer.render("**TEST** //italic//")

    // ...
  }
}

DefaultXWikiStreamRenderer

import java.io.StringReader
import com.monochromeroad.play.xwiki.rendering.plugin.{DefaultXWikiStreamRenderer => Renderer}
object Application extends Controller {

  def index = Action {
    val sourceReader = new StringReader("**TEST** //italic//")
    val htmlText = Renderer.render(sourceReader, "-- iv --", (acc: String, n: String) => acc + n)

    // ...
  }
}

DefaultXWikiStringStreamRenderer

import java.io.StringReader
import com.monochromeroad.play.xwiki.rendering.plugin.{DefaultXWikiStringStreamRenderer => Renderer}
object Application extends Controller {

  def index = Action {
    val sourceReader = new StringReader("**TEST** //italic//")
    val result = new StringBuilder()
    Renderer.render(sourceReader, result.append(_))

    // ...
  }
}

Macros

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

import com.monochromeroad.play.xwiki.rendering.plugin.{DefaultXWikiRenderer => Renderer}
object Application extends Controller {

  def index = Action {
    val htmlText = Renderer.render("**TEST** {{comment}}This is a comment that would not be contained in the result{{/comment}}")
    // Comment Macro: <p><b>TEST</b> </p>

    // ...
  }
}

To use a XWiki macro, add a macro jar to your project or register a macro source code.

Adding a macro jar

Just add the macro jar you want to use in the project.

val appDependencies = Seq(
  "org.xwiki.rendering" % "xwiki-rendering-macro-comment" % "4.1.3"
)

Registering a macro code

First, write a macro class that extends DefaultXWikiMacro or DefaultXWikiNoParameterMacro
You need to create the class with a nullary constructor.

Check out the sample macro code for more details.

Then regster the macro class in the conf/application.conf

xwiki.rendering.default.macros.1=utils.xwiki.macros.CodeMacro

When you create your own macro, the XWiki site document would be useful:
Writing a Macro

License

LGPL Version 2.1