Your Development & Design Resource

Mastering XPages by IBM Press

Disclaimer: Vendor - Commercial

IBM Press: Mastering XPages IBM Press recently released the definitive guide for IBM Lotus Notes Domino 8.5.2 XPages: Mastering XPages: A Step-by-Step Guide to XPages Application Development and the XSP Language. In this book, authors Martin Donnelly, Mark Wallace, and Tony McGuckin [with contributing author Jim Quill and foreword written by everyone's favorite IBM XPages Chief Architect Philippe Riand] strive to write the definitive printed reference material for all-things XPages.

Cut to the chase...

From the book's back cover:

The Definitive XPages Development Guide -- Straight from the XPages Team at IBM Lotus

XPages is the most significant improvement to Lotus Notes/Domino® development in 20 years. Now, three IBM® Lotus insiders have written the definitive programmer's guide to this breakthrough web application development framework. Packed with tips, tricks, and best practices, Mastering XPages brings together all the information you need to become an XPages expert, whether you're experiences with Notes/Domino development or not.

So without much further ado...

Sectioned into Parts after the foreword, acknowledgements, and all of the other stuff at the beginner of the book... we start with Part I - Getting Started with XPages.

Chapter 1: An Introduction to XPages

The obligatory introduction chapter, but the authors immediately set the stage and relay what I think is the most important message of XPages for the IBM Lotus developer:

[Emphasis added]

The catch, if you can call it that, is that the XPages development paradigm is different to what Domino web developers were used to up until version 8.5. Here, black magic practices, like $$Return fields and strategically embedded pass-through HTML, are no longer the web dev modus operandi.

Simply put: leave your hackaday techniques at the doorstep; they're no longer required. And while this all-but-nullifies years 0-6 of this website, I couldn't be happier.

The rest of this chapter does what any well-written introductory chapter is meant to do: quickly establishes and outlines the given subject (in this case, XPages). Once we have the basic idea of what XPages are, we'll need to suit up... which is the subject of the next chapter.

Chapter 2: Getting Everything You Need

This chapter was a hit and a miss for me...

First, I applaud the authors for writing this not only for the enterprise customer developer but also including directions for a developer new to IBM Lotus as a platform and instructing them on how they can download DDE v8.5.2 and get started writing apps.

The brief overview of the DDE client is brilliant, which lends as an intro to the Lotus SDK but also establishing Lotus developer nomenclature for the reader.

The miss in this chapter is the dive into creating a Hello World app. Not only is your next chapter titled Building Your First XPages Application (which is thus a misnomer), but there were some missed opportunities here.

I would have preferred to see an overview of the Domino Designer in Eclipse Help Database.

I would have preferred a tip on running Lotus Notes/DDE as Administrator in Windows 7 which is the only way to get localhost previews of XPages to work due to built-in Windows 7 security settings...

I would have preferred to make sure the new XPages developer be fully-dressed before jumping into Hello World, especially since the first part of the chapter so brilliantly includes new-to-Lotus developers in it's audience.

Chapter 3: Building Your First XPages Application

The discussion8.ntf Template takes center-stage for this chapter. This allows us to establish the prototypical XPages app layout [which will work for well over 90% of the target audience of Lotus developers]. It shows the functional similarities of the traditional and the XPages-based Main Topic Forms, and walks the reader through creating fully-functional myTopic.xsp and myView.xsp XPages to handle CRUD operations against the Discussion Template-based NotesDatabase app.

Smart move here, as it establishes the best practices techniques and the ability to employ your own XPages to further extend a given app.

New Lotus developers may not be blown away by the example, but traditional Lotus developers who have tried to do something multiple-NotesDocument selection and [in this case] Deletion requests will be impressed by the near out-of-the-box functionality of XPages.

This chapter ends Part I, and the next chapter begins Part II - XPages Development: First Principles.

Chapter 4: Anatomy of an XPage

From this chapter:

This is the primary reason that this chapter is important to you:

You will learn to create an XPage by hand so that you can understand what is actually happening under the covers to an XPage when you use Designer.

This chapter quickly establishes that, unlike HTML, XML and thus XPages are very critical to tag-syntax. It dives into XHTML, XML Documents with XHTML and XForms, simple and complex Properties, the use of character data or CDATA sections, computed Properties via CDATA-based JavaScript...

Before you realize it, you're defining Data Sources and surfacing NotesData via XPage Controls.

Where the chapters in Part I were simply introducing the technology, Chapter 4 runs with it. In the conclusion of this chapter, the authors correctly offer:

[Emphasis added]

Don't worry if you haven't fully mastered all of the tags covered; at this point, the important this is to look at the sources for a simple XPage (like the samples provided in this chapter) and to read the source and begin to understand what the page will do. Being able to use source mode to read and write XSP is a key skill that you need to master.

Later chapters in the book establish that while RAD capabilities allow you to deliver fully-functional rich web browser [and Lotus Notes Client] applications using XPages, getting even more out of the technology requires that you sometimes abandon the WYSIWYG Editor of the Design pane and the GUI-driven Properties and instead dive deeper into the XPages markup.

Chapter 5: XPages and JavaServer Faces

JavaServer Faces (or JSF) and it's relationship to XPages is covered in this chapter, and is an example of needing to understand exactly what XPages are before you can extend their RAD capabilities.

The MVC software architecture of XPages is discussed, along with detailed diagrams showing the firing times of JSF - from writing the UI/restoring the View and populating it with data from the Faces Request, to Process Events post-Response and post-Validation. You begin to appreciate the iterative processing of the JSF and learn exactly how your XPages gets from the Domino Server to your given Web Browser or Lotus Notes Client.

While I honestly think that most of this will be lost on the Notes developer and thought too big-brained... remember the paradigm shift that XPages brings -- understanding exactly what XPages are is critical to embracing them, honing your expertise, and ultimately extending their capabilities far-beyond their out-of-the-box perceived limitations.

Chapter 6: Building XPages Business Logic

Being a fan of MVC software architecture, I was really excited to see just how they handled business logic being enveloped into XPages.

This was a chapter that I thought- as someone who's written NotesDatabase apps employing MVC software architecture techniques - was a hit and a slight miss.

This chapter, simply put, should have been named Application Logic instead of Business Logic. Business Logic is not what JavaScript is fired from which button or what Renderkit is used for a given button's EventHandler or UI Control-level validation events. To me, that's Application Logic.

Business Logic is workflow routing [eg., If the Status == "Submitted", and there is no manager approval, set the Status to "Pending Manager Review", initiate an email to the author's manager including a link to the request, and update the History to reflect the workflow processing.]. It's something that is the story of what the application does, not the individual events being triggered from individual buttons or the surfacing of those buttons based on User Group/User Role assignment. That's Application Logic as far as I'm concerned.

Slight misnomer aside... awesome chapter. It covers embracing the MVC software architecture capabilities of XPages through separation of View [XPages User Interface] and Model [NotesData-based Data Sources], showcases the use of CSJS and SSJS to manipulate rendered UI Controls, and even works in View and SessionScope Variables.

This chapter, which is the first of two chapters dealing with creating your own business logic within XPages (the second being Chapter 11), does an excellent job of showing the interaction of SSJS and CSJS with UI Controls (such as inputText, and button), interaction of SSJS and CSJS [surfacing Server Data with CSJS], the leveraging of Scoped Variables, and built-in XSP Properties and Functions.

This chapter ends Part II of the book, and readies us for more NotesData manipulation in Part III - Data Binding.

Chapter 7: Working with Domino Documents

In this chapter, we begin our review of what could be the most powerful feature of XPages: Data Binding. Domino Documents covers all CRUD operations for NotesDocuments in a NotesDatabase... from simple XPages -> NotesDocument to using QueryString Parameters to create Response NotesData hierarchies.

This chapter also covers Conflict Document surfacing via XPages, managing multiple NotesDocument Data Sources on a single XPage, the NotesDocument Data Source Event Model [ie., queryNotesDocument, postNotesDocument, et al], and various other topics that'll serve a Domino Developer learning XPages quite well.

For example, it covers Simple Actions as well as using SSJS to interact with the given NotesDocument from the Data Source. Those developers worried about diving into XPages might find this chapter particularly interesting, as it gives us a glimpse into the various NotesDocument methods available to the XPages developer via simple type-ahead.

Mastering XPages - Chapter 7, Figure 7.12: Document methods exposed using the JavaScript editor

For those of you downright scared of SSJS -- and hey, I get it: moving from one language which you've mastered into something that you're unfamiliar with is scary -- check out the syntaxes here...

doc.getItemValue(name of NotesItem) looks pretty familiar to me!

This chapter concludes with customizing the Rich Text [read: CKEditor] toolbar... which is something quite useful for the more advanced Domino XPages developer who is looking to create a completely controlled Rich Text entry experience, but truth be told I think 99% of us will just roll the standard toolbar and call it a day. Still, awesome information to have!

Chapter 8: Working with Domino Views

This chapter jumps right into Domino View-based Data Sources by reviewing all 20 of the <xp:dominoView> tag properties.

You have some properties that should be familiar -- at least in function -- to the Domino Web Application Developer... and some that will make you realize just how powerful XPages are and what they can deliver as part as previously-perceived [or at least difficult-to-achieve] functionality.

The next topic highlights one of the more powerful properties of the <xp:dominoView> tag: the databaseName Property.

Here's quoted example markup from Listing 8.2:

<xp:dominoView var="view1"
    viewName="By Category">

Yep, that's remote data binding to a <xp:dominoView>. And what is even more powerful is the fact that these properties can be computed... meaning you could get really crazy and, let's say, bind them to QueryString Parameters!

Of course, that's not covered in the book... so let's get back to Chapter 8.

The chapter continues with Data Source filters using the categoryFilter and reviews the rest of the 20 parameters available to the <xp:dominoView> tag.

The section A Page with Two Views covers -- you guessed it -- multiple dominoView-based Data Sources on a single XPage.

The chapter concludes with (and I know I'm sounding like a broken record here...) one of the more powerful features of XPages: the ability to leverage scope and caching to enable faster loading of NotesData.

Chapter 9: Beyond the View Basics

At this point, most of you would have stopped reading the book and dove into Domino Designer to create your own XPage apps, be they new apps or updated versions of existing production apps that are in dire need of re-development, and that's great!

You can actually get through an app or two based on the first 8 chapters of this book and get your users actually using the apps (or at least create enough Proof of Concepts that you get buy-in from project champions and management)... but what about the more advanced features and functionality available in XPages -- and specifically that available via the <xp:dominoView> tag? Well, that's where Chapter 9 comes in.

This chapter gets us started with the viewPanel Control.

Examples in the chapter take us from full Date formatting of existing Domino View contents via a simple Date style and format properties change in the surfacing viewColumn, using rowData [as a variable for the viewPanel] to surface view position-specific images, cleaning up the presented UI of the viewPanel by using a viewTitle, handling Categorized view contents, using a dataTable to surface file attachments, using nested repeat Controls to surface Rich Text contents in a View, to a rather silly-yet-illustrative use of images in a pager Control.

Yeah, this chapter covers a lot of stuff.

... and it covers each topic at a surface level while giving you an insight into exactly what can be done in your own apps to envelop some rather slick functionality and features for your users into existing solutions.

This chapter concludes Part III, and chapter 10 kicks-off Part IV: Programmability.

Chapter 10: Custom Controls

So far, the book has covered fairly RAD capabilities and practices for XPage development. This chapter starts off with an overview of Custom Controls as reusable pieces of XPage markup correlating them to Subforms for Form Design Elements in traditional Domino application development.

Laying the groundwork for the second-half of the chapter, the definition and intended usage of a Custom Control is quickly established. At page 337, I think even the most seasoned XPages developer will start taking notes.

The Using Property Definitions starts to really expose the capabilities of Custom Controls.

By the end of Chapter 10, you will have a completely Custom Control-driven layout for your XPages that mixes properties-driven preferences with editable areas to allow you to use said layout as a template that can be further extended per individual XPage. Amazingly powerful stuff here.

Chapter 11: Advanced Scripting

To quote the intro to this chapter:

In this chapter, you improve your core skills by developing expertise in the following areas:


  • AJAX and partial refersh
  • Dojo integration
  • Traditional notes/Domino building blocks
  • Managed beans


The beginning of this chapter introduces you to the concept of stateless vs. stateful runtime environments. JSF, the chapter states, supports a stateful environment... which takes us right into AJAX and partial refresh which leverages XPages stateful capabilities.

The partial refresh example in this chapter is something that you will invariably use in your own applications once you really get into XPages development: clicking on a more link to surface additional data from a NotesDocument via a rowDataPanel and a hide link to suppress it.

Simple stuff, but it's those features that users love, and the authors did a good job of including them in the chapter to illustrate what can be delivered via targeted partial refresh.

After several more examples, the chapter continues with Dojo Integration.

This section covers dojoAttributes quite well, giving you a functional and visual example of a hierarchal tree of document UNIDs that display their data in a frame (the whole example screams 2-frame XPages Frameset, even highlighting a drag-to-resize border) via a partial refresh-driven AJAX GET.

The Working with Traditional Notes/Domino Building Blocks section briefly covers [read: discusses in a few paragraphs] the 127 @Functions available via SSJS... but rather smartly addresses working with Agents, In-Memory Documents, and Profile Documents. The examples from this section will have you interacting with Java Agents and XPages-rendered NotesDocuments via SSJS. Good stuff!

The chapter concludes with something that will send all traditional Domino application developers running in fear... until they realize just how simple they are: Managed Beans.

This section walks the reader through working with the Build Path and navigating the Package Explorer [which you've used multiple times already in the previous chapters, so it should be Permanent Sticking Charm-ed to your Domino Designer perspective.

The chapter's previewBean example illustrates how something that could be difficult to manage. Using a single link Control, the text/label, the style, and the content itself is all handled via the bean. Damn good stuff!

Chapter 12: XPages Extensibility

This chapter addresses the absolute out-of-the-box limitation with XPages... in that there are only so many controls loaded standard with XPages.

Need an Image Gallery Lightbox? Yeah, that's not core.

But this chapter shows you that IBM has given us the tools to finally address any functionality gap within the product by writing our own controls.

The How to Create a New User Interface Control does just that: provides a step-by-step recipe for creating a number spinner Control.

I'm going a little light on this chapter... only because it is pretty single-subject: it's a recipe to create a new User Interface Control thru the XPages extensibility capabilities.

With Extensibility Controls (just to define nomenclature if you will), consider this: once you write your new Control, it can be available in any application you write. The number spinner example from this chapter can be employed in any XPages app simply by adding the uiSpinner Control.

You want that Image Gallery Lightbox, write your own lightbox Control... and make sure it's donated to the XPages Extensibility Library.

Chapter 13: XPages in the Notes Client

This chapter covers the Notes Client XUL engine (XULRunner, which is also used by Mozilla Firefox [what I wouldn't give for them to have adopted WebKit... sigh]), the under-the-hood overview of how XPages works in the Notes Client [wanna see something interesting? enable the Address bar in your Notes Client the next time you work in an XPiNC app...], and dives into many of the hybrid-architecture considerations you'll face when creating multiple-Client XPage apps.

For example, the practice of applying rendered logic to Anonymous-friendly or Web Browser Client-specific features (such as an inline login form). As you are in the Lotus Notes Client, you're already authenticated and thus have no need for such features.

This chapter also covers the slight nuances of the Notes Client vs. the Web Browser Client such as the slight differences between the dialog/alert prompts. Other considerations are discussed, such as Client preferences for tabs and a given link Control's target.

Also covered are several XPiNC debugging tips and even creating a Composite app that interacts with your XPages.

This chapter concludes Part IV, and we begin Part V: Application User Experience with the next chapter.

Chapter 14: XPages Theming

This chapter jumps right into Styling rendered markup both with inline styling and via styleClass + a Stylesheet. It lays the groundwork for the meat of the chapter, which covers using Themes not only to style applications, but to control what Design Element Libraries and Stylesheets are used for a given application or applied against a given Control.

Covering extended Themes, how to apply Themes to an application via the Application Properties, and even cascading extended Themes, this chapter gives you plenty of styling options for your XPages apps.

The chapter continues with metaData, Script Libraries, and linkResources in Themes as well as Theme bundles. Amazingly useful for a lazy developer like me that wants to maintain all of the header and meta information and resources for my apps in a single place.

The chapter concludes with an amazingly detailed and fleshed-out application of Themes that covers cascading extended Themes, Client-specific Themes-based rendering of resources, usage of themeIds in Controls, and how to use SSJS to dynamically control the values of the Theme.

Killer chapter, and hands-down the best resource of Themes I've come across yet.

Chapter 15: Internationalization

This chapter covers both localization and language translation of the UI and UX via combination of Resource Bundle Files [.properties], as well as localizing SSJS libraries.

If you have a need to provide multilingual UIs and UXs for your applications, this chapter is a must-read.

This chapter also concludes Part V, and we begin Part VI: Performance, Scalability, and Security with the next chapter.

Chapter 16: Application Performance and Scalability

Once of the biggest concerns I hear about XPages apps for one reason or another are the perceived limitations of their scalability. This chapter dives right in by telling you -- if I may in my own words -- that being pretty ain't the only thing XPages is about.

A detailed review of the request processing lifecycle with JSF gives you a complete understanding of the various phases that come together when invoking a GET or a POST request. Even further in the chapter, we learn several tips on speeding up our applications by bypassing JSF phases by applying various properties to specific Controls.

Additionally covered in the chapter are property adjustments and various control properties that will improve memory usage, decrease costly re-writes of rendered markup, and otherwise speed up your XPage apps.

Chapter 17: Security

This chapter not only provides you with an in-depth overview of the security model for XPages applications, but also gives into things you will see when writing your XPages apps and you run into an environment where */* isn't a LocalDomainAdmin.

From ECL considerations to Server Document settings to ensure that your developers [or better yet, the Signer of your production apps] has the appropriate levels of access needed to perform whatever functions their app is intending.

This chapter is not an overview of traditional/core IBM Lotus Notes and Domino security, but rather covers the details you and your admin will need to be familiar with when using XPages in your production environments.

This chapter concludes Part VI, and we start Part VII: Appendixes with the next chapter.

Appendix A: XSP Programming Reference

This appendix covers in local and online resources such as XSP Java Classes, the XSP-specific sections of the DDE Help database, and others.

Appendix B: XSP Style Class Reference

This appendix covers, well, the XSP Style Classes. The first section covers the core XSP Stylesheets where subsequent tables list the Style Classes in a Style Class, Description, and HTML Tag format.

Quite useful for a quick-reference if you want to know what class you'll use to make your unread columns background-color green.

(It's xspColumnUnread btw...)

Appendix C: Useful XPages Sites on the Net

Mastering XPages - Appendix C: Useful XPages Sites on the Net

In what I can only assume was an attempt to nullify the credibility of the previous 726 pages, I was shocked to see this site listed as Useful.


I have a correction to my First Impressions review:

An amazingly solid start to what might be [The] most important published work for the IBM Lotus Notes Domino Application Developer.

There... that fixed it.

Each chapter [where appropriate] comes with a downloadable demo NotesDatabase, which can be used in-tandem with the contents of the chapter to give those who learn via hands-on vs. written-word a more tactile learning experience. Used in combination with the contents from these chapters, I suspect most developers would be employing XPages-based templates available with 8.5.2 in their environments and making slight tweaks where appropriate. The use of the 8.5.2 Discussion Template as an example in the early chapters was a smart move and gives even novice developers an immediate best practices demo as well as a working example of a target for what they'll be able to do with XPages.

This review may be gushing, but if you're reading this site... this book was written for you. XPages are the future of the IBM Lotus platform, and this is indeed the most comprehensive guide to the technology published to date.

The release of this book has spawned a Skype-based book club that meets every Thursday at 8PM Eastern to discuss each chapter (which I hope they keep going), I believe it sold out at the IBM Store at Lotusphere 2011, and is quite possibly one of the most important publications available to the IBM Lotus developer.

Mastering XPages Giveaway

As with all of my reviews, I am giving away a copy of Mastering XPages [with special thanks to IBM Press]. While you can purchase a copy for yourself at the Amazon Store, I want to give you a simple way to win a copy... if for nothing other than reading this incredibly long-winded review.

To enter for your chance to win, simply comment on this review.

I will pick a name at random from the comments on this post on Friday, April 15th, 2011 at Noon Eastern and be in contact with the winner... so please make sure you include a valid email in your comment so I can be in touch.

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.