How To Get A-HEAD in XPages (Repost – previous version corrupted)

First of all, thanks to Declan Lynch for reading this blog post when I accidentally, foolishly corrupted it all! Thanks to him, I’m able to quickly replace it.
One of my strengths is a good memory, which helps when other developers ask a question. It means I can often vaguely remember reading something somewhere or developing some code that has relevance in a database somewhere, and with a bit of hunting I can find something that points them in the right direction. The difficulty is it’s often not an exact answer, just pointing them in the right direction.
One customer has purchased an XPages mentoring contract with us, which gives me the opportunity to dig into greater depth and work through problems with them. I try to get involved in answering forum questions, but sometimes don’t have the time to follow through with responses. That means my drive to get involved on other XPages is driven by what I’m working on at the time, amount of effort required and likelihood to work on in the future.
Just today, whilst chatting with David Leedy on a number of topics including xpages.tv, Lotusphere abstracts and future collaborations David posed a question about my experience of using a script block in XPages. Both with my validation tutorials and my dojo charting tutorials I used them on a number of occasions, so I was able to help. For those who haven’t used the script block, it’s one of the mechanisms for storing client-side javascript functions on an XPage. (You can also write “pass-thru HTML” on an XPage by using a Computed Field control and setting the escape attribute to false. So you can then create your own script block in the same way you would have done on a Notes Form. Again, there are examples of that in my charting tutorials.)
One of the main points here is that the script in a script block is only made available on the XPage. It’s not triggered unless called. So why use them rather than script libraries? One benefit is that they allow you to create functions that include #{id:myField} to get client-side IDs to access the code. Another is that they allow you to access javascript variables written into the XPage in Computed Field controls.
But David’s particular requirement was that he needed to reproduce google analytics functionality that was traditionally done by placing client-side script in the tag. This was where my memory kicked in and I remembered reading that in 8.5.2 you can start adding code to the head tag of an XPage. After a quick search on the web we both found at the same time an article by Niklas Heidloff about using this to add a meta tag for developing for Blackberry devices. Between myself an David we were able to extrapolate Niklas’ example and work out we needed to add:
<xp:this.resources>
 <xp:headTag tagName=”script”>
  <xp:this.attributes>
   <xp:parameter name=”script” value=”text/javascript” />
   <xp:parameter name=”content” value=”YOUR CODE” />
  </xp:this.attributes>
 </xp:headTag>
 </xp:this.resources>

Then it was just a case of substituting “YOUR CODE” for the relevant client-side javascript. And that worked fine.
Or it would have because at this point I confused David (and, inadvertently, myself!) by trying to get him to compute the value, because I suspected the code had characters that could not go into a simple value attribute. There was one big mistake I made, a mistake I’ve had to explain to other developers when computing the output for an onComplete event, for example, and a mistake worth detailing in this blog for others. The output needs to be the correct language.< BR>Let’s break that down. When you compute a value attribute of, say, a Computed Field, the output needs to be a text string which is used to display text. So you have e.g. “Hello, this is ” + database.getTitle(). in this application, that would return “Hello, this is Intec Blog”.
In a script block or an onComplete event, the output expected is a text string which is used to run client-side javascript. So instead your output might be “alert(‘ Hello, this is ” + database.getTitle() + “‘);” to alert the same message.
So our value attribute needed to return a text string that would be valid client-side javascript. As with pass-thru HTML or inline javascript in a Form in traditional Domino development for the web, my preference is to minimise what you need to compute, so specific variables that are then passed to a function in a client-side javascript library. It minimises the risk of problems with typos or syntax errors. Alternatively, write as much as possible in a script library or other client-side javascript editor and piece it together, remembering to put quotes around anything you paste into the server-side javascript editor. In this case David was able to put the whole javascript function in a client-side javascript library and just call the function, which was considerably easier.