Advanced Script Tags and Groovy and Velocity Scripts
Excel exports can contain advanced tags that can execute
Velocity scripts. This is useful when simple property access and
JEXL expressions are insufficient.
The ability to execute scripts is controlled by the following environmental variables, which are set to false by default:
• CB_ALLOW_GROOVY_IN_EXCEL_TEMPLATES=false
• CB_ALLOW_VELOCITY_IN_EXCEL_TEMPLATES=false
• CB_ALLOW_DEFAULT_SCRIPT_IN_EXCEL_TEMPLATES=false
While the above variables are set to false, scripts are not executed in Excel templates and an error message is shown after exporting to Excel.
Some of the advanced tags are as follows:
|
Tag Name
|
Description
|
|
cb:script
|
Executes a template using the default script language, Velocity, and puts the
result into a cell.
|
|
cb:groovy
|
Evaluates a Groovy template and puts the results into a cell.
|
|
cb:velocity
|
Executes a Velocity template and puts the result into a cell.
|
For example, the <cb:groovy>Groovy name:${item.name}</cb:groovy> tag sets the value of the cell to Groovy name + <Name of the exported item>. For instance: Groovy name:my bug.
The following is another example of using a
Regexp from Groovy to extract data:
<cb:groovy template="false" silent="false"> email = item.submitter.email; domainRegexp = /@(.*?)\./; matcher= (email =~ domainRegexp); return matcher[0][1];</cb:groovy>
In the example, the domain name is extracted from the email address of the issues. If the submitter is
[email protected], the script will input “abccompany” to the cell.
The cb:groovy tag has some special feature that it can run in two different modes, as template or as script. The template mode means that the script is evaluated as a Groovy Simple Template, which has following main characteristics:
• The template is producing a string output, not a date or number.
• Bean properties are accessed using the ${bean.property} notation.
• The new variables declared inside the template are local, which means they are lost when the template evaluation is completed.
An example of this:
<cb:groovy>Hello ${world}</cb:groovy>
On the other hand, the Groovy template can run in script mode. This means that the script-text is evaluated as some Groovy code. For example:
<cb:groovy template="false" silent="false">item.submittedAt</cb:groovy>
This differs from the template mode as:
• The variables and bean properties are accessed using the simple dot, bean.property, notation, and no ${...} text is needed around.
• Any variables declared in the script will be available later as beans in the scope. For example:
<cb:groovy template="false">email = item.submitter.email</cb:groovy>
This will create an email bean in the scope which later can be used as ${email} elsewhere in the Excel document.
• By default the script won't produce any output, which means it won't write anything to cell. However if the silent=false property is set then return value of the script will be inserted to the table cell. This means that it can return date objects or numbers too, like in this example the cell will contain a date data.
Known Limitations of the Scripts
• The cb:script tags will use the complete content of the 1st cell as script, even the part which is outside the <cb:script>...</cb:script> tags.
• These tags will ignore and remove all the remaining cells even the tag spans multiple cells.