XPages Data Views – Part 2: Creating a Data View

In the first part of this series, we talked about the Data View control and it’s features at a high level. In this post, we’ll see how to create a minimal data view. We’ll then look at how to compute the summary column and add extra columns and categorization.

Data View Design – Key Point

The most important thing to understand with the data view is that, in it’s default layout, it revolves around a single piece of information called the Summary Column.

Before you can create an effective data view, you need to know what the summary will be. The summary is the main link that opens the document and it’s the primary piece of information that identifies the document. It can be a single column from the underlying view or it can be a computed value that combines multiple pieces of information.

Minimum Steps to Create a Data View

At minimum, the Data View control needs a data source and a summary column.

In its simplest form, you can create a data view with 3 steps:

1. Add a Data View control to the page (under Extension Library)

2. Set the data source. You can do this at the time you drag and drop or later in the Data subtab of the Data View properties.

3. Set the Summary column. All Properties > format > summaryColumn < + (then enter the columnName)

Now I have a Data View. It isn’t terribly useful yet, but it is a list of active links that will open the documents.

The example shown here uses data from David Leedy’s FakeNames database. I have a view with a column that combines the first and last name into a single column, called fullname.

If your view has more documents than the data view is configured to display (via the rows property), you can drag and drop a pager control into one of the pager facets on the data view. (We’ll take a look at another method of navigation later in the series.)

I combined the first and last name fields in an underlying view column, so I could easily use that single column as the summary.

Column Names

The Data View does not provide a method of selecting the column name — you need to type it in manually. (This goes for all Data View column names.)

The name must match the programmatic name of the underlying view column. For columns that display a single field, it will generally be the name of the field. For computed columns, it will generally start with $ and end with a number.

In my example, I created a computed column, but changed the programmatic name of the column to something that was easy to remember.

Document Links

The column value defined as the summary will automatically be activated as a link that will open the document.

By default it will use the XPage associated with with document’s form, but you can change that to specify the page to use in the Data View properties.

Computed Summary Value

If you need to compute the summary value (because you don’t have a single view column that uniquely identifies the data well enough), you can compute the value of the summary column.

First you need to set the var property of the data view in order to have a handle to the underlying view entry.

Then you can compute the value with SSJS in the value property of the summary column.

return dvEntry.getColumnValue('fullname') + ', ' + dvEntry.getColumnValue('occupation');

Now, the data view displays a summary that combines the person’s name and occupation.

Note: If you set both the columnName and value properties of the summaryColumn, the computed value will take precedence.

Extra Columns

We have a working data view, but what we’ve provided so far generally isn’t going to be enough information when used in a full browser. (On a mobile device, a summary column is sufficient.)

To add a few more pieces of information, we can add Extra Columns to the data view.

You add them under All Properties > format > extraColumns. You can click on the plus (+) button to add a column and then manually set the columnName property. In this example, I’ve added the phone number and birthday.

Here is the result:

As you can see, extra columns are right-justified on the screen.

The data view is not designed to display a bunch of columns like a regular view panel, so use extra columns judiciously.

Column Titles

You can add column titles by setting the Show column titles property of the data view and setting the columnLabel property on each column. Personally, I think they look good in this type of layout, but the option is there if you need them.

Styling Provided by OneUI

The Data View is designed to work with OneUI. You can certainly add your own styling with the provided class properties, but you get a much nicer look
and feel out of the box if you’re using a OneUI theme, which the preceding examples show.

Here’s the same data view as the previous screen shot, but without a OneUI theme in place.

Categorization

Another useful feature that the Data View provides (and most other controls don’t) is the ability to display categorized views.

All you have to do is go to All Properties > format > categoryColumn and click the plus (+) button to add a category column. Then manually enter the
categorized column name from the underlying view.

In my example, I have switched the data view to display a view categorized by state. Here is the result:

You can have multiple levels of categorization, provided the underlying view supports that categorization.

Up Next

In the next post I’ll demonstrate the feature that I think makes the Data View control truly great — the collapsible Detail section.