Last modified by Simon Urli on 2023/10/10

From version 119.2
edited by Vincent Massol
on 2021/02/15
Change comment: There is no comment for this version
To version 122.2
edited by Michael Hamann
on 2022/06/28
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.MichaelHamann
Content
... ... @@ -12,7 +12,7 @@
12 12  
13 13  == Definition ==
14 14  
15 -Wiki macros are defined using objects of type ##XWiki.WikiMacroClass##. You define a wiki macro by creating a new wiki page and attaching to it an object of type ##XWiki.WikiMacroClass##.
15 +Wiki macros are defined using objects of type ##XWiki.WikiMacroClass##. You define a wiki macro by creating a new wiki page and attaching to it an object of type ##XWiki.WikiMacroClass##. You will need to [[be advanced>>Documentation.UserGuide.Features.PageEditing||anchor="HAdvancedProfile"]] to access the [[object editor>>Documentation.UserGuide.Features.PageEditing||anchor="HObjectseditingmode"]].
16 16  
17 17  {{warning}}
18 18  There can be only one object of type ##XWiki.WikiMacroClass## per wiki page (if you add more only the first will be used).
... ... @@ -51,20 +51,13 @@
51 51  == Content ==
52 52  
53 53  {{version since="11.4RC1"}}
54 -There are two ways to insert the content of the wiki macro.
54 +The easiest way to insert the content of the wiki macro is to use a dedicated macro in the body of the wikimacro:
55 55  
56 -* The easiest way is to use a dedicated macro in the body of the wikimacro:(((
57 57  {{code language='none'}}
58 58  {{wikimacrocontent/}}
59 59  {{/code}}
60 60  
61 61  Note that by default this makes the content of the macro directly editable in [[the WYSIWYG editor>>https://extensions.xwiki.org/xwiki/bin/view/Extension/CKEditor%20Integration/#HWikiMacros]].
62 -)))
63 -* Another way to manipulate the content is to use the wikimacro binding. For example, when using Velocity, you can write the following script in the macro body:(((
64 -{{code language='none'}}
65 -{{velocity}}$wikimacro.content{{/velocity}}
66 -{{/code}}
67 -)))
68 68  {{/version}}
69 69  
70 70  For more details, see the [[Scripting Tips section below>>||anchor="HScriptingTips"]].
... ... @@ -78,7 +78,7 @@
78 78  * Parameter mandatory: Indicates if this particular parameter is mandatory, wiki macro will fail to execute if a mandatory parameter is missing
79 79  * {{version since="10.10"}}Parameter default value (optional): The default value of the parameter when it's empty{{/version}}
80 80  * {{version since="10.10"}}Parameter type (optional): Indicates to which Java type the parameter value (defined as a String) must be converted to (##java.lang.String## by default).{{/version}}
81 -** Example 1: ##java.awt.Color##. Will provie a Color Picker when the macro is edited in the WYSIWYG editor.
74 +** Example 1: ##java.awt.Color##. Will provide a Color Picker when the macro is edited in the WYSIWYG editor.
82 82  
83 83  Now we're going to extend our **hello macro** with a parameter. We will introduce a parameter named //greetUser// that will indicate if the greeting message should be tailored for the current user viewing the page. The definition of the parameter is shown below:
84 84  
... ... @@ -89,7 +89,7 @@
89 89  {{code language="none"}}
90 90  {{velocity}}
91 91  #if ($wikimacro.parameters.greetUser && "XWiki.XWikiGuest" != "$xcontext.user")
92 - Hello $xwiki.user.email!
85 + Hello $services.rendering.escape($xwiki.user.email, 'xwiki/2.1')!
93 93  #else
94 94   Hello world!
95 95  #end
... ... @@ -99,7 +99,7 @@
99 99  As you might have realized already, direct binding of parameters is not supported at the moment. That is, you cannot access //greetUser// parameter with **$greetUser**. Instead you must use **$wikimacro.parameters.greetUser**. We plan to introduce some form of direct parameter binding in near future.
100 100  
101 101  Since {{info}}11.5RC1{{/info}}, it is also possible to display the content of a macro parameter by using a dedicated macro:
102 -{{code language="none"}}Hello {{wikimacroparameter name="greeUsers" /}}{{/code}}
95 +{{code language="none"}}Hello {{wikimacroparameter name="greetUsers" /}}{{/code}}
103 103  
104 104  Finally, we can test our new version of **hello macro** with the following invocation:
105 105  
... ... @@ -218,7 +218,7 @@
218 218  This text will not appear in the result.
219 219  {{/code}}
220 220  )))
221 -* If you are using ##$wikimacro.content## in your velocity macro, that content will not be able to support scripting, since nested scripting is not supported. To workaround that limitation, thanks to the above, you may do the parsing yourself using the rendering service. Here is a small sample:(((
214 +* If you need to directly access the parsed XDOM of the content you may do the parsing yourself using the rendering service. Here is a small sample:(((
222 222  {{code language="velocity"}}
223 223  {{velocity output="no"}}
224 224  ## get the macro content in a velocity string
... ... @@ -245,11 +245,11 @@
245 245  {{velocity}}
246 246  #set($greetUser=$xcontext.macro.params.greetUser)
247 247  #if ("true" == $greetUser && "XWiki.XWikiGuest" != "$xcontext.user" )
248 - Hello $xwiki.user.email!
241 + Hello $services.rendering.escape($xwiki.user.email, 'xwiki/2.1')!
249 249  #else
250 250   Hello world!
251 251  #end
252 -<img src="$image" width="$width" />
245 +{{/velocity}}
253 253  {{/code}}
254 254  
255 255  If we invoke it twice in a row:

Get Connected