Mastering XPages: Beyond the View Basics

This chapter is from the book 

The View Control: Up Close and Personal

In this book, the View control is commonly referred to as the View Panel. This reference emanates from the markup tag used for the View control, i.e. <xp:viewPanel>, and it comes in handy when its necessary to disambiguate the view control from the backend Domino view that serves as its data source. In any case, the terms "View control" and "View Panel" can be used interchangeably and refer to the visual control that renders the view data.

The View Panel is a rich control with an abundance of properties and subordinate elements, such as pagers, columns, data sources, converters, and so on. Some of its properties are generic insofar as they are also shared by other controls in the XPages library to support common features like accessibility, internationalization, and so forth. For the most part, this chapter concentrates on the other properties as they are more directly relevant to view presentation, while the generic properties are addressed separately in other chapters.

In any case, the View Panel properties used in the examples up to now have been few in number and basic in nature. The upcoming examples start to pull in more and more properties in order to tweak the look and feel of your views. As usual, you learn these by way of example, but before you dive in, it is useful to summarize the View Panel features that have already been covered and provide the necessary reference points should you need to recap. The forthcoming material assumes that you are proficient with the topics listed in Table 9.1, although more detailed information may be provided going forward.

Table 9.1. viewPanel Features Previously Discussed

Feature	Chapter Reference: Section	Description
viewPanel Designer: Drag & Drop	Chapter 3: Building an XPages View	Creating a View control from controls palette Working with the view binding dialog
viewColumn property: displayAs	Chapter 3: Building an XPages View	Linking View control entries to underlying Notes/Domino documents
viewColumn property:showCheckBox	Chapter 3: Completing the CRUD	Making view entries selectable for executable actions
viewPanel <xp:pager>	Chapter 4: View	Basic description of View control with pager information
viewPanel property: facets	Chapter 4: Facets	General introduction to facets, including simple examples using view pagers
viewPanel Designer: appending columns	Chapter 8: Caching View Data	Adding a new column to a View control and computing its value using server-side JavaScript

Column Data Like You've Never Seen Before

So, start the next leg of this View Panel journey of discovery by creating a new XPage, say myView.xsp. Drop a View Panel from the control palette to view and bind it to the All Documents view when the helper dialog appears. Deselect all but three columns of the backend view—retain $106, $116, and $120. These are the programmatic names that have been assigned to the view columns; XPages allows you to use either the column's programmatic name or the view column title to identify the column you want to include in the View control. Not all view columns have titles, however! Click OK to create the View Panel.

When you preview this raw XPage, you see the Date and Topic fields as expected, along with what can best be described as some gobbledygook wedged in between those columns, as shown in Figure 9.2.

It is not unreasonable to question what exactly this $116 column represents. The formula behind the column in the backend view looks like this:

@If(!@IsResponseDoc;@DocDescendants(""; "%"; "%");"")

In the regular Notes client, this column displays the number of descendant documents for all root level documents. To decipher the code, the @DocDescendants function is only applied when !@IsResponseDoc evaluates to true, meaning when the current document is not a response document, or in other words, for top-level documents only. The "%" within the parameter strings are replaced with the actual number of descendant documents at runtime. According to the Help documentation, @DocDescendants is among a class of @Functions that are restricted in their applicability and cannot be run from web applications. The function is described as returning "special text," which is computed for client display only, not actually stored in the view, cannot be converted to a number, and so on. Other @Functions, such as @DocNumber and @DocChildren, present the same issues (you can find a more complete list in the Designer help pages). Designer itself attempts to preclude such columns from selection in the View Panel binding dialog, and the Java API getColumnValues() method, which is used to populate the View Panel row data, also tries to "null out" any autogenerated values that are contained in a row. However, these @Functions can be embedded in conditional logic and thus can be difficult to detect in advance. As a result, you might occasionally see spurious results like this appearing in views you are working on. So, what to do?

Because you cannot always work with all types of data contained in Domino views, you might need to create a modified version of a view in order to match your design criteria. Remember that the root of this problem is that the data defined in such columns is not actually contained in the backend view, but it is possible that the underlying documents have fields that hold the required information or perhaps the information you need can be deduced using one or more fields. Thus, you could modify the backend view or create a new version that contains the column values you require based on fetching or computing the information by alternative means.

In the more immediate short term, however, you need to remove the offending column from the View Panel. This can be done in Designer in a number of different ways. You can highlight the column in the Outline panel or in the WYSIWYG editor and use the right-mouse Delete menu to remove the column—you appended a new column back in Chapter 8, "Working with Domino Views," in much the same way. Alternatively, you can find the <xp:viewColumn> tag that is bound to $116 in the source pane and delete the markup directly from there.

Simple View Panel Make Over

Many presentational issues can be taken care of directly at the XPages level without any modifications to underlying the Domino view! For example, you are not restricted to the column order defined in the Domino view. You can reorder the columns in a View Panel by simply cutting and pasting the <xp:viewColumn> tags in the source pane—try this now in myView.xsp. Also, the date format of what is now or soon to be the second column can be modified in the XPages layer using a component known as a converter—this is the same component you used in Chapter 4, "Anatomy of an XPage," when working with the Date Time Picker examples. To do this, click the Date ($106) column in the WYSIWYG editor, select the Data property sheet, and change the Display type from "String" to "Date/Time." Then, change the Date style from "default" to "full," as shown in Figure 9.3.

Listing 9.1 shows the markup generated from the cut/paste operation and the addition of the date converter.

Listing 9.1. viewPanel Markup with Reordered Columns and Alternative Date Formatting

<xp:viewPanel rows="30"  id="viewPanel1">
      <xp:this.facets>
            <xp:pager partialRefresh="true"
                 layout="Previous Group Next"
                 xp:key="headerPager" id="pager1">
            </xp:pager>
      </xp:this.facets>
      <xp:this.data>
            <xp:dominoView
                  var="view1"
                  viewName="($All)">
            </xp:dominoView>
      </xp:this.data>
      <!-- Reordered columns so that Topic is first -->
      <xp:viewColumn columnName="$120" id="viewColumn7">
            <xp:viewColumnHeader value="Topic" id="viewColumnHeader7">
            </xp:viewColumnHeader>
      </xp:viewColumn>
      <xp:viewColumn columnName="$106" id="viewColumn1">
      <!-- Present full date like "Thursday, August 26, 2010" -->
           <xp:this.converter>
                 <xp:convertDateTime type="date" dateStyle="full">
                 </xp:convertDateTime>
           </xp:this.converter>
           <xp:viewColumnHeader value="Date" id="viewColumnHeader1">
           </xp:viewColumnHeader>
     </xp:viewColumn>
</xp:viewPanel>

Now that you've turned the view presentation on its head, you might as well look at its runtime rendition. All going well, you see a View Panel like the one shown in Figure 9.4.

You're not done yet, however! Albeit a simple View Panel, it is still possible to dress this puppy up a little further and add some extra behaviors.

The World Is Flat???

An obvious limitation of the View Panel shown in Figure 9.4 is that the document hierarchy is not shown. The Topic column is just a flat list of entries that does not reflect their interrelationships in any way. To show the various threads in this view, all you need to do is click the Topic column in Designer, select the Display property sheet, and check the Indent Responses control. Reload the page after doing this, and you find that all parent documents now have "twistie" controls that can be used to expand or collapse its own particular part of the document tree. If you don't like the standard blue twisties, feel free to add your own! Some extra images have been added as image resource elements to Chapter9.nsf, so if you want to try this feature out, you can simply assign minus.gif and plus.gif from the list of image resources in the application as the alternative twisties, as shown in Figure 9.5, although I'm sure you can come up with more interesting ones than these! Whatever alternative images are specified in this property sheet would also be applied to the twistie controls used for expanding and collapsing category rows, if you were working with a categorized view. Category views are discussed in the section, "Working with Categories."

Linking the View Panel to its Documents

In Chapter 3, you learned to use the Check box feature shown in Figure 9.5 to enable row selection by the end user. You also learned to display the contents of the Topic column as links and to bridge it to myTopic.xsp by explicitly nominating that XPage as pageName property for the View Panel itself. Select the Show values in this column as links feature for Topic column again now, but omit nominating myTopic.xsp as the target XPage on this occasion. Preview the page and click any link—do you know just why this happens to magically work?

The clue is in the View Panel's default link navigation option shown in Figure 9.6. When no page is explicitly nominated, XPages looks in the form used to create the underlying documents for a hint as to what XPage it should use. The form in question in this scenario is Main Topic and, if you open it in Designer and inspect its properties, you see a couple of interesting options, as highlighted in Figure 9.7.

You can basically choose to override the form associated with a document on the web and on the client by opting to substitute an XPage instead in either or both environments. For the purposes of this chapter only, Main Topic has been updated to use myTopic.xsp as an alternative on both platforms, and thus, it is resolved as the go-to XPage when a column is clicked in the View Panel.

There was originally just one Display XPage instead property. Since XPages was first made available on the web before being released on the Notes client, many customers converted their application's web implementation to XPages, but still had the original client application in place. When running the application natively on the client, they did not want to suddenly start seeing XPages appearing in place of forms! This feature was revamped in 8.5.2 to allow XPages and non-XPages implementations of an application to run harmoniously on separate platforms.

Although Display XPage instead certainly has its uses, the more common practice in the app dev community would appear to favor having an explicit XPage pageName navigation setting on the View Panel itself.

There is, in fact, a third strategy that can be employed to resolve what XPage is used when opening a document, and it is perhaps the simplest of them all! If you give the XPage the same name as the form used to create the document, it is chosen as a last resort if the other two options come up blank. This can be a useful approach if you are closely mimicking the original application implementation in XPages and if the application is simple enough to support such one-to-one design element mappings.

But, what of the remaining features in Figure 9.5? You just learned a second way to handle the Show values in this column as links option, and the Check box feature was already explored in Chapter 3. The Display column values checkbox merely serves to hide the column value retrieved from the view. This is potentially useful if you want to retrieve the column value but display something else based on what's actually contained in the column. In my experience, this property is not widely used as there are other (perhaps easier) ways of computing column values. We work through some examples of this shortly in the course of this View Panel makeover. On the other hand, if you simply want to conceal a column, you need to deselect the Visible checkbox in its property sheet, which sets rendered="false" in the underlying <xp:viewColumn> tag.

This just leaves the Icon and Content type in the view column Display panel, so you can learn now how to further enhance this simple makeover by putting those properties to work.

Decorating Your Columns with Images

Any column in a View Panel can display an image as well as its column value. To add an image to a view column, you can simply check the Icon control (refer to Figure 9.5 to find the control, if needed) and type the name of the image resource or use the image browser dialog to locate it. It is good practice to enter some alternative text in case the image cannot be resolved at runtime and to facilitate screen readers and so on. The view column properties behind these two Designer choices are called iconSrc and iconAlt, respectively. You can implement a simple example as follows:

1. Insert a new column before the first column in the View Panel. You can use the View > Insert Column main menu when the Topic column is selected.
2. Check the Icon checkbox in the Display property sheet and add /hash.gif as the nominated image resource (you can also browse for this image resource). This image has already been added to Chapter9.nsf for your convenience.
3. Add Index as the alternative text.
4. Add indexVar="rowIndex" to the <xp:viewPanel> tag in the Source pane. You can also do this via the View Panel's Data category in the All Properties sheet.
5. Add the following server-side JavaScript snippet to compute the column's value:

   var i:Number = parseInt(rowIndex + 1);
   return i.toPrecision(0);

In summary, you added an image to the new column and along with some alternative text. The indexVar property keeps a count of the rows in the View Panel as it is being populated. The indexVar property is used here as a simple row number to display in the UI. The JavaScript applied in step 5 simply increments each row index by 1 (it is a zero-based index) and ensures that no decimal places are displayed. Finally, to give the new column a title, click the view column header in the WYSIWYG editor and enter some text, say Row, as the label. Now, you can preview or reload the page to see the results (all this has been done for you in myViewExt.xsp, if you want to look at the final creation), which should closely match Figure 9.8.

This is all well and good except that the icon displayed is static in nature; observe that it is the same for each row (the hash symbol gif). Although it is a computable property, iconSrc does not have access to the View Panel var or indexVar properties, so it difficult to do something dynamic with it, such as select the image resource based on a particular row column value for example. This might be addressed in a future release.

But fear not, as a dynamic solution can still be provided by using the Content type option on the same Display panel. To implement an example of applying images based on row content, work through the following instructions:

1. Append a new column to the end of the View Panel using the View > Append Column main menu.
2. In the Display panel set the Content type to HTML.
3. In the Source pane, add var="rowData" to the <xp:viewPanel> tag to gain access to the current row via server-side JavaScript while the View Panel is being populated.
4. On the Data property sheet, add the following server-side JavaScript snippet to compute the column's value property:

   var i:number = rowData.getDescendantCount();
   if (i < 10) {
         return ("<img src=\"/Chapter9.nsf/" + i
                     + ".gif\""+">");
   } else {
         return ("<img src=\"/Chapter9.nsf/n.gif\""+">");
   }

5. Move to the Events tab for this column and for the only defined event, onclick, add another server-side JavaScript snippet:

   if (rowData.getDescendantCount() > 0) {
         rowData.toggleExpanded();
   }

As you can see, the column value is set using server-side JavaScript in step 4. An HTML image tag is returned with the src value determined by the number of documents in the row's document hierarchy, 1 descendant document means "1.gif" is used, 5 descendant documents means "5.gif" is used, and so on. Because you set the column's content type to HTML, the image tag is simply passed through to the browser as is. Moreover, the image is clickable (unlike the image added via the iconSrc property) and fires an expand/collapse event for any non-leaf entry, such as when the entry has any responses, thanks to the code you added in step 5.

The column header label should be set to Responses, and the content of the column can be quickly centered using the Alignment button on the column Font property panel. Reload the page and see the new runtime behavior for yourself. The rendering of this column is also shown in Figure 9.9. Note that the expandLevel=1 data source setting discussed in the previous chapter was used here (via a URL parameter) to initially collapse all rows. Some were then expanded to create a good example.

So, this time, the image resource in the Responses column indeed varies depending on the response count for each row entry. It might not be too evident in the printed screen shot, but the color of the images darken and increase in pixel size as the numbers increase. Thus, the rows with more responses get more emphasis in the UI (similar in concept to the tag cloud rendering) on the basis that they represent busier discussion threads and are, therefore, likely to be of more interest to forum participants. If the number of response documents exceeds nine, an ellipses image (n.gif) is shown instead. Add more documents yourself and create deep hierarchies to see how this View Panel rendering works in practice—interesting all the same to see what can be achieved by tweaking a few properties and adding some simple lines of JavaScript code!

Some Final Touches

Before completing our sample rendering of the All Documents view, there are some final miscellaneous features to apply and some other behaviors to observe. First, when used in native client mode, the backend All Documents view can be sorted by clicking the Date column. This sorting facility is not in evidence as yet in the XPages View Panel, so you must learn how to enable it.

The first thing to understand is that it is the backend view itself that performs the sorting. It is not performed client-side in XPages itself, and any attempt to do so is invariably inefficient and performs poorly as applications scale. Don't go there—leave the sorting operation to the view itself.

To enable the sort feature in the View Panel, you need to select the required view column header in the WYSIWYG editor and activate its property sheet. You see a Sort column checkbox that you need to check. If this is disabled, it means that the column as defined in the backend view does not have any sorting capability; Designer looks up the column design properties and enables or disables this option appropriately. Figure 9.10 shows the view column property that defines sorting capability.

If the column you want to sort in XPages is not defined, as shown in Figure 9.10, you need to either update the view design or create a new modified copy of the view to work with going forward. After the backend sort property and the XPages sort property are enabled, the View Panel displays a sort icon in the header and performs the sort operation when clicked by the user. Figure 9.11 shows the All Documents view after being resorted via the View Panel (oldest documents are now first).

Now complete this particular make over by selecting the View Panel and selecting its Display property sheet. Check the Show title and Show unread marks controls, and change the number of maximum number of rows from the default of 30 to 10. Figure 9.12 shows the property sheet with these changes applied.

Clicking Show title places a View Title component into the header of the View Panel. You can then click this component directly in the WYSIWYG editor and then set its label and other properties via the component's property sheet. This results in a <xp:viewTitle> tag being inserted into the View Panel facets definition; for example:

<xp:viewTitle xp:key="viewTitle" id="viewTitle1"
            value="All Documents - Make Over Complete!">
      </xp:viewTitle>

The View Panel also has a title property defined on the <xp:viewPanel> tag. This is merely exposing the title attribute of the underlying HTML table element that is used to construct the View Panel when rendered at runtime. If you enter a value for this property, it is passed through to the browser as part of the <table> HTML markup. For a visible view title, you need to use the Show title property and not this title property.

Secondly, if your unread view entries are not displayed as unread (no unread icon is displayed), this is most likely because the Domino server is not maintaining unread marks for the application—keeping track of read/unread documents is optional. You can ascertain the status of this feature in Designer via the Application Properties > Advanced property sheet. Look for the Maintain unread marks checkbox in the top-left corner.

The rows property that controls the maximum number of entries displayed in a view at any one time (set to 10) is exposed directly in the regular Discussion template UI. For example, the footer of the All Documents, By Tag, and By Author views conveniently lets the user choose the number of entries to display, as shown in Figure 9.13.

Listing 9.2 provides the entire View Panel markup, along with comments in case you had difficulty applying any of the many and varied features discussed in this section. It is also included in Chapter9.nsf in the myViewExt.xsp XPage.

Listing 9.2. View Panel: Complete Source for Make-Over Exercise

<xp:viewPanel rows="10" id="viewPanel1" var="rowData"
            indexVar="rowIndex" showUnreadMarks="true">
            <xp:this.facets>
                  <xp:pager partialRefresh="true"
                  layout="Previous Group Next"
                        xp:key="headerPager" id="pager1">
                  </xp:pager>
                  <!-- View Panel Title -->
                  <xp:viewTitle xp:key="viewTitle" id="viewTitle1"
                        value="All Documents - Made Over!">
                  </xp:viewTitle>
            </xp:this.facets>
            <xp:this.data>
                  <xp:dominoView var="view1" viewName="($All)">
                  </xp:dominoView>
            </xp:this.data>
            <!-- Static Column Image # -->
            <xp:viewColumn id="viewColumn3"
                  iconSrc="/hash.gif"
                  iconAlt="Row Number Symbol">
                  <xp:this.facets>
                        <xp:viewColumnHeader xp:key="header"
                              id="viewColumnHeader3" value="Row">
                        </xp:viewColumnHeader>
                  </xp:this.facets>
                  <!-- Compute Row Number -->
                  <xp:this.value><![CDATA[#{javascript:
                        var i:Number = parseInt(rowIndex + 1);
                        return i.toPrecision(0);}]]>
                  </xp:this.value>
            </xp:viewColumn>
            <!-- Reordered columns so that Topic is before Date -->
            <!-- Use custom twistie images for expand/collapse -->
            <xp:viewColumn columnName="$120" id="viewColumn7"
                  indentResponses="true"
                  collapsedImage="/plus.gif"
                  expandedImage="/minus.gif">
                  <xp:viewColumnHeader value="Topic"
                         id="viewColumnHeader7">
                  </xp:viewColumnHeader>
            </xp:viewColumn>
            <!-- Present full date like "Thursday, August 26, 2010" -->
            <xp:viewColumn columnName="$106" id="viewColumn1">
                        <xp:this.converter>
                              <xp:convertDateTime type="date" dateStyle="full">
                              </xp:convertDateTime>
                        </xp:this.converter>
                        <xp:viewColumnHeader value="Date"
                              id="viewColumnHeader1"
                              sortable="true">
                        </xp:viewColumnHeader>
                  </xp:viewColumn>
                  <!-- Dynamic Column Images – 1.gif thru 9.gif -->
                  <!-- inline CSS to center img -->
                  <xp:viewColumn id="viewColumn2"
                        contentType="HTML"
                        style="text-align:center">
                        <xp:this.facets>
                              <xp:viewColumnHeader xp:key="header"
                                    id="viewColumnHeader2" value="Responses">
                        </xp:viewColumnHeader>
                  </xp:this.facets>
                  <!-- Compute image name based on response count -->
                  <xp:this.value><![CDATA[#{javascript:
                        var i:number = rowData.getDescendantCount();
                        if (i < 9) {
                              return ("<img class=\"xspImageViewColumn\"
src=\"/Chapter9.nsf/" + i + ".gif\""+">");
                        } else {
                              return ("<img class=\"xspImageViewColumn\"
src=\"/Chapter9.nsf/n.gif\""+">");
                        }
                        }]]></xp:this.value>
                  <!-- Do collapse/expand for docs with responses -->
                  <xp:eventHandler event="onclick" submit="true"
                        refreshMode="complete" id="eventHandler1">
                        <xp:this.action><![CDATA[#{javascript:
                              if (rowData.getDescendantCount() > 0) {
                                    rowData.toggleExpanded();
                        }
                        }]]></xp:this.action>
                  </xp:eventHandler>
            </xp:viewColumn>
</xp:viewPanel>

Working with Categories

Just like sorting, categorization is handled by the backend view itself and not by XPages. For a column to be treated as a category, the column type must be set to Categorized in the view column properties infobox; refer to the Type radio button option show in Figure 9.10, which allows columns to be defined as Standard or Categorized.

The View Panel merely presents category rows and columns and renders them so they can be expanded and collapsed as required. The expansion and contraction of category rows works the same as it does for indented responses. Note also that the state of both category rows and document hierarchies is maintained as you navigate through the view data. For example, as part of the final make over, you restricted the number of rows presented in the View Panel to ten elements (remember rows="10"). This caused more pages to be displayed in the view pager contained in the header. If you expand and collapse some categories or response hierarchies on any given View Panel page and then navigate forward and backward via the pager, you find that the display state of these rows is maintained and then redisplayed on your return exactly as you had left them. This statefulness is a great built-in feature of XPages and something often lacking in other web applications...try the same view navigation exercises using the classic Domino web engine.

In any case, categorization becomes more interesting when two or more category columns are in a view. To provide some working examples of this, a modified form and view were added to Chapter9.nsf, namely the Main Topic2 form and the subCats view. A small number of documents with multiple categories have also been created in the sample application so that examples can be quickly constructed. You do not see these documents in the All Documents view because the view selection formula on the ($All) view only displays documents created using the Main Topic form, and thus excludes those created using Main Topic2. Figure 9.14 shows the sample multicategory documents when the subCats view is previewed in the client.

Figure 9.15 shows an XPage named subCat1.xsp, which is a default rendering of the subCats view. By "default rendering," I mean that a View Panel control was simply dropped on an XPage and all the columns in the subCats view were accepted for inclusion—nothing more than that.

If you experiment with the XPages View Panel and the Notes view, you find that the presentation and behavior of both are identical. The category columns are automatically rendered as action links with twistie icons, both of which serve to expand and collapse the category row. Apart from this specialized behavior, all the regular column properties described thus far can also be applied to category columns, they can be reordered within the View Panel so they are not contiguous, and so on.

Although adding two or more categorized columns to a view is one way of implementing subcategorization, an alternative method seems to be a common practice. That is, instead of having multiple categorized columns in the view, which map to fields in the underlying form, the view has just one category column but it can support multiple categories through the use of a "category\subcategory" data-format notation. Thus, if a user enters something like "Government" as a category value, this is interpreted as a top-level category. However, if "Government\Recycling" is entered by the user into the Categories field when creating a document, the document is categorized in a "Recycling" subcategory within the top-level "Government" category.

To provide an example of this, an alternative sample NSF is provided for this chapter, namely Chapter9a.nsf. Some of the sample documents contained in Chapter9.nsf have been recategorized in the manner just described (which is why you need a separate database). Figure 9.16 shows an example of a redefined category field as inspected in a Notes infobox and how these updated documents are displayed in the Notes client.

Observe that the Notes client view indents the new subcategories tucked in under the main categories. You have little or no control over this particular rendering because it is built-in view behavior. However, if you repeat the exercise described for Figure 9.15 and create an XPages View Panel to do a default rendering of this view, you notice a problem (refer to subCatsA.xsp in Chapter9a.nsf for convenience). As shown in Figure 9.17, XPages recognizes the entries as category columns, but the subcategories are not indented. The next section describes how to address this.

Making It Look Like Notes!

Building an XPage to emulate the Notes client rendering can be achieved in the following eight steps:

1. Create a new XPage called subCatsB.xsp and add a View Panel from the palette.
2. Bind to the By Category view but only include the Topic column.
3. As shown earlier, insert a new column before the Topic column and give it a title of "Categories" by updating the view column header.
4. In the Display panel set the Content type to HTML.
5. Add var="rowData" to the <xp:viewPanel> tag to gain access to the current row via server-side JavaScript while the View Panel is being populated.
6. Add the following server-side JavaScript snippet to compute the column's value:

   if (rowData.isCategory()) {
         // Use the standard twistie icons
         var src =
          "/xsp/.ibmxspres/global/theme/common/images/expand.gif";
          // Get the value of the Categories column
          var colValue = rowData.getColumnValue("Categories");
         // Return "Not Categorized" for null or undefined data
          if (typeof colValue == 'undefined' ||
              colValue == null) {
                colValue = "Not Categorized";
          }
          // Invert the twistie depending on row state
          if (rowData.isExpanded()) {
          src =
          "/xsp/.ibmxspres/global/theme/common/images/collapse.gif";
          }
          // return the <span> tag including the twistie & value
          return "<span style='cursor:pointer'><img src='" +
                src + "' alt='' class='xspImageViewColumn'/>" +
                colValue + "</span>";
   }

7. Add the following server-side JavaScript snippet to compute the column's style property, i.e. All Properties > Styling > Style > Compute value:

   if (rowData.isCategory()) {
         // This API tells us if a category column is indented
         var indent = rowData.getColumnIndentLevel();
         // Insert padding for each indent level
         if (indent == null || indent == 0) {
               return "padding-left:0px";
         } else {
               return "padding-left:10px";
         } // continue if deeper category levels exist ...
   };

8. Move to the Events tab for this column and for the only defined event, onclick, add another server-side JavaScript snippet:

   rowData.toggleExpanded();

The subCatsB.xsp XPage has already been created for you in Chapter9a.nsf, so you can load this or preview your own creation if you have worked through the steps above. In either case the results you see should match those shown in Figure 9.18.

The key pieces to the customized category column shown in Figure 9.18 are achieved using server-side JavaScript. Obviously, the NotesXspViewEntry class exposed via the rowData object is critical when working on view customizations as it gives full programmatic access to each view row as it is rendered. This JavaScript class is a pseudo class for the DominoViewEntry Java class defined in the XPages runtime, which, in turn, wraps the ViewEntry class defined in Notes Java API. JavaScript pseudo classes such as this one allow you to access the associated Java class without having to enter the entire package name, and have an automatic built-in type-ahead facility for method names when used in the JavaScript editor. In this example, for each row it allows you to

• Check if the row is a category: rowData.isCategory()
• Get the column value: rowData.getColumnValue("Categories")
• Check the expand/collapse state of the row: rowData.isExpanded()
• Check for embedded categories: rowData.getColumnIndentLevel()
• Toggle the expand/collapse state of the row: rowData.toggleExpanded()

Appendix A, "XSP Programming Reference," includes documentation resources that provide a full outline of the DominoViewEntry XPages class, which NotesXspViewEntry uses under the covers. It is worthwhile to study this class in more detail to get to know the full set of tools you have at your disposal when working on view customizations. You can also resolve the mappings for any JavaScript/Java classes using a handy tool on the Domino Designer wiki:

www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_Domino_Object_Map_8.5.2

The other interesting tidbit from this example is that it exposes the internal URLs used to locate embedded runtime resources like images, style sheets, and so on. The following URL, for example, points to the standard row expansion twistie that is part of the XPages runtime:

"/xsp/.ibmxspres/global/theme/common/images/expand.gif"

You see URLs just like this one whenever you view the source of a rendered XPage in a browser, and you can use these URLs as has been done in this example as part of your own customizations.

Incidentally, a similar technique can be used to render category view columns inline like this, even when they are managed as separate category columns, i.e. as was the case with the subCats view used in Chapter9.nsf, shown in Figure 9.14. A subCats2.xsp XPage has been included in that sample application to illustrate how to reformat the column category display. In essence, however, it is only the server-side JavaScript code outlined previously in steps 6 and 7 that has been modified. Listing 9.3 shows the revised code that computes the column value and the style property.

Listing 9.3. Server-Side JavaScript for View Column value and style Properties

<xp:this.value>
      <![CDATA[#{javascript:if (rowData.isCategory()) {
      // Use the standard twistie icons
      var src = "/xsp/.ibmxspres/global/theme/common/images/expand.gif";
      // Look for the deepest subcategory first
      var colValue = rowData.getColumnValue("SubCategories")
      // If not found, keep looking back until back to top level cat
      if (colValue == null) {
        colValue = rowData.getColumnValue("Categories");
      }
              // Return "Not Categorized" for null or undefined data
      if (typeof colValue == 'undefined' || colValue == null) {
        colValue = "Not Categorized";
      }
      // Invert the twistie depending on row state
      if (rowData.isExpanded()) {
        src = "/xsp/.ibmxspres/global/theme/common/images/collapse.gif";
      }
      // return the <span> tag including the twistie & value
      return "<span style='cursor:pointer'><img src='" + src +
                  "' alt='' class='xspImageViewColumn'/>" + colValue +
                  "</span>";
                  }}]]>
</xp:this.value>
<xp:this.style>
      <![CDATA[#{javascript:
      if (rowData.isCategory()) {
         // Start at the deepest subcategory and work back to root
         var colValue = rowData.getColumnValue("SubCategories");
         // Insert padding for 10 pixel padding for 2nd column
         if (colValue != null && colValue != "") {
             return "padding-left:10px";
         // Insert more padding if needed back to the top level
          } else {
            return "padding-left:0px";
         }
      }}]]>
</xp:this.style>

As you can see from the code, the principle is exactly the same as previously, but the means of detecting the category columns has changed. No longer are the column values embedded in the Category\Subcategory fashion, so the rowData.getColumnIndentLevel() API is of no use here. Instead, the indentation is determined based on the structure of the backend view—the deepest subcategory columns are sought first, rewinding to the top level if no value is found. Load the subCats2.xsp page and compare the results to Figure 9.15.

This tucked-in form of category styling seems popular in the community based on various Notes app dev forum postings and other customer feedback, so hopefully this section clarified how to achieve the Notes client look and feel in XPages. It might become a standard View Panel property in a future release.

View Properties and View Panel Properties

When working with views, any features to do with data structure and content are defined at the backend in the view design element itself—you have just seen with this with the sorting and categorization examples, insofar as these capabilities needed to be enabled in the view. The view design element also contains properties that are purely related to presentation within the Notes client or classic web engine and, as such, do not apply to the XPages view controls. For example, the Type option in Figure 9.10 defines whether a categorization data is maintained for a particular column in the view, but the twistie options contained in the adjacent tab (see Figure 9.19) only apply to native Notes rendering and not to XPages.

It is important to be able to distinguish the native view rendering features from the XPages View control presentation properties. In Chapter9.nsf a new version of the ($xpByAuthor) view, namely ($xpByAuthorExt), has been provided for use in an example that helps clarify this area. The extended view contains an extra column that totals the byte size of the documents for each category. These totals are shown in the Notes client for each category only, but can be displayed for each individual row entry if so desired. The hide/show nature of this data is determined using the Hide Detail Rows checkbox shown in Figure 9.20.

If you toggle the Hide Detail Rows checkbox value and refresh the view data from within Designer, you see the document byte size displayed for each entry. An agent has also been supplied in the sample application, which prints the column values for each view row entry using the Java API. The agent (getViewEntryData) details are shown in Listing 9.4.

Listing 9.4. Java Agent to Print View Column Data

import lotus.domino.*;
public class JavaAgent extends AgentBase {
    public void NotesMain() {
      try {
          // Standard agent code to get session & context objects
          Session session = getSession();
          AgentContext agentContext = session.getAgentContext();
          // get the current db and the new ($xpByAuthorExt) view
          Database db = session.getCurrentDatabase();
          View view = db.getView("($xpByAuthorExt)");
          // iterate over each view entry and print the Topic & Size
          ViewEntryCollection vec = view.getAllEntries();
          if (vec != null) {
                for (int i = 0; i < vec.getCount(); i++) {
                      ViewEntry ve = vec.getNthEntry(i);
                      if (ve != null)
                     // just get the 3rd & 4th column values
                     // ViewEntry index is zero-based!
                       System.out.println(
                          ve.getColumnValues().get(2)
                          + " " +
                       ve.getColumnValues().get(3) );
                }
            }
        } catch(Exception e) {
            e.printStackTrace();
        }
    }
}

Listing 9.5 shows some sample output generated when the ($xpByAuthorExt) view is configured to hide detail rows. To run the agent yourself in Designer, you first launch the Java debug console (Tools > Show Java Debug Console), right-click getViewEntryData in the agent view, and select the Run menu. All the println output then appears in the Java console. As you can see, the detail totals rows are all included in the data returned by the getColumnValues() API call regardless of Hide Details Rows property setting.

Listing 9.5. Snippet of Java Agent Output

...
if you can rip it, you can recycle it (re: It's just paper) 573.0
It's just paper 618.0
Using post-consumer recycled paper 1045.0
who't this? (re: Meeting Minutes) 629.0
phone number inside (re: Meeting Minutes) 631.0
Difference between clear and colored glass? 927.0
...

Because XPages depends on the Java API to populate its View control, the detail rows appear in any XPages View control that includes the Size column. The Hide Detail Rows property is really just used in the core view rendering code and not honored in the programmability layer. Given the view customization tips and tricks you have learned thus far, you are now be in a position to figure out how to emulate Notes Hide Detail Rows view display property in XPages! All you really need to do is not show the Size column value when the row is not a category. This is done for you in hideDetails.xsp page in Chapter9.nsf, which contains a View Panel with four standard columns (Name, Date, Topic, Size) plus a computed column. The server-side JavaScript used to compute the column value is trivial, as demonstrated in Listing 9.6.

Listing 9.6. Server-Side JavaScript Snippet to Emulate Hide Detail Rows in a View Panel

<xp:this.value>
<![CDATA[#{javascript:
      // Only show the Total column value for category rows
      if (rowData.isCategory()) {
            return rowData.getColumnValue("Size");
}}]]></xp:this.value>
<!-- Also include a converter to display whole numbers only -->
<xp:this.converter>
      <xp:convertNumber type="number"
            integerOnly="true">
      </xp:convertNumber>
</xp:this.converter>

The converter just used was added via the same Data property panel used to add the JavaScript code in Designer. Simply set the Display type to Number and check the Integer only control to eliminate the decimal points you see printed in the raw data in Listing 9.5. When loaded or previewed, the hideDetails XPage looks like Figure 9.21.

The discussion thus far covered all the main View Panel properties and dived into examples of how to customize View Panels using server-side JavaScript and other tools. The next most logical focus area for the View Panel would be styling. No doubt, as you have examined the View Panel properties, you noticed a slew of specialized style class properties (rowClass, columnClass, viewClass, and so on), which can modify its appearance. Rather than do that here in this chapter, it is covered in the section, "Working with Extended styleClass and Style Properties," in Chapter 14, "XPages Theming." The discussion here instead shifts to the Data Table container control.