Joyce Davis has just announced on the Lotus Technical Information and Education Community Blog that the XPages Forum is here. The forum is for all XPages related questions and discussions so go there and join the discussion.

This post is about creating a custom error page for handling errors (both controlled errors and not controlled errors) in XPages.

For handling errors in non-XPages requests a non-XPages 404/error page has to be added. To create a custom non-XPages error page, see the Help topic “Custom Web server messages” in Domino Administrator or have a look at this great article by Julian Robichaux on Lotus Domino custom web error pages.

First step for handling errors in XPages requests is to create the  XPage to be used. This XPage can be styled as you wish and you will probably reuse your overall site design – for instance by reusing custom controls that controls the look and feel of your web pages.

To catch controlled errors such as “page not found” errors (to “simulate” a HTTP 404 response) you can use a try/catch statement to redirect to the new XPage in case of “page not found” related errors on your XPage. This can be used to catch errors with data sources where the document id can not be found. The following example code from the documentId part of dominoDocument data source redirects to a custom XPage in case an article id can not be found:

try {
	var tempView:NotesView = database.getView("webpages-by-id");
	var tempDoc:NotesDocument = tempView.getDocumentByKey(param.id);
	return tempDoc.getUniversalID();
} catch(e) {
	context.redirectToPage("error.xsp")
}

The new XPage can also be used instead of the default error page to catch not controlled errors (errors/exceptions in your code). See this article on XPages error management in the Lotus dev wiki. In short, you need to add a computed field that display the value of the request scope variable “error”. The following example code displays the error message in a panel that is only displayed f the scoped variable “error” is present:

<xp:panel id="displayErrors">
	<xp:this.rendered>
		<![CDATA[#{javascript:if (requestScope.containsKey("error")) {
		return true;
		} else {
		return false;
		}}]]>
	</xp:this.rendered>
	<p>
		<b>Description of error:</b>
		<xp:br></xp:br>
		<xp:text escape="true" id="displayError" value="#{requestScope.error}"></xp:text>
	</p>
</xp:panel>

If you want to provide more detailed error messages on this error page, you can add the following computed field:

<xp:text escape="true" id="computedField">
	<xp:this.value>
		<![CDATA[#{javascript:var stackTrace ="";
		var trace = requestScope.error.getStackTrace() ;
		for( var i = 0; i < trace.length; i++){
		stackTrace += trace[i] + '\n';
		}
		return stackTrace;
		}]]>
	</xp:this.value>
</xp:text>

Please consider whether these detailed error messages are something that you would like to present to the users.

A better approach to displaying detailed error messages to your users would be to use logging in your application and then log the detailed error messages and instead present a user friendly error page. Matt White has integrated the OpenLog OpenNTF project with XPages in the TaskJam OpenNTF project. I will definitely have a look at this in the very near future.

David Leedy has just announced that his XPages cheat sheet will be available for handout at Lotusphere 2011. I can confirm that it is a useful cheat sheet because David involved me in a 2 hour review of the cheat sheet. It was great fun and I am pleased to have been involved in putting the cheat sheet together.

Now I just need someone from the Lotus community to grab me a copy of the handout at Lotusphere that can replace my self-printed copy. Anyone? 🙂

Below is a sneak peek at the cheat sheet courtesy of David Leedy. You will have to wait for Lotusphere 2011 for the real thing:

Update January 21: David has released the XPages cheat sheet a little earlier. Go grab your copy!