General Actions:
Changes for document Writing a Macro
Last modified by Manuel Smeria on 2013/02/20 08:15
From version 12.1
edited by Vincent Massol
on 2012/03/27 08:47
on 2012/03/27 08:47
To version 13.1
edited by Andreas Jonsson
on 2012/06/09 09:31
on 2012/06/09 09:31
Change comment: Added documentation on the transformationContextRestricted parameter.
Metadata changes
- Document author
- xwiki:XWiki.
ViAncdrentMasJonssoln
Content changes
| ... | ... | @@ -5,6 +5,7 @@ |
| 5 | 5 | This tutorial explains how to create an XWiki Rendering Macro in Java |
| 6 | 6 | |
| 7 | 7 | Pre-requisites: |
| 8 | + | |
| 8 | 8 | * You must be using JDK 1.5 or above. |
| 9 | 9 | * You must be using XWiki Rendering 3.0 or above. |
| 10 | 10 | * (optional) You need to have [[Maven installed>>http://maven.apache.org]] if you want to use the Maven Archetype we're offering to easily create Macro projects using Maven. |
| ... | ... | @@ -15,8 +15,9 @@ |
| 15 | 15 | Start by understanding the [[Macro execution process>>Main.Architecture]]. |
| 16 | 16 | |
| 17 | 17 | In order to implement a new Macro you'll need to write 2 classes: |
| 19 | + | |
| 18 | 18 | * One that is a pure Java Bean and that represents the parameters allowed for that macro, including mandatory parameters, default values, parameter descriptions. An intance of this class will be automagically populated when the user calls the macro in wiki syntax. |
| 19 | -* Another one that is the Macro itself. This class should implement the ##Macro## interface. However we recommend extending ##AbstractMacro## which does some heavy lifting for you. By doing so you'll only have to implement 2 methods: |
|
| 21 | +* Another one that is the Macro itself. This class should implement the ##Macro## interface. However we recommend extending ##AbstractMacro## which does some heavy lifting for you. By doing so you'll only have to implement 2 methods:((( | |
| 20 | 20 | {{code language="java"}} |
| 21 | 21 | /** |
| 22 | 22 | * @return true if the macro can be inserted in some existing content such as a paragraph, a list item etc. For |
| ... | ... | @@ -45,6 +45,15 @@ |
| 45 | 45 | |
| 46 | 46 | In addition you can register your Macro for all syntaxes or only for a given syntax. In order to register only for a given syntax you must use a hint in the format ##macroname/syntaxid##. For example: ##mymacro/xwiki/2.0##. |
| 47 | 47 | |
| 50 | +== Security considerations == | |
| 51 | + | |
| 52 | +The macro transformation context contains the parameter ##transformationContextRestricted##. When set, this parameter indicates that rendering is performed in a context where: | |
| 53 | + | |
| 54 | +* modifications to the database or other privileged operations should not be performed and | |
| 55 | +* expensive computations should not be performed. | |
| 56 | + | |
| 57 | +Your macro should respect this parameter and either not execute at all or execute in a restricted mode if the above is a concern for your macro. | |
| 58 | + | |
| 48 | 48 | = Implementing a Macro = |
| 49 | 49 | |
| 50 | 50 | Here are detailed steps explaining how you can create a macro and deploy it. |
| ... | ... | @@ -54,9 +54,7 @@ |
| 54 | 54 | In order for this job to go as smooth as possible we have created a [[Maven Archetype>>http://maven.apache.org/plugins/maven-archetype-plugin/]] to help you create a simple macro module with a single command. |
| 55 | 55 | |
| 56 | 56 | After you've [[installed Maven>>http://maven.apache.org]], open a shell prompt an type: |
| 57 | -{{code language="none"}} | |
| 58 | -mvn archetype:generate | |
| 59 | -{{/code}} | |
| 68 | +{{code language="none"}}mvn archetype:generate{{/code}} | |
| 60 | 60 | |
| 61 | 61 | This will list all archetypes available on Maven Central. If instead you wish to directly use the XWiki Rendering Macro Archetype, you can directly type (update the version to use the version you wish to use): |
| 62 | 62 | |
| ... | ... | @@ -327,13 +327,12 @@ |
| 327 | 327 | = Deploying the Macro = |
| 328 | 328 | |
| 329 | 329 | Now that we have a functioning Macro let's build it and deploy it: |
| 339 | + | |
| 330 | 330 | * To build the macro issue ##mvn install##. This generates a Macro JAR in the ##target## directory of your project. |
| 331 | 331 | * To use it simply make that JAR available in your runtime classpath |
| 332 | 332 | |
| 333 | 333 | You can now use the following as an input to the XWiki Rendering Parser: |
| 334 | -{{code language="none"}} | |
| 335 | -{{example parameter="hello"/}} | |
| 336 | -{{/code}} | |
| 344 | +{{code language="none"}}{{example parameter="hello"/}}{{/code}} | |
| 337 | 337 | |
| 338 | 338 | Enjoy! |
| 339 | 339 |