Mastering XPages: Beyond the View Basics
Because the preceding chapter concentrated exclusively on the gory details of data retrieval from Domino views, it's only fitting that this chapter focuses on the fine art of presenting view data in XPages. Once again, a modified version of the Discussion template is used as the sample application. In fact, for this chapter, you need two samples, namely Chapter9.nsf and Chapter9a.nsf. You need to download these resources now from the following website and load them up in Domino Designer so that you can work through all the examples provided: www.ibmpressbooks.com/title/9780132486316.
XPages provides three standard controls for presenting Domino view data, namely the View, Repeat control and Data Table. You will find all three on the Container Controls section of the palette in Designer. You have already done some work with these controls, mostly with the View control, although you have only used the basic properties up until now. You will see here how to put some of the lesser known properties to good use to solve some more advanced use cases. Perhaps it is best to start, however, with an explanation of why there are three different view presentation controls in the first place!
Pick a View Control, Any View Control
When it comes to presenting view data, we all have our individual preferences! For some use cases, a view with a strictly tabular format where rows and columns crisscross to form a rigidly ordered grid layout is what's required. In other scenarios, a more free-form view layout of summary information that allows end users to dynamically dive deeper into the underlying data is the order of the day. In terms of providing off-the-shelf controls to meet these demands, no one-size-fits-all solution exists. In other words, separate specialized renderers are required to handle what are wildly different layout requirements, and each renderer has its own unique set of properties and behaviors that cater to those particular use cases.
Rather than simply describing various alternative view layouts, it is useful for you to see real-world use cases firsthand. As usual, the sample application can be readily called upon to demonstrate different view presentation examples. For example, explore the All Documents view on the main page of the application, and then compare its look and feel to one of the other views in the main navigator, such as By Tag, By Author, By Most Recent, and so on. Some key differences should come to your attention immediately. Chief among these is the interesting capability of the All Documents view to dynamically expand and collapse row content inline. That is, as you hover over any particular row, you are presented with More and Hide links, depending on the current state of the row content. If the row is collapsed, clicking the More option effectively injects an extra row of detail into your view, showing an abstract of the underlying document and presenting options to compose a reply or to switch to a view of documents that contain the same tags. Figure 9.1 summarizes this feature.
Figure 9.1 Sample Discussion application using repeat control to render all documents view
The other views do not have this capability and instead display content on a strict one-document-per-row basis. The data in these views is typically organized according to a specific criterion, say by category, author, or date, and feature the standard document link navigators for some of the columns in each row. You will no doubt recognize these behaviors as built-in properties of the View control, and you have already implemented a view sample similar to these in Chapter 3, "Building Your First XPages Application." That first sample demonstrated that you could build simple views using a View control in a matter of minutes. Although it also is possible to build sophisticated view renderings with the View control (as you'll soon see), there are some things it is simply not designed to do—dynamic inline row insertion/deletion being a case in point.
The fancy dynamics shown in Figure 9.1 are achieved using a Repeat control. This container control iterates or "repeats" over every row in the view data source to which it is bound. Any control that is added to the Repeat container (by default it is empty) can be bound to a column in the backend view. The iterative read cycle that occurs at runtime then ensures that all contained controls display the appropriate column value once for every row in the view. Thus, you have a totally free-form means of laying out view data, where nothing is predefined but anything is possible. The presentation content is totally dependent on the controls you choose to add to the Repeat container. It is not required to be structured within an HTML table for example—something you are stuck with when using the View control or Data Table controls whether you like it or not. Also, Repeat controls can be nested within each other, meaning that different data sources can be navigated as part of one overall view presentation.
All this, of course, means the Repeat control is an incredibly powerful and flexible tool for displaying view data—that's the upside! The downside is that you must define all the content and layout data yourself; in other words, it can be a lot of work depending on what you want to achieve. The View control, on the other hand, is somewhere toward the other end of the scale—a View control can be built quickly using easy point-and-click operations, but the end result is more restrictive than is the case with a Repeat control. Again, depending on what you want to achieve, the View control may be the correct instrument to use—a simple case of choosing the right tool for the right job!
To see how the various view controls have been employed in the Discussion template, you can search the Discussion template for the tags xp:viewPanel, xp:repeat and xp:dataTable (in Designer, type Ctrl-H and specify the literal tags in the File Search tab, as shown in the previous chapter). The View control is used in all the aforementioned XPages (By Tag, By Author, By Most Recent) and in AuthorProfileView.xsp. If a user has registered a profile in the application, the Author Profile custom control is one of three views displayed when the user's name is picked from the author cloud. The Repeat control is used for the All Documents page, the presentation of both the tag and author clouds (as shown in Figure 9.1), and to build the response document chain displayed when editing a document that is contained in a hierarchy.
Interestingly, although perhaps not surprisingly, the search for xp:dataTable results in no hits—at least this is true in the out-of-the-box template; however, you can find matches in Chapter9.nsf because a Data Table example has been added for your convenience. The absence of the xp:dataTable tag from the Discussion template and from most other real-world application (at least in this author's experience) is because it offers neither the convenience of a View control nor the flexibility of a Repeat control. In essence, it is like a limited version of both controls and, thus, tends to be left out in the cold when it comes to more sophisticated application development scenarios. It is, however, useful for prototyping and for simple use cases, and we examine a sample Data Table later in this chapter. First, however, it's time to take a closer look at the intricacies of the View control.