As application designers, you are challenged with finding ways to provide the application with rich, functional user interface components to accommodate the creation, modification, and presentation of data for Lotus Notes clients, web clients, and, mobile devices. This section reviews the form
, a traditional design element for Domino applications, followed by the newest member of the Domino design elements: XPages. We discuss both and provide best practices in Domino application design along the way.
In traditional Domino application development, a form is used for a variety of purposes, many of which we briefly review in this section.
On a form, you can define fields which are used to hold a variety of data to be stored within the Domino application. The following figure shows a form example from the Domino 8.5.x Discussion Database:
The form contains fields, which house the metadata entered by the user, computed by Domino, or computed based on the results of an external process (depending on the design of the application).
Another important task that you must accomplish is to make the form functional and easy to use for the user. This is the basis of user interface design, as shown in a newly created document using the above form:
Notice that the metadata (Subject, Category, and Content fields) are bound to the form and its actions (Save and Close, Mark Private, or Cancel.), creating a tightly-coupled
relationship between the form and document metadata.
Business logic container
Also tightly coupled to the form and metadata is the business logic (custom programming). Business logic can include custom workflow processing, integration with external systems, and other computational functionality as needed. Since this is defined within the form (which contains the fields), there is an even greater tightly-coupled relationship between the document metadata, the form, and the business logic used to process it.
One of the biggest challenges of traditional Domino application design is to create a useable, functional interface for the Notes Client and web browsers. Traditionally, it is common to create two forms – one for use in the Notes Client and the other for use through web clients, each containing their own user interface components and associated business logic for the respective client. While this provides the desired results, we often find application maintenance a challenge, for you must implement each new feature twice.
Introduced in Lotus Notes and Domino version 8.5.1, XPages offers a whole new way to design, develop, and maintain Domino applications for various clients (Lotus Notes, web browsers, and mobile devices). In effect, XPages gives a "write once, run anywhere" approach to application design. Here we explore some best practices for using XPages, including the integration with forms, server-side verses client-side processing, and rendering hide-when scenarios that, if implemented properly, will produce fast, efficient applications that are easy to maintain across various clients.
An XPage is a design element (similar to forms and views) that you can design to perform the same functions that traditional Domino design elements, for example, Pages, Forms, Views, Embedded Views, Navigators, Outlines, and more. As an example, the “myDocuments” XPage from the Domino 8.5.3 Discussion Template is shown below:
There are many different types of information that are present to the end user, all of which are contained in a single XPage. These items originate from the Controls List (along the right side of the screen), and are implemented in a drag-and-drop fashion. For each control, you can populate various code segments and properties to give the look, feel, and functionality that you desire.
While this might not seem like such an accomplishment, consider displaying the Discussion application using the traditional Domino view elements, as shown in the following two figures.
This figure shows a traditional view displayed in the Notes Client.
This is a traditional view displayed in a web browser.
With respect to the above user interface displays, it is important to note the following:
- Dissimilar user interface: Note that, even though there is only one application, we must contend with two user interfaces – one for the Notes Client, and one for the web browser. This can increase user frustration which can impact application usability.
- Navigation elements: When two user interfaces are required, the developers have to define each piece of functionality twice – once for the web browser, and again for the Notes Client. Depending on the navigation element desired, this can greatly increase application development and maintenance time.
Other traditional Domino application design elements can provide the same level of dissimilarities in multiplatform development efforts.
The following two figures are user interfaces for Notes clients and web clients. These user interfaces have the exact same information but are with a single XPage-based design element.
This figure shows the XPages displaying a view In the Notes Client:
This figure shows the XPages displaying a view in a web browser:
The benefits of using XPages in the development of the user interface of a application should be obvious – you can create a single application that has a uniform interface and functionality, across the Notes Client and web browser platforms.
From a fundamental application development viewpoint, it is advisable to fully utilize the XPages UI paradigm in application development.
XPages and forms
You can use a form to define the user interface, the metadata and integrated business logic for Domino applications, typically using one form per platform. Whereas, using the new XPages design methodology, you limit the use of forms to defining the metadata for a document only and use XPage to build the functionality, business logic, and user interface once. These are usable across multiple platforms.
As an example, consider the following Main Topic Form from the Discussion template for Lotus Notes 8.5.3:
Here, the fields (the metadata), the actions (or business logic, along the right side of the diagram), and the user interface components (for example, the graphic in the background) are tightly bound to one form. Two forms are built, one for the Notes Client and one for the web browser.
Using XPages, you can use forms just to define the metadata, as outlined below:
- Define a form which contains the fields only (the field name, data type, and computed and editable properties and respective computed formulas). In XPages terminology, this form is referred to as a data source.
- To design the actual user interface, define an XPage which uses the data source from step 1 . This makes the appropriate fields available to the user for data entry and manipulation.
- The result is a single design element (the XPage) that can be used to create, edit, and delete documents using a consistent user interface and a single set of business logic.
To demonstrate, we use the Domino Discussion template for Notes 8.5.3. On this XPage, we find another XPages element, a Custom Control, as shown below:
The Data source field on the top of the right pan , shows that this XPage Custom Control is linked to the data source (that is form) called dominoDoc, allowing you to create documents using this form through an XPage (think of the XPage as a "front end" to the form).
In addition, you can place the metadata from the form on the XPage in a more "freely-flowing" format, giving you a user interface design that is flexible, functional, and modern. If we view the properties of the XPages Custom Control, you can see how this control and the data source are linked together:
A brief explanation is given below:
- Default action: The value newDocument instructs XPages to effectively create a new document, by default, whenever this Custom Control is presented to the user.
- Run form validation: If you have input translation and input validation formulas on you form, “on document save” instructs XPages to process those formulas whenever the document is saved. Although the preferred method of validation is to place the validation code on the XPage itself, Domino gives you the flexibility (which is especially useful during application migrations from traditional to XPages design methodologies).
XPages data validation and translation
Validating the value in a field is a common programming technique and requirement. Assume your form required a a field called Subject that is a required field (in other words, you cannot save the document unless this field is populated). To accomplish this, you can write an input validation formula for the field, resembling the following:
@If(Subject = “” ; @Failure(“Please provide a subject”) ; @Success)
This approach has the following implications:
- From the Notes Client side, execution of this formula would be fast, for the formula is run on the Notes Client.
- From the web client side, because web browsers cannot execute @Functions, the execution of this formula would result in a round trip to the server for processing The browser would execute the validation formula, and, assuming that the Subject field is empty, return the result of the @Failure message.
With XPages, you can implement the same validation technique as shown in the following figure:
You simply highlight the Subject field, and, using the properties panel, to instruct the XPages that this field is required, and the message to display to the users if they do not enter data into the Subject field.
The result of using XPage validation is as follows:
- The validation properties execute identically on the Notes Client, web browsers, and mobile devices.
- The validation occurs on the client-side, maximizing application performance.
Note that the validation is not limited to the simple validation shown above. You can write full-scale business validation logic, instructing XPages to execute the code on the client side for maximum performance.
Visible versus hiding
With Domino application development, you have a number of tools which can change the user interface for the user at runtime – giving you power and flexibility over what the user “sees” and, how they ”see it.” This section review the techniques commonly used in traditional Domino applications (the hide-when) as well as the newer techniques brought by XPages (visibility and rendering).
The hide-when options
Domino application development provides a mechanism that let you decide what user interface components (fields, text, buttons, actions, graphics, and so on) that a user is presented with when they open an application. These options, called hide-when options, allow you to quickly and easily hide various components from a user based on a host of criteria, including:
- When a user opens a document for reading
- When a user opens a document for editing
- When a user prints a document (Notes client only)
- When a user previews a document (Notes client only)
- When a user copies a document to the clipboard (Notes client only)
- When a user views a design element that is embedded onto another design element (for example, a view embedded on a form)
If these criteria are insufficient, you can also write a custom formula that must evaluate to true or false. In the event that the formula evaluates to true, the element will be hidden. If the formula evaluates to false, the element will be displayed.
As an example, see the anatomy of a hide-when properties box in the Main Topic form of the Domino Discussion template from Lotus Notes 8.5.3:
Domino automatically applies this formula based on "paragraph" boundaries, which include:
- Every item between the last time the user pressed the Enter key and the next occurrence of the Enter key
- The cell of a table
If you would like to fully understand the boundaries of the hide-when option, perform this experiment:
- In a test application, create a form named HWTest.
- On the form, press and hold the letter “A” key until you have multiple lines of the letter "A" on the form.
- Select one of the letters in the middle of the page, right-click to bring up the properties box, select the hide-when tab, and select the option "Hide When Editing".
- Preview the form
When you preview this form in the Notes Client (or a web browser), all of the letter A’s are removed. Why? Because the hide-when formula was applied to the entire paragraph since we did not press the Enter key, the formula was applied to all of the letter A’s back to the first occurrence of the letter A, and forward to the next occurrence of the letter A.
The visible property
XPages introduces a new property, the visible property, which allows you to choose whether you would like to view or hide an item at runtime.
Consider the following example from our sample application:
You have the navigation custom control selected for checking the Visible property. This instructs XPages to show the element on the client when you open this XPage. If you clear the checkbox, the element is sent to the browser, however, is hidden from us.
Note the diamond icon to the right of Visible in the graphic above. This is an indicator that allows you to write a custom formula to programmatically control the visibility of an element. If there is code behind the diamond, then there is custom code behind the object. If the diamond is clear, then there is no custom code behind the object.
To fully utilize the visible property, you must understand the difference between the hide-when and the visible property. In summary:
- The hide-when option instructs Domino to hide the element when the formula results to true.
- The visible property instructs Domino to show the element when the formula results to true, or the checkbox is checked, which automatically returns true.
Rendering and visibility are often confused as being the same thing. While the end result is the same, there are some vast differences that you can encounter that can ‘make or break’ an application, including processing, delivery, and subsequent dynamic updates to the user interface.
Whereas visibility is generally done on the client, there are limitations that you will encounter when determining the visibility of an object, including:
- All information about the page is sent down to the client, regardless of whether it will be actually visible to the user. This can cause more data to traverse the wire than you actually need.
- Visibility is a fast way to dynamically update the user interface, for, since all data is in the browser, updates to the interface can occur quickly because processing occurs on the client.
- A limitation of the visible property is that all data required determining visibility must be pushed down to the client.
A situation might occur where the determination of visibility may reside in the value of data sitting on the server. Since the data is not on the client, you e cannot use that value to determine visibility.
Server-side rendering allows the Domino server to determine the visibility of an element, dynamically updating the user interface by passing data back and forth between the client and the server. The server, while processing an XPages component, can determine whether to send the actual component to the client.
The use of server-side rendering has its considerations, including:
- All processing of the user interface is done at the server, thus, more server resources might be consumed.
- Since the server must make the determination of whether an element is visible before sending data down to the client, performance of the application can be impacted.
As a best practice, it is always best to use client-side rendering when possible to assure that the application will scale and perform optimally.
Sharing design elements using custom controls
In traditional Domino application development, it is customary to design applications which promoted code re-use, componentizing the respective design elements for reusability. Some examples of traditional design elements which meet this endeavor include the subform, shared actions, shared fields, and more.
This section reviews traditional Domino design elements promoting code re-use, and, how they apply to the new XPages development paradigm.
Assume that, as part of your application design, you require the same fields on various forms through your application in the same layout (that is. user interface), translation and validation formulas (among others). Traditionally, you could use the Subforms and Field to accomplish this goal by
- Placing each field on each form, independent from one another (or, use shared fields so that we only have to define the field one time).
- Placing the fields on a subform, then insert the subform into the main form as needed.
Because the XPages do not support integration with subforms, the above approach is a challenge in the application design.
When designing a new application, or, modernizing an application to use XPages, remember that direct subform integration, as well as other traditional Domino shared items, are not supported. For more information, see Domino Designer help for information related to traditional Domino design element integration with XPages.
A custom control is a reusable design element used in XPages that can contains various pieces of information, including, but not limited to:
- User interface components
- Business logic
- Static information
- Dynamic information
Similar to subforms, you create a custom control in Domino Designer, and insert the control onto one or more XPages. Thus, modifying the custom control automatically update each of the XPages that use it (promoting code re-use).
One example of how custom controls can help you build powerful applications is the integration of XPages applications with OneUI, a series of custom controls that permit you to develop consistent, reusable standard interface objects, navigation object, and more. For information about OneUI, see: http://www-12.lotus.com/ldd/doc/oneuidoc/docpublic/index.htm
Creating a simple custom control
Use these steos to create a new custom control in Domino Designer:
- Click New Custom Control, enter a new for this new custom control and select the application. See the figure below:
- After clicking OK, you are placed into the custom control editor in Domino Designer.
Drag the button component from the controls list onto the new custom control, as shown below.
- The result is a single button whose properties you can modify to control the look, feel, and functionality of the button. In this example, we change the Label property to "My Custom Control", which results in the following:
- Save and close the custom control.
To reuse the custom control, create a new XPage in Domino Designer, as shown:
You can easily see all custom controls in Domino Designer by looking at the Custom Controls list in the lower right section of your screen. To use the custom control on the newly created XPage, you simply drag and drop it to the desired location, as shown:
Upon preview in Lotus Notes, you see the following XPage with your newly created custom control.
Note that the above XPage appears virtually identical in other client environments, such as web browsers.
Assuming that you use your custom control in multiple XPages, if you change the custom control, you automatically propagate that change to all XPages that it is used on, promoting element and code reuse.
You can now repeat the process of re-using the custom control on a variety of XPages, taking advantages of user interface design and code reuse in your Domino applications.
Domino provides you with a host of application design features. When developing a Domino application, consider the following:
- Create forms to define the metadata for documents, and integrate associated Lotus script agents in the appropriate events (QueryOpen, QuerySave, and son on).
- Use XPages to develop the actual user interface, using the respective form(s) as a data source for the XPage.
- Use XPages to develop applications to write applications and support multiple platforms consistently.
- Carefully consider the use of server-side versus client-side data validation to prevent round-trips to the server for data validation and translation. Use client-side validation and processing when possible.
- Carefully consider the use of the visible property versus rendering to assure that the information that the user sees, as well as the application functionality, is processed correctly.
- Use custom controls over traditional Domino shared design elements (such as subforms, shared actions, and shared fields) to create reusable user interface components, business processing logic, and other reusable elements in your application development efforts.
Parent topic: 5.0 User interface considerations