Last modified by Simon Urli on 2023/10/10

From version 120.1
edited by Thomas Mortagne
on 2022/01/04
Change comment: There is no comment for this version
To version 125.1
edited by Manuel Leduc
on 2022/07/11
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ThomasMortagne
1 +XWiki.mleduc
Content
... ... @@ -23,7 +23,7 @@
23 23  * **Macro id**: Id of the macro to be used by users when invoking your macro from wiki code
24 24  * **Macro name**: Name of the macro to be displayed on the wysiwyg editor
25 25  * **Macro description**: A short description of the macro to be displayed on the WYSIWYG editor
26 -* **Default category**: Default category under which this macro should be listed
26 +* **Default categories**: Default categories under which this macro should be listed {{warning}}before 14.4RC1 this was called **Default category**{{/warning}}
27 27  * **Supports inline mode**: Whether the macro can be used in an inline context or not
28 28  * **Macro Content availability**: {{warning}}before 11.5RC1 this was called **Macro Content Type**{{/warning}} whether this macro should support a body or not
29 29  * **Macro content type**: {{warning}}this field has been renamed **Macro Content Availability** since 11.5RC1{{/warning}} the type of accepted content: two values are proposed, ##WIKI## if this content should be editable like a wiki content, or ##UNKNOWN## if it should be displayed like a plain text. It's also possible to specify a custom java type such as {{code language="java"}}java.util.List<java.lang.String>{{/code}}. Leaving the field blank is equivalent to ##UNKWOWN## value.
... ... @@ -36,11 +36,11 @@
36 36  
37 37  Now we can define our hello macro as shown below:
38 38  
39 -{{image reference="macro1.png"/}}
39 +{{image reference="macro1.png" width="650px"/}}
40 40  
41 41  == Invocation ==
42 42  
43 -A wiki macro can be invoked just like any other macro is invoked. Since we are writing a xwiki/2.0 wiki macro, we can invoke our **hello macro** as below:
43 +A wiki macro can be invoked just like any other macro is invoked. Since we are writing a xwiki/2.1 wiki macro, we can invoke our **hello macro** as below:
44 44  
45 45  {{code language="none"}}
46 46  {{hello/}}
... ... @@ -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"]].
... ... @@ -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  
... ... @@ -155,15 +155,15 @@
155 155  
156 156  = Bindings =
157 157  
158 -See all availalbe bindings in [[the reference documentation page>>doc:extensions:Extension.WikiMacroStore.WebHome||anchor="HBindings"]].
151 +See all available bindings in [[the reference documentation page>>doc:extensions:Extension.WikiMacroStore.WebHome||anchor="HBindings"]].
159 159  
160 160  = WYSIWYG Access =
161 161  
162 162  A wiki macros is treated just like any other rendering macro in the system. As such, the moment you save your wiki macro it will be available to the users through the WYSIWYG editor's **Insert Macro** dialog box:
163 163  
164 -[[image:macro2.png]]
157 +[[image:macro2.png||height="293" width="350"]]
165 165  
166 -[[image:macro4.png]]
159 +[[image:macro4.png||height="149" width="350"]]
167 167  
168 168  == Special code for WYSIWYG edit mode ==
169 169  
... ... @@ -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
... ... @@ -239,17 +239,17 @@
239 239  This pitfall has been fixed in XWiki 2.2
240 240  {{/info}}
241 241  
242 -There is a common pitfall for using optional paramters. The following macro code contains a not so obvious bug:
235 +There is a common pitfall for using optional parameters. The following macro code contains a not so obvious bug:
243 243  
244 244  {{code languege="velocity"}}
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:
macro1.png
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.mleduc
Size
... ... @@ -1,1 +1,1 @@
1 -117.1 KB
1 +83.5 KB
Content
macro2.png
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.surli
1 +XWiki.mleduc
Size
... ... @@ -1,1 +1,1 @@
1 -15.7 KB
1 +24.8 KB
Content

Get Connected