Section II - High level introduction to XPages 

Table of Contents | Previous Page | Next Page

Introduction to this section

XPages are new design elements in Lotus Notes and Domino 8.5 and 8.5.1. To begin using and designing XPages, you need to have a Domino 8.5 - or even better - a Domino 8.5.1 server and a Lotus Notes Designer client.

So what are immediate benefits of using XPages which make them so important?

First, these new elements allow an Application Developer to quickly and easily create rich web applications in Domino with a Web 2.0 application look and feel.

• XPages can be used to incrementally enhance an existing application or write a brand new one
• XPages are fully integrated within Domino Designer
• XPages decrease the time for writing Web Applications
• Starting from 8.5.1 they also run in the client promoting same source – multiple rendering application development

Additionally, XPages provides the developer with many “out of the box” features that previously would require lots of custom development to achieve such as:

• Type-ahead
• Field Validation
• Partial Refresh
• Date Time Picker
• One UI theme - so great default UI without any work
• Others – File Upload, File Download controls, Dojo Rich Text Editor

The necessary steps to start is to have a Domino 8.5 or 8.5.1 server running, and of course a Lotus Notes Designer 8.5 or 8.5.1 client. You should ask your Domino administrator to launch the HTTP task to be able to start a whole new great way to develop Lotus Notes application for the web. Since XPages are fully integrated within Domino Designer, you have nothing additional to setup, except to launch the Domino HTTP task on your Domino server. If you are an advanced administrator you would like to know how the Domino server can be tuned to your requirements in terms of security and performance, please consult the Server Configuration section of this Redbooks wiki.

New Design elements for XPages

Once you have opened the Notes designer client, you can access two new design elements:

• one is simply XPages,
• the second is Custom Controls.

So what is the relationship between XPages and Custom Controls?

• XPage development is structured by using XPages and Custom Controls
• XPages are the main “scenes” for each part of your application
• Custom controls are the componentized “parts” of your applications functionality
• Custom controls are essentially “Sub Forms on Steriods”

Reviewing the XPages Design Element

For developers already familiar with Notes and Domino development, the XPages design element is as simple as a new form or view design element. For developers new to Notes and Domino application development, XPages are now an integral design element, similar to the other Lotus Notes database design elements.

Creating and exploring a new XPage

To start a new XPage, you just have to select the XPage component, and you will then be able to design an XPage component.



Clicking on XPages will allow you to start creating a new design element in your Notes database.



As you can see from the screenshot above, you need to name your new component. Enter in some comments about the component as a best practice to document your application, then select in which application you are about to create the new design element. By default, it is supposed to be created in your own application.




Once you create the new XPage component, you are presented with the same, familiar Lotus Notes blank design element as shown in the screenshot above. (The appearance of a new XPage component is similar to any form or subform). To begin, we have decided to just show the basic component. As you can see, you do have just two tabs, the Source Tab and the Design tab.

Clicking the Design tab allows you to simply drag and drop components or type in some text. Components we said? Yes the great improvement for XPages is that you can now start applications with internal and external components to help you speed up your web design development within Lotus Notes. For the seasoned Lotus Notes designer, we can really compare this option to the use of subforms and/or shared fields. As we will demonstrate throughout this wiki, the use of components in XPages enables much faster and more efficient development.

Clicking on the Source tab you will discover what is behind the simple blank page!



As you can see from the image above, yes! Domino goes XML at last! So the fabulous blank page we have just defined is actually a powerful XML component. That means that now Domino will allow us to use powerful XML based design concepts. XML is generated automatically as you drag and drop controls or while you are working on the XPages.

Reviewing Custom controls

Another new design element is the Custom Controls. To better understand Custom Controls, keep in mind that XPage development is structured by using XPages and Custom Controls.

• XPages are the main “scenes” for each part of your application
• Custom controls are the componentized “parts” of your application's functionality
• Custom controls are essentially “Sub Forms on Steriods”

To create a new Custom Control, you will find them located just beneath the XPages option and above Framesets.



If you select this Lotus Notes design element you will be able to create a new custom control element or edit existing one, similar to working with any of the Lotus Notes design elements.

Introduction to the Outline Eclipse View and the Component Eclipse View

The following section introduces the Outline View and the Component View, two essential views which allow you to work efficiently with your components.

The Outline Eclipse view

The Outline view allows you easily select any component on your XPages. To access the outline view, first click on Show Outline Views, then click on Outline, as shown here.



The screenshot below illustrates what you will see within the outline view.



It allows you to move quickly from one component to another.

The Component Eclipse view

The Component Eclipse view is an essential tool which you will also find very useful. It is a view which contains all standard components as your very own components. You will only have to drag and drop your components onto your XPages to just use them. (Keep this ease of use in mind as you think back to the earlier approach in Domino design of using subforms and shared fields concepts in standard Lotus Notes design).

Considerations for Composite Application Development and XPages

Composite application development was first introduced in Lotus Notes and Domino 8. The new release allows designers to add XPages to composite applications. So, basically you can develop custom controls and add them into your composite application editor as components.

Design precisions

As an experienced Lotus Notes Designers you probably have noticed that we did not talk about alias (or synonym) for the two new design elements, right? Well you will need to forget that option for those two new components, as it is no longer relevant.

XPages definition

XPages based on JSF

XPages technology is based on Java Server Faces (JSF) from Sun. The JSF Framework is dedicated to build Web 2.0 applications and is based on components that Java developers can compare to Swing or AWT (Abstract Windows Toolkit). The component state is evaluated during execution and for the request time of life.

JSF simply uses the MVC architecture model for the modeling part (Model, view and controller) and JSP by default. But concretely, you can use it with other technologies, for instance, the IBM Lotus Notes client 8.5.1 is using XUL to render XPages.

JSF is composed of a set of APIs to render and manage components, their states and events and inter-operatibility between them.

The only limitation is that JSF standard components are too limited for Enteprise development for companies. So, JSF turns to be the start of a better interface for developers who want to publish a better Framework.

Accordingly - IBM has used the XPages to accommodate JSF limitations and integrate the possibilities of the Framework into Lotus Notes for Web developers and simplify the Lotus Notes development process and work on the Web side.

This technology was introduced to simplify web development Inside Lotus Notes for future web applications. Even if you can upgrade existing Domino Web application to XPages, starting from scratch is a good solution to learn and manage the XPages concepts. (We discuss both approaches more in the sections on Building Sample XPages applications - See Introduction_to_enabling_existing_Notes_Client_Applications_using_XPages, and Building_an_XPage_web_application_from_scratch)

So how can we define XPages technology in Domino? Domino replaces the servlet aspect used by JSF using a pure XML engine. So the http task includes the XSP engine. Temptation is easy to compare XPages to eXtensible Server Pages (XSP). Of course, they both focus on separation of content, logic and presentation, but XPages are a component of a Lotus Notes database, which is not limited to either server-side, nor to Java. Moreover, XSP is loosely defined and contains a limited set of instructions.

Understanding the XPages definition within a Notes and Domino Context

For java developers, Swing can be considered as participating in the Model–View–Controller (MVC) model. But for Swing , it plays the Controller part which can use internal views to interact with the user interface. Swing components are lights if you compare them to AWT. AWT is using native components.

XPages introduces that MVC notion. But let’s first go back to the traditional Lotus Notes designer to put this into a more specific context for Notes and Domino Developers.

With Lotus Notes (the client), developers do have the possibility to use views, forms, subforms (the View in MVC), documents and profiles (the M in Model), and Lotus Notes and Domino (the Controller). But in this architecture, the form also plays the role of the model, so the form and the documents are tightly bound together and that can result in some tricky situations when you do need to go on the web. As you know, code is mixed with components elements and porting the application to the web can make the maintenance harder. For the Domino developper (aka web designer), Domino gives them the possibility to divide some portion of code into the MVC model. Remember the « $$ViewTemplateDefault » and « $$ViewTemplate For » objects you can use and abuse? But, you will need to use the « WebQueryOpen » and « WebQuerySave » events to define the logic of the application. So, you will not be able to divide the model from the view component of the MVC model.

The XPage technology will help you make a more logical separation. First the repository will be the form where you just define the data types and Storage. The controller is Domino or the Lotus Notes client in release 8.5.1.

In designer you will use the XPage to define the user interface and business logic, while the form will be used for data Storage. Based on this statement, you may be thinking, "well, where is the MVC then?" This is really simple: the XPage is the View in the MVC model. In the XPage, you will be able to define the business logic running on the server (then here is our C for controller) which is managed by the http task of the Domino server.

The two diagrams below help to explain and support this approach:

The classic MVC model
This image illustrates the classic MVC Model architecture

The MVC model for Domino
This image illustrates the The MVC model for Domino

Why should I care about XPages technology in Domino

If your are not a Domino only shop, but also use additional Lotus products such as Quickr, Sametime, and, or WebSphere Portal, you will most likely soon be confronted by your end user community to develop a coherent User Interface among all the software servers you are using. XPages technology will simplify this effort, thanks to the OneUI themes. Alternatively, maintaining such an interface with all these different products will be significantly harder to do if you instead continue using the traditional Domino development design elements. Even CSS files are not sufficient to share information between all platforms.


Additional benefits which result from shifting toward XPage development include:

Separating Data from Presentation
The ability to more easily achieve a common User Interface between products and applications, while important, is certainly not the only goal to strive for. The more important objective is to separate the data layer from the presentation layer in all developments. With traditional Domino design, most presentation layers are tightly integrated into the data layer (with the forms, subforms, etc.), and in some complex development instances, this can result in an application which is extremely difficult to maintain. Keep in mind, it is not necessarily the result of the product by itself, but that many Lotus Notes designers have not documented their work. Accordingly, in terms of maintenance, it may be necessary to get third party products and spend significant time and effort to reverse engineer the original approach.

More possibilities for incorporating Java and executing LotusScript
Many designers have already developed within Notes using object oriented LotusScript libraries (or of course Java). But, we all faced the same limitations in that LotusScript can be executed only under certain conditions with Web applications, primarily using Agents. Java is also limited in terms of its integration with with traditional Lotus Notes development. So if you rely heavily on Java, XPages will allow you to go far beyond your earlier expectations with Lotus Notes.

Built on standard, proven technologies
The advantage is that Domino relies on standard technologies, so there is no proprietary code to manage. The technologies in use are Java, Javascript and CSS, so you will be able to find a vast array of resources on the web to help you with any development, sharing information, code samples and tips with designers from different horizons. Additionally, you will be able to delegate any design or development parts of your application to other team members with skills in these common technologies.

Custom Controls simplify development
And last but not least, the use of Custom Controls with XPages, will simplify your development effort tremendously! You will be able to exchange and reuse many components developed either by you directly, or by OpenNTF or other sources (including IBM). You are able to take advantage of these components, while still using the standard Lotus Notes mechanism to upgrade your applications (templates, etc.) so you will gain in productivity and efficiency.

In conclusion, using XPages will allow you to be more efficient in your development of great looking Web 2.0 applications without losing any existing Lotus Notes knowledge you already have in your organization.

What are the benefits over traditional Domino Development

Finally, we address the question of benefits from XPages development over traditional Domino development techniques. We will approach this topic using a framework of traditional Domino Design Elements for reference. As an experienced Domino Web designer you are accustomed to use many features that IBM Lotus development team had developed and ultimately "fine tuned" for web delivery. Basically Domino can run fine on the Web, but due to some inherent design limits, you needed to use some specific features bound to Lotus Notes architecture. For example, you have most likely developed some special forms to display views (the well-known $$ViewTemplate..... named objects) and some other components. In this section, we will list some of these traditional limitations and discuss how you can benefit by embracing the new approach in XPages development.

One approach for developing in a mixed environment

For web designers developing in a mixed environment (e.g. developing for Notes client users and web users), this often requires developing the same view twice, with each one slightly modified for the Notes or browser client. For instance, a Lotus Notes client user may need to see text headers, while the browser client should display more elegant column headers in a view. XPages provides direct benefit in this case. Using XPages, you can develop the code once and have it render properly as an XPages application - with an identical rendering in either a browser, or using an embedded browser in the Notes 8.5.1 Client.

So as a Designer you will use the same technology for the Domino server (web clients) and for the standard Lotus Notes client.

What is behind all of this? This is possible by selecting a simple option in the database property.




Alternatively, if you are running a Basic Lotus Notes client, (a version earlier than Notes Client 8.5.1) you will have to manage an option to tell the user that your application will not be able to take advantage of the new XPage features. One possible strategy for this is to dedicate the Lotus Notes basic client to a limited environment or to older machines with less powerful CPUs.

The Lotus Notes client can also handle its own theme if you want to distinguish the interface between the Notes and Web client. The theme can be defined globally to all applications on the server. Alternatively, some applications can be refined to use the global theme or use them on their own. We urge your to take a look to the sample applications and tutorials described within this Redbooks wiki, and to review the Section for Server Configuration for the location of the themes.



Yes, this is a very powerful concept - "so if I do develop an XPages oriented application, I will no longer be faced with many of the earlier limits which existed for running applications on the Lotus Notes client?" For example:

• One view with multiple columns and multiple XPages presenting the data according to my needs all on the fabulous Lotus Notes client?
• Must I go to the web also for the thin web client?
• What about off-line applications? For web applications, we know that these can be used off-line if developed for a local replica, but the other important point is that the Lotus Notes client can also go off-line with XPages as a normal Lotus Notes application. The only requirement for the end user is to know how to replicate the database to the Domino server from their local client machine.

The next screenshot shows a standard XPage application running into the standard Lotus Notes client. The application is inheriting from the Lotus Notes discussion database.



As we know, the Lotus Notes client is limited compared to the Domino server in terms of extended capabilities. The IBM team in charge of this new feature decided to integrate an independent web technology into the Notes client. The core is of course XML. since an XPage is basically XML. This allows a new Lotus Notes developer to be able to get into Lotus Notes design on their own for free (yes, the designer is free) without the use of a heavy Domino server on a a machine such as the typical laptop.

Improvements in Views

View design elements are arguably the main point of entry into any Lotus Notes application. We mainly use views as an entry point to allow end-users to access, create and / or modify documents. Accordingly, as a Lotus Notes designer, you need to spend a lot of time anticipating and determining the specific information that end-users want to see and manipulate.

Another problem can arise when talking about methods used to sort columns. To solve this challenge and arrive at the properly sorted / categorized view, some Domino designers have decided to design many views. Keep in mind however, that all those views are negatively impacting the overall Domino server performance. Additionally, a solution requiring multiple views that contributes to more analysis of your code from administrators who, in many cases, will not accept this design and development approach on a production architecture. Wouldn't it be much simpler to just have one view with all sorting options set and just use a design element that will allow you to select which column to use without impacting the server performance? XPages provides this solution. An XPages designer can select which column will be displayed just by selecting the columns from the view depository. This is a significant step forward for Lotus Notes design.

Another common challenge with views is that showing multiple views on a single page is not so easy. Of course, Lotus Notes can show multiple views, but our goal is to show only a portion of a view in one case and another, different portion of the view in another case. The XPage allows you do that and also to refine sort columns according to the context of your application. The designer simply needs to activate the sort option on the view column, and then choose whether or not to use it on the XPage. This allows for sorting options according to some specific conditions.

Finally, traditional Domino Development has made it difficult to link one view to another. In the past, we used framesets or better, composite applications, to solve this issue. Going forward, you will now only have to use XPages.

Improvements over traditional View templates

Designing forms named "$$VewTemplateDefault" and "$$ViewTemplate For <view name" allows designers to display Domino views in a great looking way on the Web. This is certainly one approach, but is also limited. To work beyond these limitations, you will need to use Style Sheets and thus to define a correct style sheet within your application. Furthermore, you need to configure the whole server to have the same style across all your applications on that server to arrive at a common look and feel.

Alternatively, using a theme, a feature within XPages , will now help you in achieving the same goal. Themes contain information on which style sheets to load (computable) and any theme information for the core controls (also computable) – you set the theme to use in the database properties. Most importantly, using themes allows you to implement this in such a simple way that you will be more productive and efficient in your application development.

Improvements based on the traditional Form element

Working with XPages requires a slight adjustment to your thinking and approach to using traditional Notes and Domino Form Design Elements. No, you cannot use a form directly within XPages. Instead of using a Form design element to display a document, you will instead need to use an XPage to display the document. For example, to display documents developed with a form called "Memo", you will have to develop an XPage called "Memo". By default Domino will try to find an XPage of the same name. In the form property, you will be able to change the behavior and to select a specific XPage to display the data. Keep in mind that when we say the "display", this is a very restrictive term. An XPage can be used to create/display and modify data.

So how will you work now? If a form cannot be used directly in XPages, what should we do? Should developers simply ignore Forms? No! XPages will just simplify your design.

What was wrong with traditional forms and why don't they apply going forward? Well, think back to your early stages of development in Lotus Notes. You simply added a form into a Lotus Notes Database to gather inputs and display information to the end-user. Basically it was easy at first sight. Eventually however, as the application grew larger, you often end up with a form being an object containing code, interface components, etc. So why don't we use the form simply to store information into a Lotus Notes database?

Here is where the XPages element comes into the picture. The XPage uses the form to store data into the Notes database, and only data, so the form ends up to be a repository for data and will not contain code anymore. Forms are used only to store data, but not to display the data, thereby eliminating the presentation aspect. Accordingly the end user will never "see" the form again. You can now consider the form as "hidden fields" and data storage.

All the application logic controls are now done at the XPages level. As a designer, you will be able to select where and when this control will be done. For example, you determine if the control will be executed at the server level or not, and during which event the control is executed. In the past you needed to use agents for control execution with web development.

Additionally, if you still want to do some data processing within the form, you can simply activate the computewithform event in the XPages properties for Documents.

Finally, another common challenge requiring maintenannce and workarounds was how to show multiple documents linked together on the same page. Few Domino Developers had used the Editor embedded element that was present in the Domino 6 system to solve that issue. Now the XPage technology will help you doing that a simple way. Data can come from documents from within another Lotus Notes database or even from a non-nsf database.

Improvements to the functionality of WebQueryOpen and WebQuerySave

These two agents - namely the WebQueryOpen and WebQuerySave agents have constantly been a real headache for Domino administrators. The administrators needed to verify security and performance before deploying these to any web application.

As a reminder, WebQueryOpen agents were designed to allow some modification to the document just before Domino renders it to the HTTP client. The WebQuerySave agent is a tool that allows designers to modify some information before the http submitted document is saved to the Lotus Notes database.

Essentially, this approach interferes with the document on load and then during the submit events. So to accommodate this, you often need to use Javascript on your own using javascript libraries. XPages now will help you solve such limitations.

You will no longer need to develop specific agents, but instead, the core XPages functionality will allow you to define code on specific events of your application.

Improvements to Rich Text Field Management

Richtext field management has been a complex area for Domino Developers, often requiring a special tool to properly manipulate Rich text data. Within XPages, the editor is now rendered with Dojo and there is an active rendering filtering that helps designer to forget about the complexity of rich text rendering while editing or rendering display state.

Built in AJAX support within XPages

To update lists fields, Domino submits the whole page back and forth to the sever. That is less than ideal when you need a responsive application on the Web. To solve this, one approach is to setup AJAX in your traditional Lotus Notes development environment. The downside is that setting up AJAX requires time and energy. Additionally, when you are working on views, changing the sort order will enforce you to use XML to do fast treatment. Woudn't it be great to get a better way to do this with just one click and just right out of the box? XPages addresses this through built-in AJAX support so designers will be able to use partial page refresh and type-ahead features.

Performance Improvements related to XPages

XPages provide significant performance benefits for your Domino hosted environment. If you compare XPages to the traditional Lotus Notes development techniques for the Web, XPages brings new performance improvements. Much of this is due to the fact that in the traditional Domino development approach, both the Data layer and the Presentation layers are linked together with the form architecture. As a result, the Domino server has to maintain in cache the whole document and form until the end of the user action. Within XPages, IBM has setup the NotesXspDocument, which in fact is only alive when an exchange between the client and the Domino server is needed. When rendering an XPage, the Domino server loads the Notes document in memory, creates the NotesXSPDocument, and then removes it from memory. This performance efficiency will be especially noticeable on an overloaded Domino HTTP server.

A simple way to optimize your application is to define how the Domino server will handle XPages performance.



The server default option can be configured in the server properties. (Note - please refer to the Section on Domino Server Configuration for XPages for more specific information about this setting.) Alternatively, the other option that can help designers to define exactly how the server can manage the application without impacting the Domino server. According to the application type, the option selection will be defined easily by the designer. Moreover the administrator can also easily change the application behavior without launching the Lotus Notes Designer.

Closing arguments in favor of XPages

The primary problem for Domino and Web designers is one of productivity - how to develop the best applications in the most efficient manner. Lotus Notes development excellence is our goal, but in today's competitive environment, Lotus Notes designers need to be efficient, deploying simple or complex reusable objects you would use as in any object oriented language. Ideally, the only technical competency which should be required should simply reside in a mouse (namely the ability to drag and drop) or by using the keyboard to copy and paste the controls onto a blank page and start using your application. Using XPages, the pre-built Web 2.0 components and AJAX features make your life easier, while coupled within the robust secured workflow enabled framework provided by Lotus Domino. You also can take immediate advantage of custom controls that will help you clearly and simply define your interface and actions.

In favor of ONE

In summary, what definitely can help you decide to go XPages is based on the concept of "One". For example, we always - as veteran Lotus Notes designers - tried to have one of everything:

• One client
• One template
• One interface
• One server
• One language
• etc...

The simplicity of One is certainly appealing!

Eventually however, this evolved to require using:

• Multi-languages (@formulas and @command, LotusScript, Java, C/C++ api)
• Multi objects (views, forms)
• Multi everything

We can now say that much of the fuss about XPages is based on the appeal and simplicity of "One" again! Let's face it, as a Domino developer I now can develop for one client. Yes one client, since IBM has launched Lotus Notes 8.5.1 with the ability to render an XPage application directly within an embedded browser. So imagine, one form, one view for all!