lekkimworld.comxpages

The XPages Portable Command Guide and why it's important

Fri, 06 Apr 2012 08:54:16 GMT

I was among the people who was fortunate enough be be sent a review copy of the new "XPages Portable Command Guide" book that has just been published. While this review has been a long time in the making I wanted to get it out there never the less. You should first read the review Tim Tripcony wrote ("XPages Portable Command Guide is a book every Domino administrator should read") as it is spot on and very good and accurate. The thing about XPages that many developers and administrators forget - or simply doesn't know - is that it is running on a completely rewritten HTTP stack on the Domino server. It was even refactored recently to be based on OSGi technology to make it even better and more easily extensible. The XPages runtime is more like a traditional J2EE server (like Websphere Application Server) than a traditional Domino server. This means that the runtime is very configurable but out of the box it is configured to be a jack of all trades. You can change it though and you probably should if you run business critical applications of it.

For me the most important part of the book is the part about the xsp.properties file that is the main configuration file for the XPages runtime. The file is central to how an XPages application function and it's crucial that it is configured and tuned correctly for the needs of the application. While having to do this kind of configuration by hand is prone to errors and that IBM really should provide better tooling for it doesn't change its central role for XPages. It is therefore very important that you as a developer or administrator know how to edit it. For the developer you need to be able to configure the application so it functions at peak efficiency and as an administrator you need to know enough to throttle your developers to not configuration the applications to as to note starve one another for resources.

The important part about XPages is that where many of the settings for traditional Domino web applications are server settings many, if not all, of the xsp.properties settings can be thought as of deployment settings as well as server settings. As Tim writes - "There are plenty of settings that can be defined in this file that only the developer should care about, but many of them you don't want the developer to decide. Trust me, if you leave it to me, I'm typically going to max out the RAM consumption in an attempt to provide lightning fast response times. But it's your server. You should be overriding me on that decision... as long as it's still in keeping with the end users' business needs, of course."

So if you do any work with XPages I therefore highly recommend you get a copy of this book. Get it as an e-book though as it's a reference and IMHO a paper copy doesn't make any sense. Most of the API calls you can also find good documentation on online but the xsp.properties part is lacking online and it's critical to know about and understand if you want to get the maximum from the XPages runtime.

The Java native2ascii tool (also important for you XPages geeks)

Wed, 21 Mar 2012 07:59:25 GMT

To prepare for our upcoming trip to Tokyo I've been working on a Japanese translation of our OnTime Group Calendar 2011 client for Notes based on Java plugins. The internationalization engine (i18n) was already in place so it was merely a matter of doing the translation (thanks to Google Translate and friends) and then adding language files to our API. In that process one becomes very thankful of UTF-8 and the fact that Java works natively in UTF-8.

Please note that the approach discussed in this post translates (excuse the pun) directly to making translation files for XPages as well.

Using the Japanese translation the GUI looks like the below screen shot (cropped of course).

(click the image for a large version)

The funny thing about most non-Latin languages is that even though you have the translations it's hard to impossible to write the characters yourself. And once you have the words getting them into the language files which are mere property files. Take the weekdays in Japanese as an example:
月曜日
火曜日
水曜日
木曜日
金曜日
土曜日
日曜日

Because we're running the OnTime Group Calendar out of Notes and because Notes is fully double-byte compatible we could actually just add the Japanese characters directly to the translation document. Instead however we opted to use the Java way that is the native2ascii tool.

The native2ascii tool is shipped with the JDK and lets you translate a file containing native characters to their UTF-8 equivalent escape sequences. So having my Japanese characters in japanese_source.txt and wanting to store the result in japanese_result.txt I simply ran the following command:

native2ascii -encoding japanese_source.txt japanese_result.txt

The encoding parameter specifies the character encoding of the source file (here japanese_source.txt). The result is something like this:
\u6708\u66dc\u65e5
\u706b\u66dc\u65e5
\u6c34\u66dc\u65e5
\u6728\u66dc\u65e5
\u91d1\u66dc\u65e5
\u571f\u66dc\u65e5
\u65e5\u66dc\u65e5

Chose escape sequences go directly into the language property file and when read into a Java property file they are automatically translated into Japanese. Sweet!

I will be giving two sessions at DNUG in November

Thu, 18 Aug 2011 10:27:42 GMT

As mentioned previously I'll be speaking at DNUG in November in Bamberg in Germany where I will be giving my "jumpstart your plugin development"-session about all the plugin development goodness. Besides that I'm also going to join forces with Rene Winkelmeyer (of among other things File Navigator fame) in a two hour session on XPages Extensibility Library titled "XPages Extensibility under the hood". One hour on the basics and a full hour hands-on labs. Hope to see many of you there.

Getting started with CSS

Fri, 13 May 2011 07:27:00 GMT

When introducing developers to XPages as I did yesterday the question on where to learn (more) about CSS always comes up. Therefore I was happy to see an article this morning in the developerWorks newsletter. The article is titled "Get started with CSS" and gives a good introduction to syntax and how to use and write CSS. Highly recommended article.

A (dojo.)mixin configuration approach to XAgents in XPages

Wed, 11 May 2011 15:14:51 GMT

Continuing my XPages theme from yesterday I also wrote an XAgent base-class in JavaScript to make XAgents easier to do. Part of the base class is that it allows me to pass in a JSON object to configure the XAgent based on the need. Since the information I pass in should override the built-in defaults I needed a way to easily allow the user supplied values to override the defaults. The easiest way to do this would be to use the dojo.mixin.

"dojo.mixin is a simple utility function for mixing objects 
together. Mixin combines two objects from right to left, 
overwriting the left-most object, and returning the newly 
mixed object for use."

Unfortunately Dojo isn't available in SSJS I needed to do it myself. To my luck it was surprisingly easy as the below code illustrates.

// create function to allow mixin' two objects
var mixin = function(target, source) {
   if (!source) return;
      var name, s, i;
      for (name in source) {
      s = source[name];
      if (!(name in target) || (target[name] !== s)) {
         target[name] = s;
      }
   }
};

My XAgent base class looks something like this:

function XAGENT(args) {
   // create mixin function
   var mixin = function(target, source) {
      if (!source) return;
         var name, s, i;
         for (name in source) {
         s = source[name];
         if (!(name in target) || (target[name] !== s)) {
            target[name] = s;
         }
      }
   };

   // define default arguments
   this._args = {
      download: false,
      filename: "default.json",
      charset: "iso-8859-1",
      contentType: "application/json"
   };
   
   // mixin user-supplies arguments
   mixin(this._args, args);
};
XAGENT.prototype.run = function(command) {
   ...
};

What's super neat is that now, in my run-method I can access the this._args object and all values that the user supplied have overridden the default values because we used the mixin-function. Very cool and an easy and flexible way to have default values but allowing them to be overridden by the caller. Also you know that the variables you need have been defined so no checks are necessary.

Calling my XAgent class is very easy allowing me to override the defaults. The run-method accepts a function which is called when the XAgent stuff has been set up supplying the Writer and the parameters supplied in the URL as a JSON object.

var xa = new XAGENT({
   filename: "feed.json", 
   download: true
});
xa.run(function(w, params) {
   ...
});

XPages JavaScript utility function of the day

Tue, 10 May 2011 12:05:02 GMT

Yesterday and today I've been spending some time doing some XPages coding for a customer project and after spending quite some time doing Java plugin development I'm amazed of how easy XPages are. Don't get me wrong - there is still work to do for the XPages team but it's a joy to work with XPages and coding in JavaScript is just - well - flexible and fun.

One of the real joys of JavaScript is it's dynamic nature and that it allows one to really cut down on the boilerplate and repeated code. For one I spent a lot of key pressed getting field values from backend documents in server side JavaScript. Instead of repeating the same ol' Document.getItemValueString(String) over and over again I did a neat little shortcut. Since I needed all items from a document I just created a utility function to JSONify a document to make it easier to access. The method is below.

var jsonifyDocument = function(doc) {
   var result = {};
   if (!doc) return result;
   var item;
   for (item in doc.getItems().toArray()) {
      result[item.getName().toLowerCase()] = item.getText();
   }
   return result;
};

So now instead of writing doc.getItemValueString all the time I can now just do property-like access to field values ("Heading" and "Description" are fields on the document).

var jsonDoc = jsonifyDocument(doc);
jsonDoc.heading + " (" + jsonDoc.description + ")";

I also wrote a nice little Dojo-like mixin function to make my XAgents easy to configure. But that's for another day.

Save the date: XPages Documentation Discussion

Fri, 22 Oct 2010 06:40:49 GMT

I found this via the LotusUserGroup.org newsletter and I found it worth passing along.

On Monday, November 8th, give a shout out to the documentation team for Lotus Domino Designer. The team is looking to get your feedback on how helpful you find the Domino Designer User Guide (XPages) Help and will be moderating a forum on the topic at LotusUserGroup.org/forum for you to shout out your comments And observations.

The XPages Help provides information that is necessary for developing web applications using the new XPages technology available in Domino Designer. Do you like the newly added controls and properties reference sections? Have some feedback orsuggestions on the usability of the documentation - content that works well, content that needs improvement? This is your chance to really impact the XPages documentation content.

So mark your calendar. Bob Harwood, the Information Development (ID) Lead for Domino Designer, the Domino Designer ID team, and Cara Viktorov, ID Usability Feedback Lead, will be moderating the forum, live, the week of November 8, 2010. Plan to join in and ask questions, share experiences, and collaborate about Domino Designer Help.

Date: November 8, 2010 Forum: http://www.LotusUserGroup.org/forum

What is new in 8.5.2 for XPages

Fri, 15 Oct 2010 11:26:51 GMT

Lotus Notes/Domino 8.5.2 is out and the other day I was hosting an XPages training session so I thought a little bit about what's new with XPages. Of course XPage ninjas like Matt has already written about it (Matt White: What's new with XPages in 8.5.2) but as I was reading up I found some links I wanted to highlight. Most info may be found on the IBM wiki.

onClientLoad Event. Its now possible to add scripts in the events to be executed when the page is submitted or this panel or some containing panel is partial updated.
Extensions API
Two new Global Objects for Server Side JavaScript, sessionAsSigner (open a session using the signer rights) and sessionAsSignerWithFullAccess(open a session using the signer rights, while giving it full access to the data)
- sessionAsSigner - Assigns credentials based on the signer of the of XPages design element. The session is restricted by the application's ACL and the security tab of the server's Domino Directory entry.
- sessionAsSignerWithFullAccess - Assigns credentials based on the signer of the of XPages design element and allows full administrative access to the application's data. The signer must have the right to such access or the session is not created.
New resource xp:headTag - this allow you in an easy way to put stuff into the header of a XPage
XPages ECL to Permissions updated to include more Java Permissions
In V851 of XPages, security for executing Java code in XPages in the Notes Client was very restricted. For XPages V852, the Java Permissions managed by the XPages ECL settings have been broadened to be similar to the set of Java Permissions allowed by Java Agents and to bring a level of equivalence between Java Permissions allowed for XPages on Domino Server (Unrestricted) and XPages in the Notes Client. For example, in V851 the ECL Network permission only covered the Java SocketPermission, now it covers NetPermission and other related Java network permissions.
Referencing a Managed Bean from JavaScript now supported in XPiNC. This fixes a bug where a Managed Bean, first referenced in JavaScript (which triggered the creation of the Bean) caused a security exception. The workaround was to first have this Managed Bean referenced and created as a DataSource (referencing the Bean from then on was fine). This bug is now fixed.