ScriptInvoker is a 'source-class' compatible helper class providing a runtime environment that allows to load and execute
script code using the JSR-223 interface (scripting for java).
Scripts can provide input for velocity templates or they can produce content directly. When invoked, this extension first
populates all given macro parameters within the script context, evaluates the script and copies any changes or newly allocated
variables back into the original parameters map.
When an additional source
was specified these resulting parameters are available in the template via $paramName
Any text output that is produced by scripts is set into "source-content
" and is displayed when no source
The following global variables are exposed in the script context, in addition to the standard template parameters:
- "globals" points to an instance of "Globals" which allows to access base path, path resolution logic,
loading & attaching content, etc.
- "scriptName" is a string that is filled with the absolute path to the script file.
that is available by default. Adding other script engines to the dependency set of module or site-plugin enables scripting
languages like: Groovy, Ruby, Python and others that offer integration with JSR-223.
or when using the alias:
- Under normal circumstances it is preferable to create your own 'source-class' compatible helper class using Java as
it adds unit testing and compiler checks. Scripting however, when combined with "site:run" allows to create content with
scripts very quickly as no additional compilation step is needed to see live changes to the site.
- Scripts run in a request scope with global bindings (global variables) being shared amongst executions and script engines.
Whether this has an effect on the scripts depends on the implementation of the script interpreter and the language itself.
|Input Parameters (set with the macro call)
||Defines a shortcut for the request properties 'source-class' and 'script'.
If this parameter is present inside the request parameters list, the system will effectively behave as if
'source-class' and 'script' where set separately.
||Sets the URL or local path to the script file to load and evaluate.
The specified file is resolved in exactly the same way as when using the parameter "source" (see Macro reference).
- In addition to setting a file path, the parameter can be used to define an inline script snippet using the syntax
- When no further source is specified, any text output produced by the script (e.g. via print "some text")
is included into the current page. STDERR is always sent to both locations, the build logs and the page. Unhandled script errors
will break the build.
- As velocity template processing is applied at a later stage, the script output is processed by velocity unless the parameter
"source-is-template" is set to false or another "source" was specified. Thus a script can dynamically
generate a velocity template and provide the parameters for the template context (though this might be kind of a overkill).