December, 2008

This free article is part of THE VIEW Free Trial for Lotus Professionals. Subscribe here to receive many more articles like this one, plus new ones published every week at THE VIEW online knowledgebase.

XPages, the powerful Web 2.0 design feature introduced with Domino Designer 8.5, makes developing Web pages easier than ever. However, because Eclipse features in the latest Designer client are new to many traditional Notes developers, you probably could use some hands-on help to get up to speed quickly. Let me orient you to the new Domino Designer 8.5, paying particular attention to how it behaves in relation to XPages. To experience the ease with which you can build an XPages application in Domino, I'll guide you through creating a simple application for managing a library of books. In the process, you'll get familiar with the many controls built into Domino Designer 8.5, along with some key aspects of XPages development.

The next article in this series will go further to focus on adding a Search capability, customizing views, using the session scope to pass information between XPages, the extensive JavaScript libraries included with Domino Designer 8.5, and much more. By the end of these two articles, you will know enough about XPages to build a basic application entirely in XPages.

Let me start with a basic concept that clarifies the relationship of data in traditional Notes elements to XPages.

In XPages, the user interface is completely separate from the data. When you add fields to an XPage, you are not creating data elements the way you do by laying out fields on a Domino form. XPages are bound to traditional Domino forms and views (and most likely other data sources in the future).

When you are building a new application that will be based entirely on XPages, you will have to create empty-shell forms and views to give structure to your data. However, since the forms and views will not be used to display the data, they can be as simple as you like. Unless you intend to use the Notes client (which doesn't currently support XPages) to view the data, you can simply list the fields in a row across an otherwise blank form. Similarly, you don't have to format a view if you only use it to provide an index to the data so it can be displayed within an XPage. When you are adding XPages to an existing application, of course, you can simply bind them to the existing forms and views. You'll see where to configure data binding to forms and views later in the article.

For many Domino developers, the XPages capabilities will be the primary reason for upgrading to version 8.5. Along with XPages, Notes and Domino 8.5 also gives you the first version of Domino Designer that runs inside of the Eclipse integrated development environment (IDE), and most Domino developers have never worked in Eclipse before. So before covering XPages in detail, let's explore the new, improved Domino Designer, paying particular attention to how it behaves in relation to XPages.

Figure 1 shows Domino Designer's Eclipse-based IDE as it displays once you close the Welcome page. (I suggest that you read the Welcome page first for its useful information.)

In the top left pane, you can see the Domino Designer applications navigator. This navigator is very similar to the traditional database navigator in previous Domino Designer versions, with a few important exceptions.

First, the list of design elements has changed significantly. In addition to new controls such as XPages, custom controls, and themes, the list is also organized differently.

Second, the applications navigator includes an Eclipse feature called "working sets." In Eclipse, a working set is a group of design elements; in Domino Designer, a working set is a group of applications that includes all of their design elements. Working sets are similar to the bookmarks available in Domino Designer for the past few versions. Working sets behave exactly as expected, are very easy to work with, and are a convenient way to manage changes across a collection of applications. You can create and manage working sets through the double-folder () icon's drop-down menu at the top left of the applications navigator. Note that when you're working with a working set in Domino Designer, you can't select individual design elements to be included or excluded from the group.

Also notice the () icon to the right of the working set management icon; hovering the mouse over it displays the label "Synchronize Navigator with Editor tab." This icon represents a toggle setting indicating whether or not Eclipse will keep the various sections of the Domino Designer screen described below in sync automatically. The icon should be in the "on" position by default. In theory, this should always work. In practice, if the sections get out of sync (and it can happen), you can disable and then re-enable this setting to reset the rest of the Domino Designer environment to match the item selected in the applications navigator.

There is one other change that may take some time to get used to. Clicking on an item in the applications navigator only once will not have any effect. You'll need to double-click on "Forms" to bring up the list of available Forms in the application. Previously, single-clicking was sufficient.

Directly below the applications navigator is the outline pane. Many Domino design elements don't take advantage of the outline yet. For example, selecting forms, views, pages, agents, and script libraries (among others) in the navigator causes the simple message, "An outline is not available," to appear in the outline pane. Selecting XPages, themes, and style sheets, however, provides a collapsible hierarchy of elements within the outline. For style sheets and themes, this hierarchy is a navigation aid, where double-clicking on a given element causes that element to receive focus within the main editing window. In XPages, the outline is useful not only to display the hierarchy of elements on the page, but also to move elements to different places.

With any visual page or form layout tool, it can be difficult to keep track of which element is nested within others, and it's sometimes nearly impossible to move an element to the exact location you want on the form or page. The outline makes tracking and moving elements into a simple, painless operation. In short, the outline is extremely important and useful — don't forget it's there!

Next, in the center top section, you can see the main editing pane. Within this area, you can find the traditional lists of design elements, such as the list of forms shown in Figure 1, or any open editor. An appropriate editor automatically opens when you select or open a specific element in this pane. The editors currently available include the new XPage editor, the CSS editor, the HTML editor, the Theme editor, as well as the various design element editors Domino Designer has always had. You can launch the appropriate editor by double-clicking on the design element.

XPages and themes support two tabs in this section, Design and Source, which are visible at the bottom of the editing area (see Figure 2). The Design tab is where you do most of your work, laying out the elements using the design tools built for that purpose. The Source tab allows you to get below that layer; it is where you can see (and modify) the raw XML code that controls the functionality of both types of design elements.

Below the editing area, Domino Designer offers three new tabs: Properties, Events, and Problems. When you have a traditional Domino design element open in the editing area, this lower area will minimize to the bottom of the screen, replaced by the Object, Reference, and Code areas you are familiar with (see Figure 3).

When you are working on an XPage, the Properties tab adjusts to reflect appropriate options, depending on what you're doing (see Figure 4). For example, if you select a control on an XPage, the Properties tab automatically provides the options available for that control. Properties are grouped logically using vertical tabs on the left. Depending on what you have selected, you may see Data, Validation, Type Ahead, Style, Resources, Navigation, and All Properties as available property groups.

If you have a problem finding a particular property, use the All Properties option, which lists all available properties. Note that some properties are not part of a group, and the only way you can define or edit singular properties is to use All Properties.

The Events tab also adjusts its options and work area depending on what element you've selected on the XPage (see Figure 5). It lists any appropriate browser events (such as onClick or onChange), along with various options available to define them. You have the opportunity to write custom client-side JavaScript code the way Domino developers have always done, or you can take advantage of built-in, server-side JavaScript programming tools.

Along with options to control whether an entire XPage, or only certain of its elements, or none at all are updated with your event code, you can also choose to add several simple actions to execute in the XPage. These frequently used actions include the self-explanatory Open Page, Modify Field, Save Document, Save Data Sources, Delete Selected Documents, and Create Response Document actions, among others.

The Events tab also allows you to write custom JavaScript code to be executed on the server-side, in which case you can make use of a set of JavaScript libraries built into XPages. These JavaScript libraries mimic a significant amount of traditional @Formula and LotusScript functionality, and I'll cover them in depth in another article later.

The Problems tab opens an area that always contains any known issues within your XPage. These issues are related to compile time, not run time, of course, and may include controls that are not bound to any data elements or syntax errors in JavaScript associated with an event. You can find problems in your application by checking the applications navigator, which displays a red box with a white X next to the elements that have issues. As you can see in Figure 6, the graphic indicating the locus of an issue bubbles up so that it's visible on each parent item in the navigator, including the top application level.

On the right side of the screen, notice two more tabs: Controls and Data. The Controls tab contains the various sets of controls, such as tables and buttons, which you can include when developing the displays and user actions on your XPages. I'll cover these essential tools in detail later in this article.

The Data tab contains the data elements that the developer has bound to a specific XPage. Domino developers have two sources of data that they can bind to an XPage — a Domino document (a form) or a Domino view. Once you've chosen a particular form or view, the Data tab populates itself with the relevant fields or columns. At that point, you can drag individual data elements and drop each onto a field or control on an XPage in order to bind the two together automatically. You can also select multiple items and drag and drop them all onto the XPage together. If the data source is a Domino view, dragging multiple items onto the XPage automatically causes the creation of a View control, containing the specific columns you selected. If the data source is a Domino form, Domino Designer automatically creates a Table control with two columns, one containing labels and the other containing the fields you chose.

The field names match the field names in the data source, and in a very nice touch, Domino Designer creates labels based on the field names (but cleaned up a bit). Specifically, a two-word field name like CurrentEditor has a label containing the two words separated by a space and followed by a colon. Note that this trick only works if the field names are written in CamelCase (i.e., the first letter of each word in the compound is capitalized); if the field had been named "currenteditor" then the label would remain a single word. Given how widespread the CamelCase practice is, this clean-up trick is likely to be useful to many developers.

In addition to the various editing and property definition areas, the menus in the bar at the top of Domino Designer have also changed significantly in the Eclipse environment. The familiar menus are still there, for the most part, as well as new menus and choices, and some of them are relevant to working with XPages.

Notice the Project menu — it includes two choices that you should know about. First, by default, the Build Automatically option is selected. That means Domino Designer recompiles your XPage whenever you save it. If you deselect that option, in order to make your design changes visible in a Web browser, you must choose Project → Build All, or Project → Build Project, or Project → Working Set.

Second, notice the Project menu option labeled "Clean." If your project is misbehaving and Designer or Eclipse is giving strange errors or producing bizarre results, choose Clean to rebuild the entire project from scratch. Think of it as similar to clearing your browser cache or executing an Updall command on a database. You might not need this option, but you should know that it's there.

Enough about Domino Designer and Eclipse — let's talk about XPages now.

XPages provide Domino developers with a rich set of controls that you can drag and drop onto your element, in the same manner as controls available in typical visual IDEs, such as Visual Basic or Delphi. Many of the controls represent the field types available within the Notes client, while others provide the Web browser with functionality found in the Notes client, and still others provide functionality that the Notes client does not provide.

Domino Designer groups these controls within palettes on the Control tab; the default configuration displays the Core Controls and the Container Controls. A third palette, called "Other Controls" or "User Added Controls" (the name is not finalized as of this writing) doesn't display unless you enable it by choosing File → Preferences, selecting Palette, and then choosing to display one or more controls within that group. In Figure 7, you can see the Preferences dialog that allows you to choose which controls to display. You need the Other Controls palette when you want to populate a set of radio buttons or checkboxes from a DBLookup or other dynamic data source. Let's quickly tour the various controls available before focusing in detail on several of the most useful.

The Core Controls palette (Figure 8) provides the control elements that developers use most often, including the following:

Note that each control palette in Domino Designer has some controls that are available but are not made visible unless you add them yourself. For the Core Controls palette, the optional controls that you can add through the Preferences dialog include the Line break control, which inserts a break in text, and the Span content control, which can contain text or other controls and allows other content to display alongside it.

Container Controls (see Figure 9) are so-named because they can contain other controls — core controls, other container controls, or any other control available. Developers typically use containers to organize and group other elements; as you'll see, though, the container controls also provide some critical functionality. Domino Designer offers these container controls:

The controls that are available but not visible by default in the Container Controls palette are the Block-level content control, which contains text or other controls and allows other content to display below it, and the Pager child control, which can be placed inside the core pager control.

In the latest beta version, the Other Controls palette is labeled "User Added Controls" in the Controls tab after selection (see Figure 2). Whatever the name, it contains items that you'd probably use infrequently. Note these two, though, which may be useful to you a little more often:

In addition, the Other Controls palette also offers these controls, some of which are meaningless as separate controls but provide functionality used in the primary controls:

You can create custom controls to use with XPages by combining the other controls. A page header or footer, a set of controls to provide site navigation, or a custom view representation are some useful examples of custom controls you can build. As a general rule, you're likely to use a custom control at least as often as you would use a subform in traditional Domino Web development.

You can find more information on building a custom control in the "Designing with custom controls" topic within the Lotus Domino Designer XPages User Guide. The User Guide is available in Domino Designer from the Help → Help Topics menu. Once you create a custom control, the Custom Controls palette automatically becomes visible on your Controls tab.

Now that you know how to find controls for building an application, it's time to try using some of them as you experience some key aspects of XPages development.

The example application provides a way to manage a library of books. The fundamental features include the ability to add book records to build up the library listing, plus the abilities to edit and search for books in the library. Begin by initiating a new application in Domino Designer 8.5 in the regular manner (I named mine "Library.nsf") and then follow the instructions below. You will create the application's data schema and two XPages, one for adding new books and listing them, and the other for editing existing book records. Let's start with the data schema.

As I mentioned earlier, it's possible to create the underlying data schema with as little as one Domino form and one view. In the usual manner, create a form named "Book." Include the following fields, with no layout or formatting at all:

The form should look extremely simple, as in Figure 10. It probably seems oddly bare to experienced Domino developers, but it's all you need.

Next, create a view named "Books" and add three columns pointing to the relevant fields of the Book form:

Again, don't bother to define any formatting options.

Now you're ready to create your first XPage for your library application.

Continuing in Domino Designer 8.5, in the applications navigator, select XPages and click the New XPage button above the view of existing XPages (an empty list at this point). In the dialog box that appears (shown in Figure 11), name it "Home" or something similar.

On the Controls tab, open the Container Controls palette. Drag a Tabbed Panel control and drop it onto the XPage. Now go to the Tabbed Panel menu, which appears between the Create and Design menus, and choose Append Tab. On the Editor tab, you should now see three tabs within the Tabbed Panel.

On the Outline pane, expand the tabbed panel called "tabbedPanel1." You should see three tab panels listed as "tabPanel1-3." Click on each one and define the Name and Label values in the Properties tab in this manner:

On the Editor pane, select the Home tab, click on a spot in that empty panel, and type a greeting to your application. As you can see in Figure 12, my greeting is just a sentence because typing and adding fancy graphics isn't the object of this exercise; however, you can certainly add anything you like on your Home tab.

Next, go to the Add Books tab, click into it, and then drag a panel from the Container Controls palette onto the tab.

Switch to the Data tab, click on the Data Source drop-down item, and choose Define Data Source. Select Domino Document from the dialog. In the next dialog, select the Book form you created earlier.

Your data source, the Book form, should now appear in the Data tab as a listing all of the fields you created earlier. Select them all and drag the group of them onto the Panel control on the Add Books tab.

When you drop the group of fields onto the Panel control, Domino Designer creates a two-column table for you, with labels on the left and fields on the right. The fields are in alphabetical order by default; if this order is not appropriate, you would need to manually adjust the contents. (That is, insert rows from the Table menu, select the items you want to move, and cut and paste the row contents until you achieve the order desired.) Unfortunately, Domino Designer 8.5 and XPages don't support the Ctrl-Up and Ctrl-Down shortcuts that the Notes client provides users for moving entire table rows up and down quickly.

When you have the rows arranged in the Panel control, click on the DatePurchased field. Note how the Properties tab content changes; in it, select the Data tab. The Display Type should be Date/Time. Change the Display Format property to Date only and select the checkbox to use the date/time picker popup. This setting gives the field a Dojo-based calendar popup on the Web.

Next, in the Panel control, select the CoverImage field and delete it. To fill that empty table cell, go to the Core Controls palette on the Controls tab, drag a File Upload control and drop it into the cell. On the Data tab of the Properties tab below, bind the upload control to the CoverImage field. That's all you have to do in order to upload files that you've directly attached to a rich text field — you no longer have to use the legacy V2Attachment work-around that's necessary for Web development in earlier Domino releases.

The last change I want you to make to the Add Books tab is to drag a Button control from the Core Controls palette and drop it below the table. On the Properties tab, label it Save and change its Button Type to Submit. You may have trouble getting the button to stay on the Add Books tab, as it might appear below all three tabs. This is one of those times when the Outline is helpful. Find the button on the Outline, drag it up to the tabAddBooks Tab Panel and drop it there. Your XPage should now look something like Figure 13.

On your List Books tab in the editor, drag and drop a View control from the Container Controls palette. In the binding dialog box that appears, choose your Books view. If the View's width doesn't extend to cover the entire page, find the Width property on the View Properties tab below, where you can set the Units to Percent and the Width to 100.

Next, click on the Display Properties tab and select the "Show pager in footer" option. This option allows application users to navigate through the pages of the view without having to scroll back to the top of the page. The Display Properties tab also allows you to define the "Maximum rows per page" property.

When previewing this XPage on the Web from within Domino Designer, you can navigate using the different tabs, enter and save data about new books, and see your data appear in the listing. When you click the Save button to add data about a new book, the button action saves the Book document and presents you with a blank form to continue adding more book data. The application is not fancy, other than the Dojo calendar popup on the Date Purchase field and the fact that your view has an actual pager that works — but then it wasn't much work, was it?

I mentioned in the "Get Ready for XPages in Domino 8.5" article (November/December 2008) that Domino Designer 8.5 provides developers with a wide variety of built-in JavaScript libraries. The most immediately interesting ones to an experienced Domino developer are the ones named "Domino," which provides access to most of the back-end LotusScript objects, properties, and methods, and "@Functions," which allows you to use the formula language directly in XPages. I will describe these and other JavaScript libraries in depth in a subsequent article, but for now, to get the feel of how easy it is to incorporate these libraries into your Web pages, I focus on the simplest way to provide a list of field value choices to your users.

If you're anything like me, your library has lots of books by the same author. You can save users from retyping each repeated author name by enabling the type-ahead feature for the Author field. In Domino Designer, go back to your Add Books tab, select the Author edit box control, and look below at the Properties pane. Select the Type Ahead tab (visible in Figure 14) and click the Enable Type Ahead checkbox.

Then click on the diamond next to the Suggestions property and choose "Compute value." The dialog that appears allows you to write code to determine the values that will be suggested to the user as he or she begins to type in this field. If you guessed that one of the functions that the @Functions JavaScript library provides is an "@DbColumn" function, you are correct. Just type this JavaScript code into the Condition section and click OK:

@DbColumn("","Books",1)

As you probably surmise, this line simply looks up the Books view in the current database and retrieves the first column. At this point, if you (as an end user) preview the XPage and start typing in the Authors field, if you've saved Book documents with author names that begin with the same letters, you would see a list of author names that match the letters you've entered. The Minimum Characters is set to 1 (which is the default), so after each letter the user types, the list of possible matches narrows.

Note that if you have performance or network bandwidth concerns, you can delay the type-ahead feature until the end user types in a certain number of characters. Simply adjust the Minimum Characters property on the Type-Ahead tab.

You've probably noticed that there is no way to edit the Book documents you've added yet. To enable that functionality, start by adjusting the View control so that it displays links to the Book documents. Within the List Books tab, click on the Title column (not on the column header but somewhere in the column entries) and in the Properties pane, go to the View Column Properties tab, visible in Figure 15. Enable the "Show values in this column as links" option and make sure the "Document open mode" option below it is set to Edit. Save your XPage and preview it again to see that the titles are now links, albeit clicking on a link causes an error at this point.

The reason for the error is that you also need to specify an XPage for editing a Book document. The way Domino determines which XPage to use to edit a particular document is by comparing the form name to the available XPages and looking for a match. So, create a new XPage and call it "Book" (or whatever you named the form you created earlier).

You're going to copy some controls onto the new XPage from your existing XPage, and in order for the data bindings to continue to work, you need to create the same Data Source on the new XPage. Otherwise, you'd just have to define the data bindings on each field again. So before you do anything else, define a Data Source pointing to the Book form, in the same manner you did for the Add Book tab.

Once you've defined the Date Source, go back to the original Home XPage and select the Add Books tab in the editing pane. (The easiest way to accomplish this navigation task is to use the Outline panel.) Then open the Source tab in the editing pane. You should see some XML code, as in Figure 16. Using the Windows clipboard, copy and then paste this code onto the Source tab of the new Book XPage.

At this point, you have a working XPage, although you created an orphaned tabPanel element (since there's no parent Tabbed Panel on this XPage). To clean up the orphaned element, you can delete the following elements from the Source panel on the new XPage:

<xp:tabPanel id="tabAddBooks" label="Add Books">

and

</xp:tabPanel>

As you can see, the XML code in the Source pane includes special "xp:" tags, which provide the unique XPages functionality. When you edit in the Source pane, you change the raw XML code, which Domino Designer then matches visually in the design pane and in the outline. The exception is when you make an edit that's impossible to display in some way, in which case Domino Designer will display as much as it can in the other two areas. For example, it's possible to copy the XML representing a view column and paste it inside of another view column, but there is no valid visual representation for that.

Moving elements around in the design pane can also change the outline, and moving elements around in the outline can change their display in the design pane.

You know the application can upload files, but a user editing the Book XPage can't see the cover images yet because you still have to add a crucial File Download control to your Book XPage. Switch back to the Design pane and from the Core Controls palette, drag and drop a File Download control onto the Book XPage, immediately below the File Upload control. On the Properties tab for this control, choose the "Hide if no attachments" option. This option suppresses the Cover image field display if there are no images attached to that field. Then on the Data Properties tab, bind the control to the CoverImage rich text field. Now when users edit a book, they can see all of the document's attachments listed in the CoverImage field, neatly laid out as in Figure 17.

Your last design change to this XPage makes the Save button take the user back to the Home page after saving a Book document. In the editing pane, select the Save button, then choose the Events tab (see Figure 18), expand the Mouse vertical tab in the navigator on the left, and select the onClick event. Next, choose the Add Action button. In the dialog that opens above the Events pane, set the Action to Open Page and choose the Home XPage as the page to open.

Now you've configured your Save button to bring the user to the Home page. Click OK, save your XPage, and go back to the Home XPage. You can, once again, preview the simple application you've just built and see your changes in action.

Stay tuned — in my next XPages article, I'll show you the following:

This free article is part of THE VIEW Free Trial for Lotus Professionals. Subscribe here to receive many more articles like this one, plus new ones published every week at THE VIEW online knowledgebase.

This document is for your personal use only. Reproduction or distribution in any form is strictly prohibited without the permission of the publisher, Wellesley Information Services. For information about the THE UC VIEW, THE VIEW, and other WIS publications, visit www.WISpubs.com.