 | Executes a script implementing the [[JSR-223 API>>http://scripting.dev.java.net/]] |
| Type | javamacro |
| Category | |
| Developed by | Unknown |
| Rating | |
| License | Unknown |
Table of contents
Description
Executes a script implementing the JSR-223 API.
Usage
print "some" + " " + "script" + " " + "content"
{{/script}}
By default the "xwiki" and "xcontext" variables are defined and respectively represent a XWiki and Context API objects.
Parameters definition
| Name | Optional | Allowed values | Default value | Description | Since version |
|---|---|---|---|---|---|
| language | yes | the identifier of the JSR 223 engine | Indicate which engine to use to execute the provided script | ||
| output | yes | true/false | true | Indicate the output result has to be inserted back in the document | 1.8.1, 1.9M1 |
| wiki | yes | true/false | true | indicate if the result of the script execution has to be parsed by the current wiki parser. If not it's put in a verbatim block. | 2.0 M1 |
| jars | yes | comma-separated list of JARs that will be added to the script execution class loader | none | see below | 2.0RC1 |
Specifying extra JARs
If you have programming rights, it's possible to add JARs that will be available to the script's execution by using the jars parameters. The format is a comma-separated list of entries of the following types:
- a URL of the type http://server/path/to/some.jar
- a reference to a JAR attachment on the current page:
- a reference to a JAR attachment located on another page:
- a reference to all jars located on a give page:
Bindings
Some bindings/variable are automatically provided:
| Name | Class | Description |
|---|---|---|
| xwiki | com.xpn.xwiki.api.XWiki | Utility APIs |
| xcontext | com.xpn.xwiki.api.Context | Contains contextual informations |
| request | com.xpn.xwiki.web.XWikiRequest | The servlet request. Generaly used to get URL parameters. |
| response | com.xpn.xwiki.web.XWikiResponse | The servlet response |
| doc | com.xpn.xwiki.api.Document | The current document |
| util | com.xpn.xwiki.api.Util | Utility APIs |
| msg | com.xpn.xwiki.web.XWikiMessageTool | l10n tool |
| syntaxFactory | org.xwiki.rendering.syntax.SyntaxFactory | generate proper Syntax object from syntax identifier |
Return
Since 2.4M2 it's possible to directly return the result of the macro execution as a single Block, a list of Block or a XDOM. That allow to cover some use case where you already have the block (you got from a parsing for example) and want to insert them into the document or when you want to do safest escaping possible.
The way to return a value from a script totally depends on the language and the engine used. Note that this is available only for JSR 223 based macro for now which mean pretty much all macros except velocity one.
Here is an example with groovy macro:
return java.util.Arrays.asList(new org.xwiki.rendering.block.WordBlock("Hello"), org.xwiki.rendering.block.SpaceBlock.SPACE_BLOCK, new org.xwiki.rendering.block.WordBlock("world"));
{{/groovy}}
Nested scripts
Since 2.4M2 it is no longer possible to directly nest script macros inside each other. For example, this would NOT work any more:
#set($data = "test")
## nested groovy, forbidden!
{{groovy}}
println("$data");
{{/groovy}}
{{/velocity}}
Nested scripts present a serious security risk, because they can be used to bypass security checks. We strongly advise to write your scripts so that the data is passed through variables. If you really need the old behavior, you can remove NestedScriptMacroValidator from components.txt in xwiki-rendering-macro-script component.
Example
def list = ["one", "two"]
list.each { item ->
println "* ${item}"
}
{{/script}}
Result
- one
- two
