JavaScript in RPE


Simple templates can be created in RPE by doing drag&drop mainly. However for some of the more interesting templates you need to write some code: process the data that is being rendered, conditions for exclusion of elements or formatting etc.For all this you use JavaScript.

RPE exposes a standard JavaScript engine meaning you can one of the many JavaScript resources available on the WWW. For more details on the JavaScript engine supported by RPE check Mozilla Rhino: JavaScript for Java

Given the above I will not go into details on how JavaScript works instead I will focus on some of the common problems RPE designers face when using JavaScript in RPE.

The value of an expression

The value of a JavaScript expression used in RPE is always the value of the last JavaScript instruction in the script. Even if your script has many instructions it is always the last instructions.

var i = 0;
i = i +2;  // i equals 2 now
i;  //evaluates to 2 - this is the value of the expression

In the above code the value of the script expression is 3.

var i = 0;
i = i +2;  // i equals 2 now
i+3;  //evaluates to 5 - this is the value of the expression

In the above code the value of the script expression is 5.

You can look at everything before the last instruction is helper code, the part that calculates the result. The last instruction can be as simple as specifying the result or it can do some calculations. So a simple way to describe JavaScript expressions in RPE is:

  • [calculations] – 0 or more instructions
  • [result] – exactly one instruction

NOTE you do not have to use a “return” instruction as your last line.

Declare the variables you use

JavaScript is a very user friendly language. The language and the interpreter will try to make the best with the script code you write  and not bother you much. This translates into easy coding but can also cause problems.

Not having to declare variables is such an example: it makes your life simpler but can produce problems too. Using a variable without declaring it using the var keyword will cause it to be global and affect other places in which is used. The following code will cause an infinite loop :

function doSomething()
{
   // this affects the value of the i variable from the main body
   // and as i never reaches 5 the code will be an infinite loop
   i = 1;
}

for ( i = 0; i < 5; ++i)
{
   doSomething();
}

The way to write this code to avoid the loop and in general to avoid side effects in your code is to declare all your variables in your functions, making them local.

function doSomething()
{
   // local variable to this function
   var i = 1;
}

var i = 0
for ( i = 0; i < 5; ++i)
{
   doSomething();
}

Test your expressions

Anywhere JavaScript is used you will see a “Test” button. Use it as it helps you get the JavaScript code right  and its easier to follow than trying to figure out what happens when the document is actually generated.

Java objects in JavaScript

In addition to the resources ( functions, types) provided by the JavaScript language you can use almost any Java class in your scripts. This helps when you do not have the necessary tools provided by JavaScript and you want to avoid writing all the code by yourself.

A good example is Parsing dates with Java Script . The JavaScript language does not have a good date formatting library hence I usually resort to the date formatting features provided by Java.

// using Java class SimpleDateFormat from the java.text package
var fmt_in  = new java.text.SimpleDateFormat( "yyyy-MM-dd'T'HH:mm:ss");

NOTE when declaring a JavaScript variable you use the var keyword and not the type of the defined variable as you would do in Java.

Resources

JavaScript Tutorial

JavaScript and RegExp which also provides a Regular Expression tester

Advertisements

Author: Dragos Cojocari

Architect for Rational Publishing Engine

9 thoughts on “JavaScript in RPE”

  1. The first example above has:
    var i = 0;
    i = i +2; // i equals 2 now
    i; //evaluates to 3 – this is the value of the expression
    In the above code the value of the script expression is 3.

    This evaluates to “2.0”, not “3” when I run it.

    1. That is correct, thanks for spotting the error. I have updated my post.

      Also, all calculations evaluate to floating numbers. This doesn’t affect the code much ( code like if ( i > 2) works as expected) but it can affect the display. In order to display a float like an integer you can use the toFixed function like this:

      i.toFIxed( 0); // the argument is the number of digits you want to see after .the decimal point.

  2. Is there a known limit to the size of the ScriptExpression? I’m considering a long if/else stmt where I’m expecting around 850 lines. It’s a simple expression for determing target region, like if (varX < val1) targetRegion=1 else if(varX <val2) targetRegion=2… targetRegion=363 . I'm building it now, but I haven't completed it yet and don't know how a problem may manifest itself.

    Thanks,
    Jackie

    1. Hey Letty,

      using arrays inside a single JavaScript expression ( a condition, filter, assignment etc) is done using this statement:
      var myArray = new Array();
      myArray[0] = "alpha";
      myArray[1] = "beta";

      However note that with the current GA version it is not possible to pass arrays ( or another composed data structures) between scripts. In other words you cannot create the array in an assignment and than use it in a condition.

      Regards,
      Dragos

      1. Dragos,

        I have realized that I can’t access the array out of the script. It is very sad. =( jk

        I am trying to parse through an attribute text. The text contains hyperlinks mixed in with text in no particular order or pattern. The MS Word template I am creating with RPE must have the hyperlinks enabled(so that the user can click on the link). My first idea was to create 2 string arrays. One would contain text subsections and another would contain the hyperlinks. After the arrays were created, I would populate text or hyperlink fields in the template with the data in the arrays. But this idea is not feasible anymore since I can’t access the arrays outside of the script.

        Do you have any idea what my alternative is?

        Thanks!

  3. Hi Dragos,

    how do I beam the calculated js-stuff into the generated document?

    Best Regards,
    Raul

    1. Salut Raul,

      you do it by setting it as as the value for a text element. Her is an example:
      1. create a new template
      2. add a text element
      3. double-click the text element to edit its content
      4. switch to the “Script” tab
      5. write a JavaScript expression
      6. the last instruction in your JS code is used by RPE as the value

      Code sample:

      var x = 1
      x = x*1 + 1 // this is the output of the script expression

      I hope this answers your question.

      Regards,
      Dragos

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s