Wiki Transformation Application
 | Contrib extension which depends on xwiki-platform |
| Type | XAR |
| Category | Application |
| Developed by | |
| Active Installs | 1 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
Transformation allowing to declare in-wiki transformations at runtime.
General information
The wiki transformation application allows to define transformation that can be created an configured directly in XWiki. The application comes in two parts :
- A generic API module, with the necessary plumbing to create new transformation that can be configured directly in XWiki ;
- A module for transformations that are bundled by default with the application.
A wiki transformation is materialized in XWiki as an XClass, which contains all the properties needed to declare a transformation.
Default transformation parameters
The following parameters come by default with each wiki transformation.
| Name | Description | Default value | Mandatory | Available since |
|---|---|---|---|---|
| ID | The ID of the transformation | N/A | Yes | 1.0 |
| Template | The template to execute for the transformation | N/A | Yes | 1.0 |
Template
The transformation template is rendered whenever a transformation is to be executed in a part of an XDOM. The template will be parsed using the xwiki/2.1 syntax parser, and can contain calls to other macros, including script macros.
As part of this template, a binding transformation is exposed, to get information about the matched block and set the result of the transformation.
The transformation binding
The binding transformation allows to control the output of the transformation in the template. This binding can be enhanced by the wiki transformations.
| Method name | Description | Available since |
|---|---|---|
| getBlock() | Returns the matched block | 1.0 |
| getTransformationContext() | Returns the current transformation context | 1.0 |
| setResult() | Set the result of the transformation | 1.0 |
| getResult() | Returns the result of the transformation | 1.0 |
Supported transformations
Pattern transformation
The pattern transformation will work by taking a pattern and matching it to the XDOM being transformed. In order to match a set of XDOM Blocks without having to render their contents, this transformation uses its own pattern syntax described in the section below.
To create a new pattern transformation, use an object of class Transformation.Code.PatternWikiTransformationClass.
Parameters
| Name | Description | Default value | Mandatory | Available since |
|---|---|---|---|---|
| Pattern | The pattern to apply for matching the XDOM blocks | N/A | Yes | 1.0 |
Pattern
The pattern used to match the XDOM blocks to transform should be of the following
- If a word is to be matched, then the match should be in the form of a regex to apply to the word. The regex should start with a ^ and end with an $.
- If a space is to be matched, you should put a space character (U+0020) in the pattern.
- If a special symbol is to be matched, you should put the special symbol in the pattern, or use ? to match any symbol.
- To match the symbol ?, escape it with \.
Examples
- The pattern ^([a-zA-Z]+)$-^([0-9]+)$ will match JIRA-like issue IDs such as XWIKI-1234
- The pattern #^([0-9]+)$ will match GitLab-like issue IDs such as #42
Extra bindings
The pattern transformation comes with two additional bindings which allow to get more information about the match.
| Method name | Link to the class | Description | Available since |
|---|---|---|---|
| getPattern() | Pattern | The pattern used to match the blocks | 1.0 |
| getMatcher() | Matcher | The result of the match with the pattern and the blocks | 1.0 |
Use transformation.getMatcher().getMatchedBlocks() to get an ordered list of matched blocks for the transformation. You can also use transformation.getMatcher().getMatchedString() to directly get a string representation of the match.
To get the results of a capturing group in one of the regex declared in the pattern, use transformation.getMatcher().getMatchResult(<the block that matches>).getMatcher().group(<the number of the capturing group>).
Examples
Since 1.1, you can install the package org.xwiki.contrib.transformation.wiki:application-wiki-transformation-help in the same version as the application in order to get some examples of the possible wiki transfomations. Note that it is not recommended to install this package in a production environment, as the wiki transformation it defines will have a negative impact on the rendering time of the wiki pages.
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). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Versions
Dependencies
Dependencies for this extension (org.xwiki.contrib.transformation.wiki:application-wiki-transformation-ui 1.1):
- org.xwiki.contrib.transformation.wiki:application-wiki-transformation-transformation-pattern 1.1
