To execute a template, call the executeTemplate() routine over any pre-defined file.
So, this sounds easy, right? Because it really is.
Please take a moment to examine the documentation of the routine. The executeTemplate() routine takes one mandatory parameter, the path to the template file, either absolute or relative in that case the file must reside in the Kepler Home directory on the server. The second parameter, optional, is the charset, in case you wrote the file with a different charset encoding. Let's discuss several examples.
A Simple Example
<KEPLER_HOME>/templates/some.tpl
$! if(isNotNull(baseVar)) { $
Well done, $baseVar$ !
$! } else { $
Nobody to congratulate ?!? Whoaaaa !!!
$! } $
The example above shows the baseVar variable is not defined in the template. However, it is referred in both the if code block and as an output variable. So where does it come from?
The answer is in the calling script:
string baseVar = "Monster";
return executeTemplate("templates/some.tpl");
The baseVar variable is defined prior of the template execution call, and it is injected as a global variable (i.e. the uppermost context) in the resulting SIL™ script of the interpreted template. This means that you can exploit it like any normal variable and output it, and this is what we do there ($baseVar$).
The template tool ensures that all variables defined in contexts (read: blocks) are passed onto the template. Let's complicate a bit the example, and add the following to the script:
string baseVar = "Monster";
number baseNo = 10; //+another variable gets defined
string ret;
for(number i = 0; i < 3; i++) { //+ iterate 3 times
ret += executeTemplate("templates/some.tpl") + " "; //+ concatenate result
}
return ret, baseNo; //return also the baseNo
Let's modify the template to make use of those variables:
$! if(isNotNull(baseVar)) { $
Well done, $baseVar$ $i$ ($baseNo$) !
$! } else { $
Nobody to congratulate ?!? Whoaaaa !!!
$! } $
$! baseNo++; $
The little surprise is that:
Everything runs smoothly, with no error
.Both i and baseNo variables are defined at runtime in the template, along with baseVar.
baseNo gets incremented, as expected. This is the only method of returning from templates, although this practice should be discouraged, because of the side-effects it may have.
The output of the above script is:
Well done, Monster0 (10) ! Well done, Monster1 (11) ! Well done, Monster2 (12) !, 13
Advice
Always document your templates, stating what variables it expects. STL does not offer code comments, but you can always add a code block with comments, like in the example below:
$! // This template does A and B // It receives the following params: // x, type string, representing X // y, type number, representing Y // z, output param, type string $ ..... rest of the template here ....
Advice
Always state the side effects! Try as much as possible not to modify the variables, even if the mechanism allows you to do that!
Templates In The Issue Context
Templates in the issue context have the wonderful property of letting you access the issue variables like any other variable. This makes the template easily adaptable in your SIL™ scripts. Of course, they retain the above behaviour.
Let's examine this template:
$!
// A simple issue template. Runs only in an issue context.
// param: baseVar a string. If not null sets a customfield to a magic value.
$
$! if(isNotNull(baseVar)) { $
Well done, $baseVar$, the reporter of the issue $key$ is $reporter$
$!customfield_10000 = 2;$
$! } $
Let's create a post function on some transition in a workflow:
string baseVar = "Monster";
description += "\n" + executeTemplate("templates/descript.tpl");
What you need to remember is that the custom fields and issue fields may be accessed in the template as you do in the script. Of course, this only applies if you are in an issue context, otherwise you will get an error in the logs and nothing is returned from that template execution call.
As you can easily imagine, the result of the transition execution of the issue will look like:
Contents